modern-di-starlette 3.3.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 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.

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.