Writing an integration¶
This page specifies how to build a modern-di integration for a framework that does not have one yet: an ASGI app, a message broker, a CLI, a test runner. Implement the contract, mirror the scaffolding, and work through the checklist at the end.
An integration does three jobs:
- Own the root container's lifecycle: open it when the app starts, close it when the app stops.
- Open a child container per unit of work (a request, a message, a command), injecting the framework's connection object as context, and close it when that unit ends.
- Bridge modern-di into the framework's own injection, so a handler can ask for a provider or a type and receive the resolved value.
The contract¶
Every integration exposes the following. The examples are for an async web framework; a synchronous
one swaps async with for with and close_async for close_sync.
1. Connection ContextProvider(s)¶
One module-level provider per connection kind the framework has. Each pairs the framework's connection
type with the scope its child container opens at, which makes these providers
the single source of the kind-to-scope mapping. setup_di registers them and the child builder
dispatches on them.
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)
With one connection kind (a broker message, a gRPC call) there is one provider, and FastStream and FastMCP register it directly without a tuple. A unit of work with no injectable connection object, such as a Typer command or a Celery task, has none.
2. setup_di(app, container) -> Container¶
Attach the root container to the application state, register the connection providers, wire the root container's lifecycle to app startup and shutdown, and return the container:
def setup_di(app: myfw.App, container: Container) -> Container:
app.state.di_container = container
container.add_providers(*_CONNECTION_PROVIDERS)
original_lifespan = app.lifespan
@contextlib.asynccontextmanager
async def lifespan(app_: myfw.App) -> typing.AsyncIterator[None]:
async with fetch_di_container(app_), original_lifespan(app_):
yield
app.lifespan = lifespan
return container
A framework with a plugin system gets the same three steps through its own extension point. Litestar's
ModernDIPlugin(InitPlugin) does them in on_app_init instead of a free setup_di function.
add_providers is a startup-time operation and is not coordinated with concurrent resolves, so call it
from setup_di, never from request-handling code.
3. fetch_di_container(app_or_ctx) -> Container¶
Read the root container back out of framework state. The child builder and any helpers get at the root
through it. When the lookup fails, raise a RuntimeError that names the missing call, with from None
so the framework's AttributeError or KeyError on a private key does not trail it:
def fetch_di_container(app: myfw.App) -> Container:
try:
return typing.cast(Container, app.state.di_container)
except AttributeError:
msg = (
"No modern-di container found on the app. "
"Call setup_di(app, container) before using FromDI or fetch_di_container."
)
raise RuntimeError(msg) from None
The same rule covers every place an integration looks a container up, including the per-call child
that a decorator reads. Use a plain RuntimeError rather than a ModernDIError subclass, because the
fault is in the framework wiring and modern_di.integrations defines no exceptions. Pin the message
with a test. FastMCP is the one variation: it raises a subclass of both RuntimeError and
FastMCPError, so the client sees the message.
When the framework has a string-keyed store (FastStream's ContextRepo, Typer's
context_settings["obj"]), keep the key in a named constant that both the writer and the reader use.
4. Per-unit-of-work child-container builder¶
Build a child container at the connection's scope, inject the connection object as context, hand the
child to the handler, and close it when the unit of work ends. async with on the child closes it on
every exit path. Who builds the child depends on how the framework runs handlers:
- A dependency generator (FastAPI, Litestar, taskiq) yields the child. With several connection kinds,
modern_di.integrations.classify_connectionpicks the first provider the connection is an instance of and returns its scope and a{context_type: connection}context, orNonewhen nothing matches:
from modern_di import integrations
async def build_di_container(connection: HTTPConnection) -> typing.AsyncIterator[Container]:
match = integrations.classify_connection(connection, _CONNECTION_PROVIDERS)
async with fetch_di_container(connection.app).build_child_container(
scope=match.scope if match else None,
context=match.context if match else None,
) as container:
yield container
With one connection kind, integrations.bind(provider, connection) returns the same scope and
context without the isinstance scan.
-
Middleware or a framework hook builds the child, stores it where the handler's code can find it for the duration of the call, and closes it afterwards. FastStream does this in
BaseMiddleware.consume_scope, Starlette in a pure-ASGI middleware, Flask inbefore_requestandteardown_appcontext, arq inon_job_startandon_job_end, and gRPC in a server interceptor. -
A decorator builds the child around each call (Typer, Celery). A unit of work with no connection object skips
bindandclassify_connectionand callsbuild_child_container(scope=...)directly.
5. FromDI marker + Dependency resolver¶
FromDI(dependency) accepts a provider or a type and stands in for the resolved value at a handler's
call site: x: Annotated[Foo, FromDI(foo_provider)]. How it delivers the value depends on the
framework:
- Native-DI frameworks (FastAPI, FastMCP, FastStream, Litestar, taskiq) have a per-handler injection
seam such as
Depends,ProvideorTaskiqDepends.FromDIreturns that native marker, and the framework calls your resolver with the request container. FastMCP needs the default-value form,x: T = FromDI(T), because it strips an injected parameter from the tool schema only when the marker is the default; its integration refuses to start on theAnnotatedform. - Frameworks without request-scoped DI return an inert marker from
FromDI, and a decorator does the resolution. See the decorator path.
On the native path, FromDI returns the framework's marker wrapping a frozen, slotted dataclass that
holds a modern_di.integrations.Marker. The dataclass's __call__ receives the request container
through the framework's DI and resolves through the marker:
from modern_di import integrations
@dataclasses.dataclass(slots=True, frozen=True)
class Dependency(typing.Generic[T_co]):
marker: integrations.Marker[T_co]
async def __call__(self, request_container: typing.Annotated[Container, myfw.Depends(build_di_container)]) -> T_co:
return self.marker.resolve(request_container)
def FromDI(dependency: providers.AbstractProvider[T_co] | type[T_co]) -> T_co: # noqa: N802
return typing.cast(T_co, myfw.Depends(Dependency(integrations.Marker(dependency))))
Marker.resolve(container) calls container.resolve_dependency, so overrides, caching and
did-you-mean suggestions come with it. FromDI is PascalCase, with # noqa: N802, because it stands
in for a type at call sites.
Lifecycle rules¶
- Open the root before any user startup code and close it after all user shutdown code. That code
can then resolve APP-scoped dependencies, and APP finalizers run last. With a context-manager
lifespan, make the container the outer context, as
setup_diabove does. With callback hooks, the close must run after every shutdown hook, including ones registered aftersetup_di. FastStream and aiogram register their close at startup, Celery moves its close to the end when the worker starts, and taskiq moves its close to the end at shutdown. Where the framework can't give that order, say on the docs page which user code runs outside it, as the aiohttp and FastMCP pages do. - Reopen the root container on startup. A container closed on shutdown stays closed, and the next
resolve raises
ContainerClosedError, so a second lifespan cycle in the same process (a test client re-entered, a broker restarted) needs the reopen. With a context-manager lifespan, composeasync with containeraround the existing lifespan, assetup_diabove does:__aenter__opens and__aexit__closes. With callback hooks, open the container on startup and close it withclose_asyncon shutdown, as FastStream, aiogram and taskiq do.open()validates nothing and is a no-op on an open container. - Close the child container on every exit path, errors included. If the framework runs on anyio,
close it under
anyio.move_on_after(10, shield=True)and log a warning when that bound expires. anyio cancellation is level-triggered: in a cancelled scope everyawaitis cancelled again, so an unshielded close stops at the first async finalizer and skips the rest. The bound keeps a hung finalizer from blocking forever. modern-di-starlette's_close_childis the reference; the FastAPI, Litestar, FastMCP and FastStream integrations do the same. Under plain asyncio atask.cancel()is delivered once, so the close that follows runs in full and needs no shield. - Match async and sync to the framework:
close_asyncin an async framework,close_syncin a synchronous one (Typer, Flask, a sync gRPC server). - Document that
container.validate()goes aftersetup_di, never before.setup_diregisters the connection providers, so an earliervalidate()sees an incomplete graph and raises for any provider that depends on the connection object by type. Validating is optional. - Open and close the root in every execution context the framework runs work in. Celery fires
worker_process_initonly for the prefork and solo pools, never for gevent, eventlet or threads, which run in the main worker process; its integration also hooksworker_initandworker_shutdown, which fire for every pool.open()andclose_*are idempotent, so overlapping hooks are safe. Where no hook fires, work still succeeds because a new container is open, but nothing closes it and its finalizers never run. If the framework has no lifecycle hook at all (Flask, gRPC, Typer), the caller owns the root's open and close; say so on the docs page. - On ASGI the lifespan scope is optional. A mounted sub-application never receives it from its parent,
and some deployments turn it off (Mangum
lifespan="off"), so callsetup_dion the top-level served app or have the caller close the root. modern-di-starlette and modern-di-fastapi also open and close the root containers of mounted apps that calledsetup_di, from the outer app's lifespan.
Scope mapping¶
Map each connection kind to the scope its child container opens at, following the scope hierarchy:
| Unit of work | Scope | Rationale |
|---|---|---|
| HTTP request | REQUEST |
one child per request |
| WebSocket connection | SESSION |
outlives individual messages on the socket |
| Broker message | REQUEST |
one child per consumed message |
| CLI command | REQUEST |
one child per command invocation |
| Nested action within a unit | ACTION (a further child) |
opt-in deeper scope, e.g. a Typer action_scope |
How the existing integrations realize the contract¶
Pick the closest precedent for your framework:
| Integration | Path | Child built by | Connection providers | Root lifecycle |
|---|---|---|---|---|
| FastAPI | native, Depends |
async dependency generator | request, websocket | composed lifespan |
| Litestar | native, Provide |
async dependency generator | request, websocket | ModernDIPlugin.on_app_init adds a lifespan manager and an on_shutdown hook |
| FastStream | native, Depends |
BaseMiddleware.consume_scope |
message | on_startup / after_shutdown callbacks |
| taskiq | native, TaskiqDepends |
async dependency generator | message | worker startup and shutdown events |
| FastMCP | native, default-value FromDI |
middleware | fastmcp.Context |
lifespan provider |
| Starlette | decorator | pure-ASGI middleware | request, websocket | composed lifespan |
| aiohttp | decorator | middleware | web.Request twice, the websocket one with bound_type=None |
on_startup / on_cleanup signals |
| Flask | decorator, or auto_inject=True |
before_request / teardown_appcontext |
request | caller |
| aiogram | decorator, or auto_inject=True |
dispatcher middleware | update, event | dispatcher startup and shutdown |
| gRPC | decorator | server interceptor | ServicerContext |
caller |
| arq | decorator | on_job_start / on_job_end hooks |
none | wrapped on_startup / on_shutdown |
| Celery | decorator, or the DITask base |
the decorator | none | worker signals |
| Typer | decorator | the decorator | none | caller |
aiohttp has one connection type for both kinds, since a WebSocket is an upgraded web.Request. It
tells them apart with web.WebSocketResponse().can_prepare(request).ok and registers only the request
provider by type.
modern-di-pytest has no app to wire. It exposes modern_di_fixture and expose in
place of setup_di and FromDI, and resolves from a di_container fixture the user defines. Follow it
for a test runner.
Frameworks without native DI (the decorator path)¶
An integration can skip the decorator only where the framework evaluates a parameter default as a
provider: FastAPI, FastMCP and FastStream Depends, Litestar Provide, taskiq TaskiqDepends. Flask,
Starlette, aiohttp, Celery, arq, Typer and gRPC hand the handler a plain call, and aiogram matches its
data dict by parameter name, so those need @inject. Some apply it for you: Flask and aiogram take
setup_di(..., auto_inject=True), and Celery has the DITask base class.
On this path FromDI is integrations.from_di, which returns an inert Marker cast to the resolved
type so checkers still see T. The decorator scans for markers once with integrations.parse_markers
at decoration time and resolves them with integrations.resolve_markers on each call. Here a
middleware stores the child on the connection, and @inject reads it back:
import functools
from modern_di import integrations
FromDI = integrations.from_di
_CHILD_CONTAINER_KEY = "modern_di_container"
async def di_middleware(
request: myfw.Request, call_next: typing.Callable[[myfw.Request], typing.Awaitable[typing.Any]]
) -> typing.Any:
match = integrations.bind(myfw_request_provider, request)
async with fetch_di_container(request.app).build_child_container(
scope=match.scope, context=match.context
) as child:
request.scope[_CHILD_CONTAINER_KEY] = child
try:
return await call_next(request)
finally:
del request.scope[_CHILD_CONTAINER_KEY]
def inject(func: typing.Callable[..., typing.Awaitable[typing.Any]]) -> typing.Callable[..., typing.Awaitable[typing.Any]]:
markers = integrations.parse_markers(func)
@functools.wraps(func)
async def wrapper(request: myfw.Request, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
try:
child = request.scope[_CHILD_CONTAINER_KEY]
except KeyError:
msg = (
"No modern-di container found for this request. "
"Call setup_di(app, container) so requests pass through the modern-di middleware "
"before using @inject."
)
raise RuntimeError(msg) from None
return await func(request, *args, **kwargs, **integrations.resolve_markers(child, markers))
return wrapper
@inject
async def handler(
request: myfw.Request, service: typing.Annotated[MyService, FromDI(Dependencies.service)]
) -> MyService:
return service
Delete the per-call entry in finally, as Starlette and aiohttp do. The child's context holds the
connection, so an entry left on the connection makes a reference cycle that only the garbage collector
can reclaim.
Signature rewriting¶
Rewrite the signature only when the framework reads the handler's signature to bind its arguments.
Typer parses CLI options from it, Celery binds task arguments against it, and aiogram matches data
keys to parameter names. Starlette, aiohttp, Flask, gRPC and arq call the handler with arguments they
already know, so a plain functools.wraps wrapper is enough there.
When you rewrite:
- Remove the marked parameters and leave every other parameter in place, so the framework keeps parsing them.
- Assign the cleaned signature to
wrapper.__signature__.__signature__is missing from the stubs, so add# ty: ignore[missing-attribute]. - Skip
functools.wrapswhen the framework unwraps__wrapped__to find the signature, as aiogram does; otherwise it reads the original signature and ignores yours. - Add any parameter the wrapper needs to reach the container, if the handler did not declare it. Typer
inserts a
typer.Contextat position 0 and drops it again before calling the handler.
Pitfalls to get right¶
- Put the framework's registration decorator outside:
@app.command()above@inject, so it registers the wrapper. - Keep per-call state on a per-call store (Typer's
ctx.meta, a request's scope), never on shared app state, so nested scopes can parent onto it and nothing leaks between calls. - Guard sweeps that apply
@injectfor the user (Flask and aiogramauto_inject, CeleryDITask) against double wrapping withintegrations.is_injected(func)andintegrations.mark_injected(wrapper). - Say which handlers a sweep leaves alone. aiogram's
auto_injectskips handlers onupdateobservers, so those need@injectby hand, and its page says so. - Leave nested scopes to the caller. Typer's
action_scope(ctx)yields a freshACTIONchild of the per-call container for eachwithblock.
Repo scaffolding¶
Each official integration is its own repository and PyPI package, with the same tooling as
modern-di.
- Name the repo and the PyPI package
modern-di-<framework>, and the import packagemodern_di_<framework>. - Put the implementation in
modern_di_<framework>/main.py; a larger integration may add modules beside it, as aiogram does withdialog.py.__init__.pyre-exports the public API and lists it in an explicit__all__, with private helpers kept out. - In
pyproject.toml, setdescription = "modern-di integration for <Framework>", dependencies["<framework>>=...,<...", "modern-di>=4,<5"], the standard classifiers,[project.urls]for the docs site and the repo, andversion = "0", because the release tag sets the version. - In
tests/:conftest.pybuilds an app, callssetup_diwith aContainer(groups=[Dependencies]), and yields a test client.dependencies.pydefines a sampleGroupwith providers at several scopes, plus providers that read the connection object to prove context injection works.- Cover the lifespan with a restart, resolution through
FromDI, and websockets where the framework has them, under the same 100% coverage gatemodern-diholds. test_public_surface.pypins the package's public names.
- Ship
examples/app.py(with an emptyexamples/__init__.py): an APP-scopedSettingsand one work-scoped service that depends on it by type, resolved into one handler through the framework's real idiom. Usetyping.Annotated[T, FromDI(...)], since a= FromDI(...)default trips ruffB008; FastMCP is the exception and needs the default. Name the types to match the docs page.tests/test_example.pydrives the example through the repo's own test double, asserts the real injected output, and covers the example fully, with no coverageomitand# pragma: no coveronly on an unreachable boot line such asif __name__ == "__main__". - In the README, put a
Usage example:line underFull guide:with an absolute link, such as[examples/](https://github.com/modern-python/modern-di-<framework>/tree/main/examples). PyPI does not rewrite relative links. - Copy
AGENTS.mdand thejustfilefrommodern-di. Keep behavioural invariants in named tests, and record rejected alternatives on the design decisions page. Keep resolution sync-only and add no runtime dependency beyond the framework andmodern-di.rufffloats forward in CI, so keepCPY001in the lintignorelist. - In the
modern-direpo, adddocs/integrations/<framework>.mdand amkdocs.ymlnav entry under the matching family: Web, Tasks & events, Bots, RPC, CLI or Testing. Model the page on an existing one in the same family, with one compact example using the same two providers asexamples/app.pyandcontainer.validate()aftersetup_di. Web pages such as Starlette use## Installation,## Usage,## Injecting into handlers,## Scopes and lifecycle, and## Websocketswhere the framework has them. Other pages such as taskiq use## How to use,## Scopes,## Root container lifecycle, and usually## Testing. Both kinds give connection injection its own section, named## Framework context objectson every page but gRPC's and present even when the integration registers no context provider. Framework-specific sections follow, then a## See alsoblock, and the## APItable last. WriteFromDIin theAnnotatedform, except where the framework needs another: the FastMCP page uses the default-value form, and the Litestar page putsFromDIin a route'sdependenciesmapping. For a provider that must also resolve outside a connection, show an optional parameter (request: FrameworkType | None = None), as the gRPC page does; Optional parameters explains it. - Releases are tag-driven: push a bare semver tag off a green
mainand the workflow publishes.
Checklist¶
- [ ] Repo
modern-di-<framework>, packagemodern_di_<framework>,main.pyand a re-exporting__init__.pywith an explicit__all__. - [ ] One connection
ContextProviderper connection kind, each mapping the kind to a scope. - [ ]
setup_di(or a plugin) attaches the root container, registers the connection providers, and wires startup and shutdown. - [ ]
fetch_di_containerreads the root container back out of framework state. - [ ] Every container lookup that can miss raises a
RuntimeErrornamingsetup_di, never aKeyErrororAttributeErroron a private key, and a test pins it. - [ ] A per-unit-of-work builder opens a child container at the right scope, injects the connection as context, and closes it on every exit path.
- [ ] The root container reopens on startup, so a restart doesn't raise
ContainerClosedError, and closes on shutdown so finalizers run. It opens before user startup code and closes after all user shutdown code. - [ ]
close_asyncorclose_syncmatches the framework. - [ ] On an anyio framework, the child closes under
anyio.move_on_after(10, shield=True)and logs a warning when the bound expires, and a test cancels a running handler and checks that every finalizer ran. - [ ]
FromDIacceptsAbstractProvider[T] | type[T]and resolves throughintegrations.Marker(or isintegrations.from_dion the decorator path). - [ ] On the decorator path,
@injectusesparse_markersandresolve_markers, and rewrites the signature only if the framework binds arguments from it. See the decorator path. - [ ] Tests cover the lifespan with a restart, resolution through
FromDI, context injection from the connection object, and the public surface; the coverage gate is green. - [ ] Shutdown-order tests: a shutdown hook registered before
setup_diand one registered after it can both resolve an APP dependency, and the APP finalizer runs after both, over two lifespan cycles. Cover the framework's other places for shutdown code too, such as sub-routers, mounted apps or middleware. Where the framework can't give this order, a test pins what it does and the usage page says so. - [ ] Usage page and
mkdocs.ymlnav entry added in themodern-direpo. - [ ]
examples/app.pywith a smoke test that asserts real injected output, and a READMEUsage example:line with an absolute link. - [ ]
AGENTS.mdandjustfilemirrored; invariants pinned by named tests.