add docs initial structure

Author: lesnik512

docs/css/code.css

@@ -0,0 +1,10 @@
+/* Round the corners of code blocks */
+.md-typeset .highlight code {
+  border-radius: 10px !important;
+}
+
+@media (max-width: 600px) {
+  .md-typeset code {
+    border-radius: 4px;
+  }
+}

docs/dev/contributing.md

@@ -0,0 +1,19 @@
+# Contributing
+This is an opensource project, and we are opened to new contributors.
+
+## Getting started
+1. Make sure that you have [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/) installed.
+2. Clone project:
+```
+[email protected]:modern-python/modern-di.git
+cd modern-di
+```
+3. Install dependencies running `just install`
+
+## Running linters
+`Ruff` and `mypy` are used for static analysis.
+
+Run all checks by command `just lint`
+
+## Running tests
+Run all tests by command `just test`

docs/dev/decisions.md

@@ -0,0 +1,13 @@
+# Decisions
+1. Dependency resolving is async and sync:
+  - if resolving requires event loop in sync mode `RuntimeError` is raised;
+  - framework was developed mostly for usage with async python applications;
+  - sync resolving is also possible, but it will fail in runtime in case of unresolved async dependencies;
+2. Resources and singletons are safe for concurrent resolving:
+  - in async resolving `asyncio.Lock` is used;
+  - in sync resolving `threading.Lock` is used;
+3. No global state -> all state lives in containers:
+  - it's needed for scopes to work;
+4. Focus on maximum compatibility with mypy:
+  - no need for `# type: ignore`
+  - no need for `typing.cast`

docs/index.md

@@ -0,0 +1,22 @@
+# Modern DI
+
+Welcome to the `lite-bootstrap` documentation!
+
+`lite-bootstrap` assists you in creating applications with all the necessary instruments already set up.
+
+With `lite-bootstrap`, you receive an application with lightweight built-in support for:
+- `sentry`
+- `prometheus`
+- `opentelemetry`
+- `structlog`
+- `cors`
+- `swagger` - with additional offline version support
+- `health-checks`
+
+Those instruments can be bootstrapped for:
+- `fastapi`,
+- `litestar`,
+- `faststream`,
+- services without these frameworks.
+
+---

docs/integrations/fastapi.md

@@ -0,0 +1,100 @@
+# Usage with `Fastapi`
+
+*More advanced example of usage with FastAPI - [fastapi-sqlalchemy-template](https://github.com/modern-python/fastapi-sqlalchemy-template)*
+
+## How to use
+
+1. Install `modern-di-fastapi`:
+
+=== "uv"
+ 
+      ```bash
+      uv add modern-di-fastapi
+      ```
+ 
+=== "pip"
+
+      ```bash
+      pip install modern-di-fastapi
+      ```
+
+=== "poetry"
+
+      ```bash
+      poetry add modern-di-fastapi
+      ```
+
+2. Apply this code example to your application:
+```python
+import datetime
+import contextlib
+import typing
+
+import fastapi
+import modern_di_fastapi
+from modern_di import Scope, providers
+
+
+app = fastapi.FastAPI()
+modern_di_fastapi.setup_di(app)
+
+
+async def create_async_resource() -> typing.AsyncIterator[datetime.datetime]:
+    # async resource initiated
+    try:
+        yield datetime.datetime.now(tz=datetime.timezone.utc)
+    finally:
+        pass  # async resource destructed
+
+
+async_resource = providers.Resource(Scope.APP, create_async_resource)
+
+
+@app.get("/")
+async def read_root(
+        instance: typing.Annotated[
+            datetime.datetime,
+            modern_di_fastapi.FromDI(async_resource),
+        ],
+) -> datetime.datetime:
+    return instance
+
+```
+
+## Websockets
+
+Usually our application uses only two scopes: `APP` and `REQUEST`.
+
+But when websockets are used, `SESSION` scope is used as well:
+- for the lifetime of websocket-connection we have `SESSION` scope
+- for each message we have `REQUEST` scope
+
+`APP` → `SESSION` → `REQUEST`
+
+`SESSION` scope is entered automatically.
+`REQUEST` scope must be entered manually:
+
+```python
+import typing
+
+import fastapi
+import modern_di
+import modern_di_fastapi
+
+
+app = fastapi.FastAPI()
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(
+    websocket: fastapi.WebSocket,
+    session_container: typing.Annotated[modern_di.Container, fastapi.Depends(modern_di_fastapi.build_di_container)],
+) -> None:
+    with session_container.build_child_container() as request_container:
+        # REQUEST scope is entered here
+        pass
+
+    await websocket.accept()
+    await websocket.send_text("test")
+    await websocket.close()
+```

docs/integrations/faststream.md

@@ -0,0 +1,62 @@
+# Usage with `FastStream`
+
+## How to use
+
+1. Install `modern-di-faststream`:
+
+=== "uv"
+
+      ```bash
+      uv add modern-di-faststream
+      ```
+
+=== "pip"
+
+      ```bash
+      pip install modern-di-faststream
+      ```
+
+=== "poetry"
+
+      ```bash
+      poetry add modern-di-faststream
+      ```
+
+2. Apply this code example to your application:
+
+```python
+import datetime
+import typing
+
+import faststream
+from faststream.nats import NatsBroker
+import modern_di_faststream
+from modern_di import Scope, providers
+
+
+broker = NatsBroker()
+app = faststream.FastStream(broker=broker)
+modern_di_faststream.setup_di(app)
+
+
+async def create_async_resource() -> typing.AsyncIterator[datetime.datetime]:
+    # async resource initiated
+    try:
+        yield datetime.datetime.now(tz=datetime.timezone.utc)
+    finally:
+        pass  # async resource destructed
+
+
+async_resource = providers.Resource(Scope.APP, create_async_resource)
+
+
+@broker.subscriber("in")
+async def read_root(
+    instance: typing.Annotated[
+        datetime.datetime,
+        modern_di_faststream.FromDI(async_resource),
+    ],
+) -> datetime.datetime:
+    return instance
+
+```

docs/integrations/litestar.md

@@ -0,0 +1,88 @@
+# Usage with `Litestar`
+
+*More advanced example of usage with LiteStar - [litestar-sqlalchemy-template](https://github.com/modern-python/litestar-sqlalchemy-template)*
+
+## How to use
+
+1. Install `modern-di-litestar`:
+
+=== "uv"
+
+      ```bash
+      uv add modern-di-litestar
+      ```
+
+=== "pip"
+
+      ```bash
+      pip install modern-di-litestar
+      ```
+
+=== "poetry"
+
+      ```bash
+      poetry add modern-di-litestar
+      ```
+
+2. Apply this code example to your application:
+```python
+import datetime
+import typing
+
+from litestar import Litestar, get
+import modern_di_litestar
+from modern_di import Scope, providers
+
+
+async def create_async_resource() -> typing.AsyncIterator[datetime.datetime]:
+    # async resource initiated
+    try:
+        yield datetime.datetime.now(tz=datetime.timezone.utc)
+    finally:
+        pass  # async resource destructed
+
+
+async_resource = providers.Resource(Scope.APP, create_async_resource)
+
+
+@get("/", dependencies={"injected": modern_di_litestar.FromDI(async_resource)})
+async def index(injected: datetime.datetime) -> str:
+    return injected.isoformat()
+
+
+app = Litestar(
+    route_handlers=[index],
+    plugins=[modern_di_litestar.ModernDIPlugin()],
+)
+```
+
+## Websockets
+
+Usually our application uses only two scopes: `APP` and `REQUEST`.
+
+But when websockets are used, `SESSION` scope is used as well:
+- for the lifetime of websocket-connection we have `SESSION` scope
+- for each message we have `REQUEST` scope
+
+`APP` → `SESSION` → `REQUEST`
+
+`SESSION` scope is entered automatically.
+`REQUEST` scope must be entered manually:
+
+```python
+import litestar
+import modern_di
+import modern_di_litestar
+
+
+app = litestar.Litestar(plugins=[modern_di_litestar.ModernDIPlugin()])
+
+
+@litestar.websocket_listener("/ws")
+async def websocket_handler(data: str, di_container: modern_di.Container) -> None:
+    with di_container.build_child_container() as request_container:
+        # REQUEST scope is entered here
+        pass
+
+app.register(websocket_handler)
+```

docs/introduction/application-settings.md

@@ -0,0 +1,24 @@
+# Application settings
+For example, you have application settings in `pydantic_settings`
+```python
+import pydantic_settings
+
+
+class Settings(pydantic_settings.BaseSettings):
+    service_name: str = "FastAPI template"
+    debug: bool = False
+    ...
+```
+
+You can register settings as `Singleton` in DI container
+
+```python
+from modern_di import BaseGraph, Scope, providers
+
+
+class DIContainer(BaseGraph):
+    settings = providers.Singleton(Scope.APP, Settings)
+    some_factory = providers.Factory(Scope.APP, SomeFactory, service_name=settings.cast.service_name)
+```
+
+And when `some_factory` is resolved it will receive `service_name` attribute from `Settings`

docs/introduction/context-data.md

@@ -0,0 +1,7 @@
+# Context data
+
+Often, scopes are connected with external events: HTTP-requests, message from queue, callbacks from framework.
+
+These events can be represented by some objects which can be used for dependencies creation.
+
+There are several providers with access to such context data. You can read more [here](../../providers/context-providers):