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?
answer
- lifespan scope carries a state dict
- copied into every request
- shallow, not deep
- app.state is one shared bag
basics
~20 sThe 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 sThe 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 linesfrom 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
Remember the two read paths: yielded lifespan state through request.state, attributes set on the app through request.app.state.
Walk through the mechanism: state dict in the lifespan scope, updated from the yield, shallow-copied into each request scope by the server.
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.
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.