Skip to content

Usage with Starlette

Starlette has no dependency injection of its own, so modern-di-starlette provides an @inject decorator that fills the handler parameters marked with FromDI. setup_di installs a middleware that gives each HTTP request a Scope.REQUEST child container and each websocket connection a Scope.SESSION one, and wraps the app's lifespan, which closes the root container on shutdown.

Installation

uv add modern-di-starlette
pip install modern-di-starlette
poetry add modern-di-starlette

Usage

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, 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: Request,
    report: typing.Annotated[Report, FromDI(Report)],
) -> JSONResponse:
    return JSONResponse(report.as_dict())


app = Starlette(routes=[Route("/report", get_report)])
container = Container(groups=[AppGroup])
setup_di(app, container)
container.validate()

Call container.validate() after setup_di. A factory that takes a Starlette Request depends on the context provider that setup_di registers, so validating before it fails with ValidationFailedError.

Injecting into handlers

FromDI takes a type, as above, or a provider such as FromDI(AppGroup.report). @inject resolves it from the connection's child container, which it finds through the Request or WebSocket the handler receives. A decorated handler without one among its positional arguments raises TypeError, and a request that did not pass through the setup_di middleware raises RuntimeError.

Since modern-di-starlette 4.1.0, @inject also takes a plain def endpoint or HTTPEndpoint method. It returns a sync wrapper for it, so Starlette still runs the endpoint in its threadpool:

@inject
def get_report_sync(
    request: Request,
    report: typing.Annotated[Report, FromDI(Report)],
) -> JSONResponse:
    return JSONResponse(report.as_dict())


app.routes.append(Route("/report-sync", get_report_sync))

Class-based endpoints

@inject works the same on the methods of an HTTPEndpoint or WebSocketEndpoint subclass. Decorate the 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 WebSocketRoute
from starlette.websockets import WebSocket


class ReportEndpoint(HTTPEndpoint):
    @inject
    async def get(
        self,
        request: Request,
        report: typing.Annotated[Report, FromDI(Report)],
    ) -> JSONResponse:
        return JSONResponse(report.as_dict())


class EchoEndpoint(WebSocketEndpoint):
    encoding = "text"

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


app.routes.extend([Route("/report-endpoint", ReportEndpoint), WebSocketRoute("/echo", EchoEndpoint)])

Scopes and lifecycle

An HTTP request gets a Scope.REQUEST child container and a websocket connection a Scope.SESSION one; see the scope hierarchy. The middleware builds the child before your handler runs and closes it once the app is done with the connection: after the response is sent for HTTP, and when the socket closes for a websocket. The close is shielded from cancellation, so a request cancelled by an anyio scope such as move_on_after still runs its finalizers. A close that takes longer than 10 seconds is abandoned, with a warning on the modern_di_starlette.main logger.

The root container is open from the moment you construct it. setup_di wraps the app's lifespan, and the state yielded by a lifespan= you passed to Starlette() passes through. Since modern-di-starlette 4.3.0, the container is the outer context: it reopens before your lifespan's startup code and closes with close_async() after its shutdown code. Both can resolve APP-scoped dependencies, and APP finalizers run last. Earlier releases closed the container before your shutdown code ran. The lifespan shutdown is the only thing that closes the root container.

Since modern-di-starlette 4.2.0, setup_di(app, container, manage_lifespan=False) leaves the root container's open and close to you, for a container shared with another app; see Lifecycle. The flag covers only this app's own container. The lifespan still opens and closes the container of each mounted app, unless that app's own setup_di set the flag to False.

Mounted apps

An app mounted with Mount can call setup_di with its own container. Its routes then resolve from that container, and the routes of a mounted app without setup_di resolve from the outer app's. Before modern-di-starlette 4.1.0, a mounted app with its own setup_di raised KeyError after every response.

Starlette runs only the outermost app's lifespan. Since 4.1.0, the lifespan that setup_di composes on the outer app also opens and closes the root container of every mounted app that called setup_di, under Mount and Host routes at any depth. Since 4.1.1 this includes an app mounted with Mount(app, middleware=[...]). It looks for them at startup, before your lifespan's startup code. Mounts added after setup_di are found, but since 4.3.0 a mount added inside your lifespan is not, so add mounts before the app starts.

from starlette.routing import Mount

admin_app = Starlette(routes=[Route("/report", get_report)])
admin_container = setup_di(admin_app, Container(groups=[AppGroup]))
outer_app = Starlette(routes=[Mount("/admin", app=admin_app)])
setup_di(outer_app, Container(groups=[AppGroup]))

Deployment: mounted sub-apps and disabled lifespan

Deployments that disable lifespan (for example Mangum with lifespan="off") skip the lifespan events, and so does a setup_di-wired app mounted under an outer app that has no setup_di of its own. Requests still succeed, because the root container is open from construction, but nothing closes it, so its finalizers never run. Call setup_di on the top-level served app, or close the root yourself (await container.close_async()) at shutdown.

Websockets

For per-message work inside a websocket's Scope.SESSION container, open a Scope.REQUEST child of it. FromDI(Container) gives the handler the SESSION container:

@inject
async def report_socket(
    websocket: WebSocket,
    session_container: typing.Annotated[Container, FromDI(Container)],
) -> None:
    await websocket.accept()
    async for _ in websocket.iter_text():
        async with session_container.build_child_container(scope=Scope.REQUEST) as request_container:
            report = request_container.resolve(Report)
            await websocket.send_json(report.as_dict())


app.routes.append(WebSocketRoute("/ws", report_socket))

Injecting a REQUEST-scoped provider such as FromDI(Report) straight into a websocket handler raises ScopeNotInitializedError, because no REQUEST container exists for the connection.

Framework context objects

The integration makes starlette.requests.Request and starlette.websockets.WebSocket available to your factories. See Framework context objects for how implicit and explicit resolution work.

  • starlette_request_provider provides the current starlette.requests.Request (REQUEST scope).
  • starlette_websocket_provider provides the current starlette.websockets.WebSocket (SESSION scope).

The object these providers hold is one the middleware builds, so it is a different object from the Request or WebSocket your handler receives. Both wrap the same ASGI scope and share request.state.

A factory can receive the request by type, or name the provider in kwargs:

import modern_di_starlette


def describe_request(request: Request) -> dict[str, str]:
    return {"method": request.method, "url": str(request.url)}


class RequestGroup(Group):
    by_type = providers.Factory(describe_request, scope=Scope.REQUEST, bound_type=None)
    by_provider = providers.Factory(
        describe_request,
        scope=Scope.REQUEST,
        bound_type=None,
        kwargs={"request": modern_di_starlette.starlette_request_provider},
    )

See also

API

Symbol Description
setup_di(app, container, *, manage_lifespan=True) Stores the container on app.state, registers the request and websocket context providers, wraps the lifespan so the container reopens before your startup code and closes after your shutdown code, along with the root container of each mounted app that called setup_di, and installs the middleware that builds a per-connection child container. With manage_lifespan=False, this app's own container is left to you. Returns the container.
FromDI(dependency) Marker (used with @inject) that resolves a provider or type from the per-connection child container.
inject Decorator for a sync or async def handler(connection: Request | WebSocket, ...), a function endpoint or a method of an HTTPEndpoint / WebSocketEndpoint subclass; resolves its FromDI-annotated parameters. Raises TypeError when the handler receives no Request or WebSocket positionally, and RuntimeError naming setup_di when the connection did not pass through the middleware.
fetch_di_container(app) Returns the root Container stored on app.state.
starlette_request_provider ContextProvider for starlette.requests.Request (REQUEST scope), auto-registered.
starlette_websocket_provider ContextProvider for starlette.websockets.WebSocket (SESSION scope), auto-registered.