skip to content

In a FastAPI app, how does a dict yielded from the lifespan reach endpoints through request.state, and how does that differ from app.state?

level: middleimportance: should knowfreq 32%

answer

  1. lifespan scope carries a state dict
  2. copied into every request
  3. shallow, not deep
  4. app.state is one shared bag

basics

~20 s

The yielded dict is stored as lifespan state, and the server puts a shallow copy of it into each request, where request.state.model reads it. app.state is one object on the application, set by assignment and read through request.app.state.

solid answer

~40 s

The server passes a `state` dict in the lifespan scope; Starlette updates it with whatever the lifespan yields. For each request or WebSocket the server copies that dict into the request scope, and `request.state` wraps it, readable as `request.state.model` or `request.state["model"]`. The copy is shallow: a key you set on one request is invisible to the next, but every request shares the same model object. `app.state` is different: a single `State` object on the application, filled by assignment such as `app.state.model = m` and read through `request.app.state`. Yielding a dict does not populate `app.state`. I prefer yielded state for resources the lifespan creates and closes, and wrap the read in a small dependency.

code

python · 39 lines
python
from contextlib import asynccontextmanager
from typing import Any

from fastapi import FastAPI, Request


class UpstreamClient:
    """Stands in for a pooled async HTTP client."""

    async def aclose(self) -> None:
        print("client closed")


def load_model(path: str) -> dict[str, Any]:
    return {"path": path}


@asynccontextmanager
async def lifespan(app: FastAPI):
    client = UpstreamClient()
    yield {"model": load_model("/models/classifier.bin"), "upstream": client}
    await client.aclose()


app = FastAPI(lifespan=lifespan)
app.state.started_by = "lifespan-demo"  # app.state: set directly on the application


@app.post("/predict")
async def predict(request: Request) -> dict:
    model = request.state.model  # attribute style
    upstream = request.state["upstream"]  # dict style works too
    request.state.request_note = "only this request sees me"
    return {
        "model": model["path"],
        "has_upstream": isinstance(upstream, UpstreamClient),
        "app_state": request.app.state.started_by,
        "model_on_app_state": hasattr(request.app.state, "model"),
    }

go deeper

for a junior

Remember the two read paths: yielded lifespan state through request.state, attributes set on the app through request.app.state.

for a middle

Walk through the mechanism: state dict in the lifespan scope, updated from the yield, shallow-copied into each request scope by the server.

for a senior

Point out what the shallow copy does and does not protect, why mutable shared objects need care, and why wrapping request.state reads in a dependency eases testing.

for a principal

Set the team convention: which resources live in yielded state versus app.state, how they are typed, and that business code receives them through dependencies.

## Two places to keep shared objects Once the lifespan has created a model or a client, endpoints need a way to reach it. A FastAPI app offers two built-in containers, both instances of Starlette's `State` class, plus the option of a plain module-level variable. - **Lifespan state**: the dict your lifespan function yields, read per request as `request.state`. - **Application state**: `app.state`, an attribute bag on the application object, reached from an endpoint as `request.app.state`. - A **module global**, such as a dict that the lifespan fills in. The FastAPI documentation's model example does this, and it works, but it is the hardest of the three to replace in tests. ## How a yielded dict reaches `request.state` The mechanism runs through the ASGI scopes, the dicts a server passes to the app with every connection: 1. The server creates an empty state dict and passes it in the **lifespan scope** as `scope["state"]`. 2. Your lifespan yields a dict. Starlette's router calls `scope["state"].update(...)` with it. If the server sent no `state` key, Starlette raises `RuntimeError('The server does not support "state" in the lifespan scope.')`; Uvicorn and `TestClient` both send it. 3. For every HTTP request and WebSocket connection, the server puts a **shallow copy** of that dict into the request scope. 4. `request.state` wraps the request's copy. You read it as an attribute (`request.state.model`) or, since Starlette 0.52, as a key (`request.state["model"]`). FastAPI 0.143 runs on Starlette 1.7, so both work. The shallow copy has two consequences that interviewers like to probe: - **Rebinding a name is private to the request.** `request.state.request_note = "x"` adds a key to this request's copy only; the next request does not see it. That is why middleware can safely attach per-request values to `request.state`. - **Mutating a shared object is not private.** The copy holds references to the same objects, so `request.state.model` in every request is the one model, and appending to a yielded list or dict changes it for all requests. Shared mutable objects in lifespan state need the same concurrency care as any global. ## How `app.state` differs `app.state` is a single `State` object created with the application. You assign attributes to it directly, for example `app.state.model = load_model(...)` inside the lifespan, and every request reaches the same object through `request.app.state`. | | Lifespan state | `app.state` | |---|---|---| | How it is filled | yield a dict from the lifespan | assign attributes on the app | | Where an endpoint reads it | `request.state.model` | `request.app.state.model` | | Per-request copy | yes, shallow | no, one shared object | | Visible to a mounted sub-application | yes, copied into its requests | no, the sub-app has its own `app.state` | | Natural owner | the lifespan that creates and closes it | any code holding the app object | A frequent misunderstanding is that yielding `{"model": m}` sets `app.state.model`. It does not: the yielded dict lives in the server's lifespan state, and `app.state.model` raises `AttributeError` unless you also set it there. ## Choosing between them - Prefer **yielded state** for resources the lifespan owns: the code that creates the object and the code that releases it sit together, and the yielded dict documents what requests may use. Describe it with a `TypedDict` to give type checkers a shape. - Use **`app.state`** when something outside a request needs the object too, or when an app factory configures the app before it runs. - Avoid reading `request.state` deep inside business code. Wrap the access in a small dependency, such as `def get_model(request: Request): return request.state.model`, and inject it with `Depends`; endpoints then declare what they need and tests can override it. ## Wrapping the read in a dependency A small dependency keeps `request.state` out of endpoint bodies: ```python def get_model(request: Request) -> dict: return request.state.model ModelDep = Annotated[dict, Depends(get_model)] @app.post("/predict") async def predict(model: ModelDep) -> dict: return {"model": model["path"]} ``` Three things improve at once: - The endpoint signature says it needs the model, which makes the dependency visible in review. - A test can replace `get_model` through `app.dependency_overrides` without running the real lifespan. - If the storage later moves from yielded state to `app.state`, only `get_model` changes. ## A trap in tests Lifespan state exists only after the lifespan has run. `TestClient(app)` used without a `with` block never starts the lifespan, so the first `request.state.model` raises `AttributeError: 'State' object has no attribute 'model'`. Using the client as `with TestClient(app) as client:` runs startup on entry and shutdown on exit.

  • Why can middleware put a per-request value on request.state without it leaking into other requests?
    Because each request gets its own shallow copy of the lifespan state dict. Setting `request.state.user_id` adds a key to that copy only. The protection stops at the top level: mutating an object that came from the lifespan, such as a shared dict, changes it for every request.
  • Does a sub-application mounted with app.mount see the parent's yielded state?
    Yes. Mounting passes the request scope down, including its copy of the parent's lifespan state, so `request.state` in the sub-application holds the parent's keys. The sub-application's own `app.state` is a separate object, and its own lifespan is not run.

  • Yielding a dict from the lifespan sets the same attributes on app.state.
  • Each request gets a deep copy, so mutating the model per request is safe.
  • A value set on request.state in middleware is visible to every later request.
  • request.state is filled even when TestClient is used without a with block.