Skip to content

Typed application state

Reading a resource as request.app.state.<name> is untyped: a misspelt name or a wrong type surfaces as a 500 at request time. app_state and state_lifespan declare the resources once, as a class, and a route receives them through Depends, so the same mistakes fail type checking.

Declare the state

Declare the resources as a frozen dataclass.

from dataclasses import dataclass

from sqlalchemy.ext.asyncio import AsyncEngine


@dataclass(frozen=True, slots=True, kw_only=True)
class AppState:
    engine: AsyncEngine
    greeting: str

Open it

An opener is an async context manager that builds the state and releases it on shutdown.

from contextlib import asynccontextmanager
from collections.abc import AsyncGenerator

from fastapi import FastAPI
from sqlalchemy.ext.asyncio import create_async_engine


@asynccontextmanager
async def open_state(app: FastAPI) -> AsyncGenerator[AppState]:
    engine = create_async_engine("sqlite+aiosqlite://")
    try:
        yield AppState(engine=engine, greeting="hello")
    finally:
        await engine.dispose()

Pass state_lifespan(...) as lifespan=. An opener that yields something that is not an AppState raises TypeError at startup, and the application never serves.

from rn_forge.fastapi import FastApiApp, state_lifespan

app = FastApiApp(lifespan=state_lifespan(AppState, open_state))

Startup runs the opener, then the optional inner lifespan; shutdown runs in reverse, removing the registration before the opener exits.

Use it in a route

Alias the dependency once and annotate routes with it.

from typing import Annotated

from fastapi import Depends
from rn_forge.fastapi import app_state

State = Annotated[AppState, Depends(app_state(AppState))]


@app.get("/greeting")
def greeting(state: State) -> str:
    return state.greeting

state.greting or state.greeting + 1 is a type error. A route on an application whose lifespan never registered AppState raises RuntimeError("no AppState registered on this application").

Replace it in tests

app_state(AppState) returns the same dependency object every time, so it is the key for an override.

app.dependency_overrides[app_state(AppState)] = lambda: AppState(
    engine=fake_engine, greeting="test"
)

Several state classes

Nest state_lifespan calls through inner; each registers its own class.

lifespan = state_lifespan(
    AppState,
    open_state,
    inner=state_lifespan(CacheState, open_cache),
)