Modern-DI

https://github.com/modern-python/modern-di
Admin
Modern-DI is a Python dependency injection framework supporting async/sync resolution, scopes,...
Tokens:115,237
Snippets:886
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quick start with modern-di Container and Group

Source: https://github.com/modern-python/modern-di/blob/main/README.md

Quick start example showing how to define dataclasses, a Group with providers, and resolve dependencies using a Container. The Settings dataclass is frozen and slots-enabled, while UserRepository gets its settings auto-injected by type. The example prints the database_url from the resolved repository.

```python
import dataclasses
from modern_di import Container, Group, Scope, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    database_url: str = "postgresql+asyncpg://localhost/app"


@dataclasses.dataclass(kw_only=True, slots=True)
class UserRepository:
    settings: Settings  # auto-injected by type


class Dependencies(Group):
    settings = providers.Factory(Settings, scope=Scope.APP)
    user_repository = providers.Factory(UserRepository, scope=Scope.REQUEST)


with Container(groups=[Dependencies]) as container:
    with container.build_child_container(scope=Scope.REQUEST) as request:
        repo = request.resolve(UserRepository)
        print(repo.settings.database_url)
```

--------------------------------

### Install modern-di-taskiq with poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/taskiq.md

Install the modern-di-taskiq package using poetry.

```bash
poetry add modern-di-taskiq
```

--------------------------------

### Install modern-di-arq with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/arq.md

Install the modern-di-arq package using uv.

```bash
uv add modern-di-arq
```

--------------------------------

### Install modern-di-taskiq with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/taskiq.md

Install the modern-di-taskiq package using the uv package manager.

```bash
uv add modern-di-taskiq
```

--------------------------------

### Install modern-di-faststream with poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/faststream.md

Install the modern-di-faststream package using poetry.

```bash
poetry add modern-di-faststream
```

--------------------------------

### Install framework integrations with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/from-that-depends.md

Installs optional framework integration packages (FastAPI, Litestar, FastStream, Typer, pytest) using uv.

```bash
uv add modern-di-fastapi      # FastAPI
uv add modern-di-litestar     # Litestar
uv add modern-di-faststream   # FastStream
uv add modern-di-typer        # Typer
uv add modern-di-pytest       # pytest fixtures
```

--------------------------------

### Install modern-di-arq with poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/arq.md

Install the modern-di-arq package using poetry.

```bash
poetry add modern-di-arq
```

--------------------------------

### Install modern-di-faststream with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/faststream.md

Install the modern-di-faststream package using the uv package manager.

```bash
uv add modern-di-faststream
```

--------------------------------

### Install modern-di with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/index.md

Install modern-di with uv, pip, or poetry. For framework integrations, install the matching modern-di-* adapter package (e.g., modern-di-fastapi, modern-di-aiohttp, modern-di-litestar). For pytest support, install modern-di-pytest.

```bash
uv add modern-di
```

```bash
pip install modern-di
```

```bash
poetry add modern-di
```

--------------------------------

### Install modern-di-taskiq with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/taskiq.md

Install the modern-di-taskiq package using pip.

```bash
pip install modern-di-taskiq
```

--------------------------------

### Install modern-di-faststream with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/faststream.md

Install the modern-di-faststream package using pip.

```bash
pip install modern-di-faststream
```

--------------------------------

### Install modern-di-aiohttp with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/aiohttp.md

Install the modern-di-aiohttp package using uv, pip, or poetry. Choose the command that matches your package manager.

```bash
uv add modern-di-aiohttp
```

```bash
pip install modern-di-aiohttp
```

```bash
poetry add modern-di-aiohttp
```

--------------------------------

### setup_di(app, container)

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/aiohttp.md

Opens the root container on startup, closes it on cleanup, and installs the middleware that builds a per-connection child container. Returns the container.

```APIDOC
## setup_di(app, container)

### Description
Opens the root container on startup, closes it on cleanup, and installs the middleware that builds a per-connection child container. Returns the container.

### Parameters
- **app** (aiohttp.web.Application) - Required - The aiohttp application.
- **container** (Container) - Required - The root container to manage.

### Returns
- **Container** - The root container.
```

--------------------------------

### Install modern-di with uv or pip

Source: https://github.com/modern-python/modern-di/blob/main/README.md

Install the modern-di package using uv or pip. The comment shows the alternative pip command.

```bash
uv add modern-di      # or: pip install modern-di
```

--------------------------------

### Add a broker after setup_di

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/faststream.md

Shows that a broker added with app.add_broker after setup_di also gets the DI middleware at startup.

```python
app = faststream.FastStream(nats_broker)
modern_di_faststream.setup_di(app, container)
app.add_broker(kafka_broker)  # also gets the DI middleware at startup
```

--------------------------------

### Install modern-di-grpc with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/grpc.md

Install the modern-di-grpc package using your preferred package manager. The three commands are equivalent alternatives shown as tabs in the source.

```bash
uv add modern-di-grpc
```

```bash
pip install modern-di-grpc
```

```bash
poetry add modern-di-grpc
```

--------------------------------

### Install modern-di-litestar with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/litestar.md

Install the modern-di-litestar package using uv, pip, or poetry. Choose the command that matches your package manager.

```bash
uv add modern-di-litestar
```

```bash
pip install modern-di-litestar
```

```bash
poetry add modern-di-litestar
```

--------------------------------

### Install modern-di-typer with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/typer.md

Installs modern-di-typer using pip.

```bash
pip install modern-di-typer
```

--------------------------------

### Install modern-di-fastapi with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/fastapi.md

Adds the modern-di-fastapi package to the project using uv.

```bash
uv add modern-di-fastapi
```

--------------------------------

### Install framework integrations with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/from-that-depends.md

Installs optional framework integration packages (FastAPI, Litestar, FastStream, Typer, pytest) using pip.

```bash
pip install modern-di-fastapi
pip install modern-di-litestar
pip install modern-di-faststream
pip install modern-di-typer
pip install modern-di-pytest
```

--------------------------------

### Install modern-di-starlette with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/starlette.md

Install the modern-di-starlette package using uv, pip, or poetry. Choose the command that matches your package manager.

```bash
uv add modern-di-starlette
```

```bash
pip install modern-di-starlette
```

```bash
poetry add modern-di-starlette
```

--------------------------------

### Install modern-di with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/from-that-depends.md

Installs the modern-di core package using pip.

```bash
pip install modern-di
```

--------------------------------

### Install modern-di-arq with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/arq.md

Install the modern-di-arq package using pip.

```bash
pip install modern-di-arq
```

--------------------------------

### Install modern-di-fastapi with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/fastapi.md

Installs the modern-di-fastapi package using pip.

```bash
pip install modern-di-fastapi
```

--------------------------------

### Apply DITask to a single task with base=DITask

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/celery.md

Uses DITask for only one task by passing base=DITask to @app.task. The rest of the setup (container, setup_di, validate) is the same as the app-wide example.

```python
import typing

from celery import Celery
from modern_di import Container, Group, Scope, providers
from modern_di_celery import DITask, FromDI, setup_di


class Settings:
    def __init__(self) -> None:
        self.greeting = "hello"


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)


app = Celery("myapp", broker="redis://localhost")
container = Container(groups=[AppGroup])
setup_di(app, container)
container.validate()  # fails fast on a broken graph before the worker runs


@app.task(base=DITask)
def greet(name: str, settings: typing.Annotated[Settings, FromDI(Settings)]) -> str:
    return f"{settings.greeting}, {name}"
```

--------------------------------

### Install modern-di-flask with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/flask.md

Install the modern-di-flask package using your preferred package manager. Choose the command that matches your environment: uv, pip, or poetry.

```bash
uv add modern-di-flask
```

```bash
pip install modern-di-flask
```

```bash
poetry add modern-di-flask
```

--------------------------------

### Install modern-di-pytest with pip

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/pytest.md

Installs modern-di-pytest using pip.

```bash
pip install modern-di-pytest
```

--------------------------------

### First success: define a provider and resolve it

Source: https://github.com/modern-python/modern-di/blob/main/docs/index.md

Minimal example of a provider, a Group namespace, and Container.resolve. Without cache=, Factory calls the creator on every resolve, which is fine for cheap, stateless objects but not for a database engine you want to build once. Call validate() to detect cycles and scope-chain errors up front.

```python
import dataclasses

from modern_di import Container, Group, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    database_url: str = "postgresql+asyncpg://localhost/app"


class Dependencies(Group):
    settings = providers.Factory(Settings)


# Call validate() to detect cycles and scope-chain errors up front, at startup
container = Container(groups=[Dependencies])
container.validate()
settings = container.resolve(Settings)
print(settings.database_url)
```

--------------------------------

### Install modern-di-fastapi with poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/fastapi.md

Adds the modern-di-fastapi package to the project using poetry.

```bash
poetry add modern-di-fastapi
```

--------------------------------

### Install modern-di-aiogram with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/aiogram.md

Install the modern-di-aiogram package using your preferred package manager. The three commands are equivalent alternatives.

```bash
uv add modern-di-aiogram
```

```bash
pip install modern-di-aiogram
```

```bash
poetry add modern-di-aiogram
```

--------------------------------

### Install modern-di with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/from-that-depends.md

Adds the modern-di core package using the uv package manager.

```bash
uv add modern-di
```

--------------------------------

### Install modern-di-celery with uv, pip, or poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/celery.md

Install the modern-di-celery package using your preferred package manager. Choose the command that matches your environment: uv, pip, or poetry.

```bash
uv add modern-di-celery
```

```bash
pip install modern-di-celery
```

```bash
poetry add modern-di-celery
```

--------------------------------

### Regular Factory Example

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/factories.md

Shows how to define a regular factory that creates a new instance on every call. The factory is declared with providers.Factory, specifying the class and its kwargs. It demonstrates resolving the instance both by provider reference and by type.

```python
import dataclasses

from modern_di import Group, Container, Scope, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class IndependentFactory:
    dep1: str
    dep2: int


class Dependencies(Group):
    independent_factory = providers.Factory(
        IndependentFactory,
        scope=Scope.APP,
        kwargs={"dep1": "text", "dep2": 123}
    )


container = Container(groups=[Dependencies])
# Resolve by provider reference
instance = container.resolve_provider(Dependencies.independent_factory)
assert isinstance(instance, IndependentFactory)

# Resolve by type (uses the return type of the creator function/class)
instance2 = container.resolve(IndependentFactory)
assert isinstance(instance2, IndependentFactory)
```

--------------------------------

### Install modern-di-pytest with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/pytest.md

Adds modern-di-pytest as a development dependency using uv.

```bash
uv add --dev modern-di-pytest
```

--------------------------------

### Install modern-di with poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/from-that-depends.md

Adds the modern-di core package using the poetry package manager.

```bash
poetry add modern-di
```

--------------------------------

### Import modern_di classes

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/lifecycle.md

Import the core classes needed for the examples on this page.

```python
from modern_di import Container, Scope, providers, exceptions

```

--------------------------------

### Configuration replacement with external settings

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/from-dependency-injector.md

Shows how to replace dependency-injector's Configuration subsystem by loading settings with an external library and registering the resulting object as a regular provider. The example uses os.environ and a Group class.

```python
class Settings:
    def __init__(self) -> None:
        self.database_url = os.environ["DATABASE_URL"]

class AppGroup(Group):
    settings = providers.Factory(Settings, cache=True)
```

--------------------------------

### Install modern-di-typer with uv

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/typer.md

Adds modern-di-typer as a dependency using the uv package manager.

```bash
uv add modern-di-typer
```

--------------------------------

### Registering multiple provider groups

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/missing-provider.md

Example of passing multiple provider groups to the Container constructor to ensure all providers are registered.

```python
container = Container(groups=[Database, UseCases, Cache])
container.validate()
```

--------------------------------

### Install modern-di-typer with poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/typer.md

Adds modern-di-typer as a dependency using the poetry package manager.

```bash
poetry add modern-di-typer
```

--------------------------------

### Integrate modern-di with aiogram using setup_di and @inject

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/aiogram.md

Integrate modern-di with aiogram by defining scoped providers, creating a container, and calling setup_di to open/close it on dispatcher startup/shutdown and install per-update middleware. The @inject decorator with FromDI markers injects dependencies into handlers; container.validate() must be called after setup_di.

```python
import dataclasses
import typing

from aiogram import Dispatcher
from aiogram.types import Message
from modern_di import Container, Group, Scope, providers
from modern_di_aiogram import FromDI, inject, setup_di


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    service_name: str = "catalog"


@dataclasses.dataclass(kw_only=True, slots=True)
class Report:
    settings: Settings   # APP-scoped, injected by type

    def as_dict(self) -> dict[str, str]:
        return {"service": self.settings.service_name}


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)
    report = providers.Factory(Report, scope=Scope.REQUEST)


dispatcher = Dispatcher()
container = Container(groups=[AppGroup])
setup_di(dispatcher, container)
container.validate()  # after setup_di — its connection providers are now registered


@dispatcher.message()
@inject
async def greet(
    message: Message,
    report: typing.Annotated[Report, FromDI(Report)],
) -> None:
    await message.answer(str(report.as_dict()))
```

--------------------------------

### Install modern-di-pytest with poetry

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/pytest.md

Adds modern-di-pytest to the dev group using poetry.

```bash
poetry add --group dev modern-di-pytest
```

--------------------------------

### Fix DuplicateProviderTypeError with bound_type=None and explicit kwargs

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/duplicate-type-error.md

Complete example addressing the DuplicateProviderTypeError by setting bound_type=None on one duplicate provider and explicitly passing dependencies via kwargs. The primary_db_config provider is resolvable by type, while secondary_db_config is not and must be resolved via resolve_provider. The example also shows secondary_repository receiving its dependency via kwargs.

```python
from modern_di import Group, Scope, providers


class DatabaseConfig:
    def __init__(self, connection_string: str) -> None:
        self.connection_string = connection_string


class Repository:
    def __init__(self, db_config: DatabaseConfig) -> None:
        self.db_config = db_config


class MyGroup(Group):
    # Step 1: Set bound_type=None on the secondary provider or for both providers
    # This provider can be resolved by type: container.resolve(DatabaseConfig)
    primary_db_config = providers.Factory(
        DatabaseConfig,
        scope=Scope.APP,
        kwargs={"connection_string": "postgresql://primary"}
    )

    # This provider cannot be resolved by type
    # Must use: container.resolve_provider(MyGroup.secondary_db_config)
    secondary_db_config = providers.Factory(
        DatabaseConfig,
        scope=Scope.APP,
        bound_type=None,  # <-- Step 1: Makes it unresolvable by type
        kwargs={"connection_string": "postgresql://secondary"}
    )

    # Step 2: Explicitly pass dependencies via kwargs for second repository or for both
    primary_repository = providers.Factory(
        Repository,  # <-- Implicit dependency, no kwargs
        scope=Scope.APP,
    )

    secondary_repository = providers.Factory(
        Repository,
        scope=Scope.APP,
        kwargs={"db_config": secondary_db_config}  # <-- Step 2: Explicit dependency
    )

```

--------------------------------

### Use modern_di_aiogram.dialog with aiogram-dialog

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/aiogram.md

Shows how to use modern_di_aiogram.dialog with aiogram-dialog. Decorate getters and callbacks with @inject and use FromDI to resolve providers from the per-update child container. Requires setup_di(dispatcher, container) and installing aiogram-dialog yourself.

```python
import typing

from aiogram_dialog import DialogManager
from modern_di import Group, Scope, providers
from modern_di_aiogram.dialog import FromDI, inject


class Settings:
    def __init__(self) -> None:
        self.greeting = "hello"


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)


@inject
async def getter(
    dialog_manager: DialogManager,
    settings: typing.Annotated[Settings, FromDI(Settings)],   # resolve by type
    **kwargs: typing.Any,                                     # required by aiogram-dialog
) -> dict[str, str]:
    return {"greeting": settings.greeting}


@inject
async def on_click(
    callback: typing.Any,
    button: typing.Any,
    manager: DialogManager,
    settings: typing.Annotated[Settings, FromDI(Settings)],
) -> None:
    await manager.done(result=settings.greeting)
```

--------------------------------

### Apply modern-di to an aiohttp app with setup_di and @inject

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/aiohttp.md

Integrates modern-di with an aiohttp application. Defines APP-scoped Settings and REQUEST-scoped Report providers, injects Report into a handler via FromDI, and calls setup_di to open/close the root container and install per-connection middleware. Call container.validate() after setup_di because its connection providers are registered then.

```python
import dataclasses
import typing

from aiohttp import web
from modern_di import Container, Group, Scope, providers
from modern_di_aiohttp import FromDI, inject, setup_di


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    service_name: str = "catalog"


@dataclasses.dataclass(kw_only=True, slots=True)
class Report:
    settings: Settings   # APP-scoped, injected by type

    def as_dict(self) -> dict[str, str]:
        return {"service": self.settings.service_name}


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)
    report = providers.Factory(Report, scope=Scope.REQUEST)


@inject
async def get_report(
    request: web.Request,
    report: typing.Annotated[Report, FromDI(Report)],
) -> web.Response:
    return web.json_response(report.as_dict())


app = web.Application()
app.router.add_get("/report", get_report)
container = Container(groups=[AppGroup])
setup_di(app, container)
container.validate()  # after setup_di — its connection providers are now registered
```

--------------------------------

### Pair TestNatsBroker with TestApp in same with statement

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/faststream.md

Pair the test broker with TestApp in the same with statement when testing DI-using subscribers. Using TestNatsBroker alone starts the broker without running on_startup hooks, so the middleware and container are not set up, causing a RuntimeError that names setup_di and TestApp.

```python
async with TestNatsBroker(broker) as br, TestApp(app):
    await br.publish(...)
```

--------------------------------

### Custom Cache Settings with Finalizer

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/factories.md

Shows how to customize caching behavior by passing a CacheSettings to cache=. The example uses a finalizer to clean up the resource when it is closed, ensuring the closed resource is evicted from the cache.

```python
import contextlib

from modern_di import Group, Scope, providers


class SomeResource:
    def close(self) -> None: ...


def create_resource() -> SomeResource:
    # Create and return resource
    return SomeResource()


class Dependencies(Group):
    # Cache with cleanup — clear_cache=True (the default) ensures the closed
    # resource is evicted from cache so it cannot be returned again after close
    resource = providers.Factory(
        create_resource,
        scope=Scope.APP,
        cache=providers.CacheSettings(
            finalizer=lambda res: res.close(),  # Cleanup function
        )
    )
```

--------------------------------

### Sync and async finalizer examples

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/lifecycle.md

Both sync and async finalizers are supported; CacheSettings auto-detects via inspect.iscoroutinefunction(). The finalizer takes one argument: the cached instance.

```python
def close_engine_sync(engine: Engine) -> None:
    engine.dispose()


async def close_engine_async(engine: AsyncEngine) -> None:
    await engine.dispose()

```

--------------------------------

### Apply modern-di to a Litestar application

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/litestar.md

Set up a Litestar application with modern-di. Define scoped providers, inject dependencies via FromDI, and validate the container after installing the plugin.

```python
import dataclasses

import litestar
import modern_di_litestar
from modern_di import Container, Group, Scope, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    service_name: str = "catalog"


@dataclasses.dataclass(kw_only=True, slots=True)
class Report:
    settings: Settings   # APP-scoped, injected by type

    def as_dict(self) -> dict[str, str]:
        return {"service": self.settings.service_name}


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)
    report = providers.Factory(Report, scope=Scope.REQUEST)


@litestar.get("/report", dependencies={"report": modern_di_litestar.FromDI(Report)})
async def get_report(report: Report) -> dict[str, str]:
    return report.as_dict()


container = Container(groups=[AppGroup])
app = litestar.Litestar(
    route_handlers=[get_report],
    plugins=[modern_di_litestar.ModernDIPlugin(container)],
)
container.validate()  # after the plugin is installed — its connection providers are now registered
```

--------------------------------

### Cached Factory Example

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/factories.md

Shows how to define a cached factory that resolves once and caches the instance. The factory is declared with providers.Factory and cache=True. It demonstrates that resolving the same provider twice in the same container returns the same instance.

```python
import random

from modern_di import Group, Container, Scope, providers


def generate_random_number() -> float:
    return random.random()


class Dependencies(Group):
    singleton = providers.Factory(
        generate_random_number,
        scope=Scope.APP,
        cache=True
    )


container = Container(groups=[Dependencies])
singleton_instance1 = container.resolve_provider(Dependencies.singleton)
singleton_instance2 = container.resolve_provider(Dependencies.singleton)

# If resolved in the same container, the instance will be the same
assert singleton_instance1 is singleton_instance2
```

--------------------------------

### Create a broker in an on_startup hook

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/faststream.md

Shows how to create a broker inside an on_startup hook and ensure setup_di is called after the hook so the broker is covered.

```python
app = faststream.FastStream()


@app.on_startup
async def attach_broker() -> None:
    app.add_broker(NatsBroker(settings.nats_url))


modern_di_faststream.setup_di(app, container)  # after the hook, so startup sees the broker
```

--------------------------------

### Create once, reuse with CacheSettings and finalizer

Source: https://github.com/modern-python/modern-di/blob/main/docs/index.md

Use `cache=True` via `CacheSettings` to make a provider a singleton, and switch to the `with` form so the finalizer runs when the container closes. The example shows that resolving the same provider twice returns the same instance, and the finalizer is called on `with` exit.

```python
import dataclasses

from modern_di import Container, Group, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    database_url: str = "postgresql+asyncpg://localhost/app"


def close_settings(settings: Settings) -> None:
    print(f"closing settings ({id(settings)})")


class Dependencies(Group):
    settings = providers.Factory(
        Settings,
        cache=providers.CacheSettings(finalizer=close_settings),
    )


with Container(groups=[Dependencies]) as container:
    first = container.resolve(Settings)
    second = container.resolve(Settings)
    print(id(first), id(second), first is second)  # same instance, cached on first resolve
# `close_settings` ran here, on `with` exit
```

--------------------------------

### Implement setup_di to attach container and register providers

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/writing-integrations.md

Attaches the root container to the framework's application state, registers the connection providers, and wires the root container's lifecycle to app startup/shutdown. Returns the container. add_providers is a startup-time operation; concurrent calls on the same root container are not coordinated beyond the registry's internal lock.

```python
def setup_di(app: myfw.App, container: Container) -> Container:
    app.state.di_container = container            # attach
    container.add_providers(*_CONNECTION_PROVIDERS)  # register
    # wire lifecycle (see "Lifecycle rules" below)
    return container
```

--------------------------------

### Error output when dependency is reached through an alias

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/scope-chain.md

Example output showing the chain when the dependency is reached through an alias, naming every hop and the scope at which each resolves.

```text
InvalidScopeDependencyError (1):
  - Provider at a deeper scope reached through this chain:
      APP      UserCache (myapp.providers:10)
      REQUEST  └─> Repository
      REQUEST      └─> Session (myapp.providers:4)
      caused by: UserCache (scope APP) declares parameter 'session' typed as a provider of Session at deeper scope REQUEST. A provider cannot depend on a deeper-scoped provider.

```

--------------------------------

### Implement fetch_di_container to read root container from state

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/writing-integrations.md

Reads the root container back out of framework state. This is where the child-container builder and any helpers get at the root. Store and read under a named constant when the framework uses a string-keyed store.

```python
def fetch_di_container(app: myfw.App) -> Container:
    return typing.cast(Container, app.state.di_container)
```

--------------------------------

### Automatic sub-dependency resolution with Factory

Source: https://github.com/modern-python/modern-di/blob/main/docs/introduction/resolving.md

Shows how a Factory's creator function or class constructor is introspected to auto-resolve parameters by type. Parameters with defaults fall back to those defaults if no provider matches. The example defines DatabaseConfig and DatabaseConnection dataclasses, registers them as providers in a Group, and resolves DatabaseConnection, asserting the injected config and default timeout.

```python
import dataclasses
from modern_di import Container, Group, Scope, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class DatabaseConfig:
    host: str
    port: int


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class DatabaseConnection:
    config: DatabaseConfig    # auto-resolved by type
    timeout: int = 30         # uses default if unresolvable


class Dependencies(Group):
    db_config = providers.Factory(
        DatabaseConfig,
        scope=Scope.APP,
        kwargs={"host": "localhost", "port": 5432},
    )
    db_connection = providers.Factory(DatabaseConnection, scope=Scope.APP)


container = Container(groups=[Dependencies])

connection = container.resolve(DatabaseConnection)
assert connection.config.host == "localhost"
assert connection.timeout == 30
```

--------------------------------

### Building dependencies inside the class - hidden

Source: https://github.com/modern-python/modern-di/blob/main/docs/introduction/about-di.md

Constructor takes no arguments, so nothing outside the class can change the email sender. Tests reach the real sender and callers get no hint that mail is involved.

```python
class Registration:
    def __init__(self) -> None:
        self.email = SmtpEmailSender()

    def register_user(self, email: str) -> None:
        self.email.send_email(email, "Welcome!")
```

--------------------------------

### Fix ArgumentResolutionError: register provider, pass kwargs, or use default

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/argument-resolution-error.md

Shows three ways to resolve a missing provider for a creator parameter: register a provider with bound_type, pass the value explicitly via kwargs, or (not shown) give the parameter a default. The example defines a Dependencies group with a Factory for Service that requires a Clock, and provides two fixes: a provider for Clock and a kwargs entry.

```python
class Dependencies(Group):
    # missing: no provider for `Clock` anywhere
    service = providers.Factory(Service, scope=Scope.APP)  # Service(clock: Clock)

    # fix option 1: register a provider
    clock = providers.Factory(SystemClock, scope=Scope.APP, bound_type=Clock)

    # fix option 2: pass explicitly
    service2 = providers.Factory(Service, scope=Scope.APP, kwargs={"clock": clock})
```

--------------------------------

### Apply modern-di to taskiq application

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/taskiq.md

Shows how to set up a taskiq broker with modern-di, including defining providers, creating a container, and using FromDI for dependency injection in a task.

```python
import dataclasses
import typing

from modern_di import Container, Group, Scope, providers
from modern_di_taskiq import FromDI, setup_di
from taskiq import InMemoryBroker


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    service_name: str = "catalog"


@dataclasses.dataclass(kw_only=True, slots=True)
class Report:
    settings: Settings   # APP-scoped, injected by type

    def as_dict(self) -> dict[str, str]:
        return {"service": self.settings.service_name}


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)
    report = providers.Factory(Report, scope=Scope.REQUEST)


broker = InMemoryBroker()
container = Container(groups=[AppGroup])
setup_di(broker, container)
container.validate()  # after setup_di — its connection providers are now registered


@broker.task
async def get_report(
    report: typing.Annotated[Report, FromDI(Report)],
) -> dict[str, str]:
    return report.as_dict()
```

--------------------------------

### Apply modern-di to a FastStream application

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/faststream.md

Shows how to set up a FastStream app with modern-di, including defining providers, creating a container, and using the FromDI annotation in a subscriber.

```python
import dataclasses
import typing

import faststream
from faststream.nats import NatsBroker
import modern_di_faststream
from modern_di import Container, Group, Scope, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    service_name: str = "catalog"


@dataclasses.dataclass(kw_only=True, slots=True)
class Report:
    settings: Settings   # APP-scoped, injected by type

    def as_dict(self) -> dict[str, str]:
        return {"service": self.settings.service_name}


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)
    report = providers.Factory(Report, scope=Scope.REQUEST)


broker = NatsBroker()
app = faststream.FastStream(broker=broker)
container = Container(groups=[AppGroup])
modern_di_faststream.setup_di(app, container)
container.validate()  # after setup_di — its connection providers are now registered


@broker.subscriber("orders.in")
async def handle_order(
    report: typing.Annotated[Report, modern_di_faststream.FromDI(Report)],
) -> dict[str, str]:
    return report.as_dict()
```

--------------------------------

### Fix CreatorCallError with skip_creator_parsing

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/creator-call-error.md

Shows the correct and incorrect usage of `skip_creator_parsing=True` with `providers.Factory`. The wrong example omits the required `port` kwarg, causing a `CreatorCallError`; the right example includes both `host` and `port` to match the creator signature.

```python
def create_service(host: str, port: int) -> Service: ...


class Dependencies(Group):
    # Wrong: skip_creator_parsing=True but kwargs misses `port`
    service = providers.Factory(
        create_service, scope=Scope.APP, skip_creator_parsing=True,
        bound_type=Service, kwargs={"host": "localhost"},
    )

    # Right
    service = providers.Factory(
        create_service, scope=Scope.APP, skip_creator_parsing=True,
        bound_type=Service, kwargs={"host": "localhost", "port": 5432},
    )
```

--------------------------------

### Fix InvalidChildScopeError with strictly deeper scope

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/invalid-child-scope-error.md

Shows the correct usage of build_child_container with a strictly deeper scope. The wrong example raises InvalidChildScopeError when the child scope is equal to the parent's, while the right example uses Scope.REQUEST from a SESSION parent.

```python
from modern_di import Scope

app_container = Container(scope=Scope.APP, groups=[MyGroup])

# Wrong: SESSION is not deeper than SESSION
mid = app_container.build_child_container(scope=Scope.SESSION)
bad = mid.build_child_container(scope=Scope.SESSION)  # raises InvalidChildScopeError

# Right
good = mid.build_child_container(scope=Scope.REQUEST)
```

--------------------------------

### After (3.0): Opening a container before use

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/to-3.x.md

Shows the 3.0 behavior where a container must be opened before use, either with a with block or by calling open() directly. Also demonstrates that child containers must be entered before use.

```python
container = Container(scope=Scope.APP, groups=[MyGroup])
service = container.resolve(MyService)  # raises ContainerClosedError: not open

# Fix: enter the container first.
with Container(scope=Scope.APP, groups=[MyGroup]) as container:
    service = container.resolve(MyService)  # works

    # A child also starts unopened and must be entered before use.
    with container.build_child_container(scope=Scope.REQUEST) as child:
        value = child.resolve(SomeContextType)  # works

# Or, without a `with` block:
container = Container(scope=Scope.APP, groups=[MyGroup])
container.open()
service = container.resolve(MyService)  # works
```

--------------------------------

### Use auto_inject=True to wire all views automatically

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/flask.md

Enable auto_inject=True in setup_di to automatically wire all registered views (app and blueprint routes) without per-view @inject. setup_di must run after all routes are registered. Views that already have @inject are left untouched.

```python
import typing

from flask import Flask
from modern_di import Container, Group, Scope, providers
from modern_di_flask import FromDI, setup_di


class Settings:
    def __init__(self) -> None:
        self.greeting = "hello"


class Dependencies(Group):
    settings = providers.Factory(scope=Scope.APP, creator=Settings)


app = Flask(__name__)


@app.route("/hello/<name>")
def hello(name: str, settings: typing.Annotated[Settings, FromDI(Dependencies.settings)]) -> str:
    return f"{settings.greeting}, {name}"


# no @inject needed on individual views
container = Container(groups=[Dependencies])
setup_di(app, container, auto_inject=True)
container.validate()  # after setup_di — its connection providers are now registered
```

--------------------------------

### Define connection ContextProviders for request and websocket

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/writing-integrations.md

Module-level providers pair the framework's connection types with the scope their child container should open at. This is the single source of the kind-to-scope mapping; setup_di registers them and the child-container builder dispatches off them.

```python
from modern_di import Scope, providers

myfw_request_provider = providers.ContextProvider(myfw.Request, scope=Scope.REQUEST)
myfw_websocket_provider = providers.ContextProvider(myfw.WebSocket, scope=Scope.SESSION)

_CONNECTION_PROVIDERS = (myfw_request_provider, myfw_websocket_provider)
```

--------------------------------

### Warm caches at startup

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/lifecycle.md

Resolve providers in the startup hook to warm caches, since instances are created lazily on first resolve.

```python
container = Container(groups=[Dependencies])

# Warm caches at startup
container.resolve(AsyncEngine)
container.resolve(Settings)

```

--------------------------------

### Manual child container with sync and async context managers

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/scopes.md

Shows how to build a child container manually using a context manager so finalizers run on exit. Use 'async with' only when the scope holds providers with async finalizers; otherwise plain 'with' is enough. Resolution is always synchronous.

```python
with app_container.build_child_container(scope=Scope.REQUEST) as request_container:
    service = request_container.resolve(UserService)
# finalizers ran here

async with app_container.build_child_container(scope=Scope.REQUEST) as request_container:
    service = request_container.resolve(UserService)
# async finalizers ran here
```

--------------------------------

### Error output for scope chain violation

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/scope-chain.md

Example output from container.validate() showing an InvalidScopeDependencyError with a chain from APP-scoped UserCache to REQUEST-scoped Session.

```text
Container.validate() found 1 issue(s): InvalidScopeDependencyError

InvalidScopeDependencyError (1):
  - Provider at a deeper scope reached through this chain:
      APP      UserCache (myapp.providers:10)
      REQUEST  └─> Session (myapp.providers:4)
      caused by: UserCache (scope APP) declares parameter 'session' typed as a provider of Session at deeper scope REQUEST. A provider cannot depend on a deeper-scoped provider.

```

--------------------------------

### Error output for CircularDependencyError

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/circular-dependency.md

Example output when Container.validate() detects a circular dependency, showing the cycle path from ServiceA to ServiceB and back.

```text
Container.validate() found 1 issue(s): CircularDependencyError

CircularDependencyError (1):
  - Circular dependency detected:
      ServiceA
      └─> ServiceB
          └─> ServiceA
    Check your provider graph for unintended cycles.
```

--------------------------------

### Materialize dependencies as fixtures with expose and modern_di_fixture

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/pytest.md

Shows bulk exposure of providers via expose and manual creation of a single fixture via modern_di_fixture.

```python
from modern_di_pytest import expose, modern_di_fixture

from app.ioc import Auth, Billing, Dependencies
from app.services import EmailClient


# Bulk: every Provider on each group becomes a pytest fixture
# named after the class attribute. Pass several groups in one call;
# duplicate names across groups raise ValueError. Non-Provider attributes
# are skipped.
expose(Dependencies, Auth, Billing)
# e.g. user_service is the attribute name on the Dependencies group,
# so it becomes the user_service fixture used in the tests below.

# Manual: a single type or Provider as a named fixture.
email_client = modern_di_fixture(EmailClient)
```

--------------------------------

### Manual wiring by hand - construction order

Source: https://github.com/modern-python/modern-di/blob/main/docs/introduction/about-di.md

Manually constructing objects in dependency order becomes unwieldy as the application grows; nothing manages lifetimes and construction logic ends up wherever needed. A container like modern-di takes over this.

```python
config = AppConfig()
email = SmtpEmailSender(config)
registration = Registration(email)
```

--------------------------------

### Resolving Container returns the calling container

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/container.md

Shows that resolving `Container` returns the calling container, not the root. A child container built with `build_child_container` resolves to itself, as asserted in the example.

```python
app_container = Container(scope=Scope.APP)
request_container = app_container.build_child_container(scope=Scope.REQUEST)

assert app_container.resolve(Container) is app_container
assert request_container.resolve(Container) is request_container  # the child, not the APP root
```

--------------------------------

### ProviderScopeFrozenError example

Source: https://github.com/modern-python/modern-di/blob/main/docs/troubleshooting/provider-scope-frozen-error.md

Shows the error scenario: a provider without explicit scope is used in a group without scope, then registered, and later a scoped group tries to change its scope, raising ProviderScopeFrozenError.

```python
shared = providers.Factory(SomeService)          # no explicit scope -> APP default, unclaimed

class PlainGroup(Group):                          # no scope= -> stamps nothing
    svc = shared

container = Container(scope=Scope.APP, groups=[PlainGroup])   # registers + compiles

class ScopedGroup(Group, scope=Scope.REQUEST):    # ProviderScopeFrozenError
    svc = shared
```

--------------------------------

### Migrate Resource with generator initializer to Factory with finalizer

Source: https://github.com/modern-python/modern-di/blob/main/docs/migration/from-dependency-injector.md

Shows how to split a generator-based Resource (with shutdown step) into a plain creator function and a separate finalizer, then use a cached Factory with CacheSettings(finalizer=...).

```python
# dependency-injector
def init_resource(argument1=...):
    resource = SomeResource()  # initialization
    yield resource
    # shutdown code

thread_pool = providers.Resource(init_resource)

# modern-di
def create_resource() -> SomeResource:
    return SomeResource()

def close_resource(resource: SomeResource) -> None:
    ...  # shutdown code

thread_pool = providers.Factory(
    create_resource,
    cache=providers.CacheSettings(finalizer=close_resource),
)
```

--------------------------------

### List external pull requests for triage

Source: https://github.com/modern-python/modern-di/blob/main/docs/agents/issue-tracker.md

Use `gh pr list` with `--state open` and `--json` to get PR data. Filter by `authorAssociation` to keep only `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE`.

```bash
gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments
```

--------------------------------

### fetch_request_container(request)

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/aiohttp.md

Returns the per-connection child container the middleware built (REQUEST for HTTP, SESSION for a WebSocket). Raises RuntimeError naming setup_di when the request did not pass through the middleware.

```APIDOC
## fetch_request_container(request)

### Description
Returns the per-connection child container the middleware built (REQUEST for HTTP, SESSION for a WebSocket). Raises RuntimeError naming setup_di when the request did not pass through the middleware.

### Parameters
- **request** (aiohttp.web.Request) - Required - The incoming request.

### Returns
- **Container** - The per-connection child container.

### Exceptions
- **RuntimeError** - If the request did not pass through the middleware, naming setup_di.
```

--------------------------------

### Clone and run benchmark report

Source: https://github.com/modern-python/modern-di/blob/main/docs/introduction/performance.md

Clones the modern-di repository and runs the benchmark report in an isolated environment. The first run resolves pinned rival dependencies and runs 5 times by default.

```bash
git clone https://github.com/modern-python/modern-di
cd modern-di
just bench-report   # isolated env; first run resolves the pinned rival deps; runs 5x by default
```

--------------------------------

### Apply modern-di-typer to a Typer application

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/typer.md

Shows how to set up a Typer app with modern-di-typer, including defining providers, creating a container, and using the @inject decorator to resolve dependencies.

```python
import dataclasses
import typing

import modern_di_typer
import typer
from modern_di import Container, Group, Scope, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    service_name: str = "catalog"


@dataclasses.dataclass(kw_only=True, slots=True)
class Report:
    settings: Settings   # APP-scoped, injected by type

    def render(self) -> str:
        return f"service={self.settings.service_name}"


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)
    report = providers.Factory(Report, scope=Scope.REQUEST)


app = typer.Typer()
container = Container(groups=[AppGroup])
modern_di_typer.setup_di(app, container)
container.validate()  # fails fast on a broken graph before the CLI runs


@app.command()
@modern_di_typer.inject
def status(
    report: typing.Annotated[Report, modern_di_typer.FromDI(Report)],   # resolve by type
) -> None:
    typer.echo(report.render())


if __name__ == "__main__":
    with container:                                # runs APP-scope finalizers on exit
        app()
```

--------------------------------

### Apply modern-di-flask to a Flask application

Source: https://github.com/modern-python/modern-di/blob/main/docs/integrations/flask.md

Set up modern-di-flask in a Flask app. Define providers with scopes (APP and REQUEST), register routes, then call setup_di after all routes are registered. The @inject decorator and FromDI marker are used for injection. container.validate() must be called after setup_di.

```python
import dataclasses
import typing

from flask import Flask
from modern_di import Container, Group, Scope, providers
from modern_di_flask import FromDI, inject, setup_di


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    service_name: str = "catalog"


@dataclasses.dataclass(kw_only=True, slots=True)
class Report:
    settings: Settings   # APP-scoped, injected by type

    def as_dict(self) -> dict[str, str]:
        return {"service": self.settings.service_name}


class Dependencies(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)
    report = providers.Factory(Report, scope=Scope.REQUEST)


app = Flask(__name__)


@app.route("/report")
@inject
def get_report(report: typing.Annotated[Report, FromDI(Report)]) -> dict[str, str]:
    return report.as_dict()


# call setup_di AFTER registering routes
container = Container(groups=[Dependencies])
setup_di(app, container)
container.validate()  # after setup_di — its connection providers are now registered
```

--------------------------------

### Explicit container injection with providers.container_provider

Source: https://github.com/modern-python/modern-di/blob/main/docs/providers/container.md

Inject the container explicitly using `providers.container_provider` in the factory's `kwargs`. Use this when the parameter is not annotated as `Container` or when an explicit binding is preferred. The example shows the result "resolved from APP scope".

```python
from modern_di import Container, Group, Scope, providers

def another_creator(di_container: Container) -> str:
    # The injected container is real — use it
    return f"resolved from {di_container.scope.name} scope"

class Dependencies(Group):
    another_factory = providers.Factory(
        another_creator,
        scope=Scope.APP,
        kwargs={"di_container": providers.container_provider}
    )

container = Container(groups=[Dependencies])
result = container.resolve(str)
# result: "resolved from APP scope"
```
Tokens:
Raw