modern-di-starlette 4.2.0

modern-di integration for Starlette.

Full guide: Starlette integration docs

Usage example: examples/

Installation

uv add modern-di-starlette      # or: pip install modern-di-starlette

Usage

setup_di registers the container, composes the lifespan, and installs middleware that builds a per-connection child container. Decorate an endpoint with @inject and mark parameters with FromDI to receive resolved dependencies. Starlette has no native DI, so @inject is required (there is no Depends).

import dataclasses
import typing

from modern_di import Container, Group, Scope, providers
from modern_di_starlette import FromDI, inject, setup_di
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route


@dataclasses.dataclass(kw_only=True)
class Settings:
    debug: bool = True


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


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


@inject
async def homepage(
    request: Request,
    service: typing.Annotated[UserService, FromDI(Dependencies.user_service)],
) -> JSONResponse:
    return JSONResponse({"debug": service.settings.debug})


app = Starlette(routes=[Route("/", homepage)])
container = Container(groups=[Dependencies])
setup_di(app, container)
container.validate()  # optional fail-fast; must come after setup_di registers its providers

Call setup_di once, after creating the app and before it starts serving. It installs middleware, and Starlette does not allow middleware to be added after startup.

@inject also works on a plain def endpoint. It returns a sync wrapper for a sync function, so Starlette still runs that endpoint in its threadpool.

@inject works the same on the methods of a class-based endpoint. Decorate the handler method, not the class; self and any arguments Starlette passes after the connection are forwarded unchanged, so WebSocketEndpoint.on_receive and on_disconnect inject too:

from starlette.endpoints import HTTPEndpoint, WebSocketEndpoint
from starlette.routing import Route, WebSocketRoute
from starlette.websockets import WebSocket


class Users(HTTPEndpoint):
    @inject
    async def get(
        self,
        request: Request,
        service: typing.Annotated[UserService, FromDI(Dependencies.user_service)],
    ) -> JSONResponse:
        return JSONResponse({"debug": service.settings.debug})


class Echo(WebSocketEndpoint):
    encoding = "text"

    @inject
    async def on_receive(
        self,
        websocket: WebSocket,
        data: str,
        settings: typing.Annotated[Settings, FromDI(Dependencies.settings)],
    ) -> None:
        await websocket.send_text(f"{data} debug={settings.debug}")


app = Starlette(routes=[Route("/users", Users), WebSocketRoute("/echo", Echo)])

An HTTP request opens a Scope.REQUEST child container; a WebSocket connection opens a Scope.SESSION one, both built by the middleware before your handler runs. A WebSocket handler can therefore inject APP- and SESSION-scoped dependencies but not REQUEST-scoped ones. The connection starlette.requests.Request / starlette.websockets.WebSocket are resolvable within DI via the pre-built starlette_request_provider / starlette_websocket_provider context providers. The instance a provider receives is backed by the same ASGI scope as your handler's connection but is a distinct object: read method / url / headers / state from it, not the request body.

A Starlette app mounted under another with Mount can call setup_di with its own container. A route inside the mounted app then resolves from the mounted app's container, and routes outside it resolve from the outer one. Both middlewares open a child container for the connection and both close it when the connection ends. If only the outer app calls setup_di, routes in the mounted app resolve from the outer container.

Starlette runs only the outermost app's lifespan, so the outer app's lifespan also opens and closes the root container of every mounted app that called setup_di, including apps under Host routes, apps mounted with Mount(..., middleware=[...]), and apps mounted more than one level deep. It looks for them at startup, so mounts added after setup_di are included. Each container is opened once and closed at shutdown, after your lifespan code. The mounted app's own lifespan function still does not run. A mounted app whose setup_di was called with manage_lifespan=False is skipped.

Sharing a container

By default the lifespan opens the root container at startup and closes it at shutdown, which runs its APP-scoped finalizers. To share one container between this app and something else that outlives it, such as a second app or a worker, pass manage_lifespan=False and open and close the container yourself:

setup_di(app, container, manage_lifespan=False)


async def main() -> None:
    async with container:
        ...  # run the app and anything else that uses the container

The middleware still opens and closes a child container for every connection. The flag covers only this app's root container: the lifespan still opens and closes the containers of mounted apps that kept the default.

API

📦 PyPI

📝 License

Part of modern-python

Built on modern-di, a dependency-injection framework with an IoC container and scopes.

Browse the full list of templates and libraries in modern-python; the org profile has the categorized index.