In FastAPI 0.143, how do Depends(scope="function") and the default "request" scope change when a yield dependency's cleanup runs?
answer
- two exit stacks, one inside the other
- around the function vs around the request
- which side of the response
- request scope cannot use a function-scoped child
basics
~20 sWith scope="function", FastAPI runs a yield dependency's cleanup right after the endpoint returns, before the response is sent; with the default "request" it runs after the response. A request-scoped yield dependency cannot depend on a function-scoped one.
solid answer
~40 sFastAPI 0.121 added `scope` to `Depends` for yield dependencies. FastAPI keeps two exit stacks per request: a function stack closed as soon as the path operation function returns, and a request stack closed after the response has been sent, including any background tasks. `Depends(get_client, scope="function")` puts the dependency on the first, so a resource the endpoint alone needs is released before a slow response goes out. The default, `scope="request"`, keeps it open until the response is finished, which is what a streamed body that reads from it needs. Because a dependency's cleanup may still use its sub-dependencies, a request-scoped yield dependency cannot depend on a function-scoped one: FastAPI raises `DependencyScopeError` when the route is declared. The reverse, a function-scoped dependency on a request-scoped one, is allowed.
code
python · 46 linesimport tempfile
from pathlib import Path
from typing import Annotated
from fastapi import Depends, FastAPI
app = FastAPI()
class UpstreamClient:
"""Stand-in for an outbound HTTP client that holds pooled connections."""
async def fetch(self, report_id: str) -> str:
return f"data for {report_id}"
async def aclose(self) -> None:
print("upstream client closed")
async def get_upstream():
client = UpstreamClient()
try:
yield client
finally:
await client.aclose()
def get_workdir():
tmp = tempfile.TemporaryDirectory()
try:
yield Path(tmp.name)
finally:
tmp.cleanup()
print("workdir removed")
UpstreamDep = Annotated[UpstreamClient, Depends(get_upstream, scope="function")]
WorkdirDep = Annotated[Path, Depends(get_workdir)] # default scope="request"
@app.get("/reports/{report_id}")
async def build_report(report_id: str, upstream: UpstreamDep, workdir: WorkdirDep):
data = await upstream.fetch(report_id)
(workdir / "report.txt").write_text(data)
print("endpoint returned")
return {"report": data}go deeper
Remember the two values and the default: function closes before the response, request closes after it, and a yield dependency without scope is request-scoped.
Explain the two exit stacks, the order of a request with both scopes and a background task, and why the request-on-function shape raises DependencyScopeError at import time.
Diagnose the streaming case: a function-scoped resource is closed before the body streams. Show when early release is worth it and when it breaks the response.
Decide whether the team's shared resource aliases default to function scope for capacity or request scope for safety, and document which endpoints may opt out.
## Two exit points for one request A **yield dependency** runs setup code up to its `yield`, hands the yielded value to the endpoint, and runs **exit code** afterwards. The `scope` argument of `fastapi.Depends`, added in FastAPI 0.121, decides *when* that exit code runs. For every HTTP request FastAPI opens two `contextlib.AsyncExitStack` objects, one nested inside the other: - the **function stack**, closed as soon as the path operation function returns; - the **request stack**, closed only after the response has been sent to the client. When FastAPI resolves a yield dependency it enters it on one of them: `scope="function"` picks the function stack, and `scope="request"`, or no `scope` at all, picks the request stack. If you write no `scope`, a yield dependency is request-scoped. | | `scope="function"` | `scope="request"` (default) | |---|---|---| | Setup runs | before the endpoint | before the endpoint | | Exit code runs | after the endpoint returns, **before** the response is sent | **after** the response is sent | | Wraps | the path operation function | the whole request and response | | Good for | a resource only the endpoint uses | anything the response body still reads | ## The timeline of one request An endpoint with one function-scoped dependency, one request-scoped dependency and a background task runs in this order: 1. setup of both dependencies, in resolution order; 2. the endpoint body; 3. exit code of the **function-scoped** dependency; 4. the response is sent; 5. the background task runs, because a Starlette response runs its background tasks as part of sending; 6. exit code of the **request-scoped** dependency. Within one stack, exits still run last in, first out. When the endpoint raises instead of returning, both stacks unwind, function stack first, before the error response is built, so on the error path every yield dependency finishes before the client gets anything. ## When to choose which Use `scope="function"` when the endpoint is the only consumer and the response may take a while to deliver: an outbound client used to fetch data that is then returned as a plain body, or a pooled resource used only to check something. Releasing it early frees capacity for other requests. Keep the default when anything after the endpoint returns still needs the resource: - a streamed response whose generator keeps reading from it; - a body that is produced lazily from the yielded object; - code that inspects the yielded object after the response is complete. A function-scoped resource handed to a streaming body is already closed when streaming starts. Scope is also part of how FastAPI caches a dependency within one request. If the same generator is declared with `scope="function"` in one place and with the default scope in another, FastAPI treats them as two separate dependencies: setup runs twice and two objects are injected, each closed at its own time. Declare a shared resource with one scope everywhere, usually through a single `Annotated` alias. The database variant of this choice, a session released early, is covered in the material on a session per request. ## The sub-dependency rule A dependency's exit code may still use the values it received, so those values must close **after** it. A request-scoped dependency closes after the response; a function-scoped sub-dependency would already be gone by then. FastAPI therefore forbids that shape: - a yield dependency with `scope="request"` (explicit or default) **cannot** depend on one declared with `scope="function"`; - a dependency with `scope="function"` **may** depend on both function- and request-scoped ones; - a dependency that uses `return` has no exit code, so it may depend on a function-scoped yield dependency. The check runs while FastAPI analyses the endpoint's signature, which happens when the route decorator executes at import time. The error is `fastapi.exceptions.DependencyScopeError`, a subclass of `FastAPIError`, with the message `The dependency "<name>" has a scope of "request", it cannot depend on dependencies with scope "function".` The app fails to start rather than failing on the first request. ## How it got here Exit-code timing has moved twice. Before 0.106 it ran after the response; 0.106 moved it before the response to stop holding resources while bytes travelled over the network; 0.118 moved it back after the response because a streamed response found its resources already closed. 0.121 kept "after the response" as the default and added `scope="function"` as the explicit opt-in for the early exit.
- Why is a function-scoped dependency allowed to depend on a request-scoped one, but not the other way round?A dependency's exit code may still use its sub-dependencies, so they must close after it. A function-scoped parent closes before the response and its request-scoped child after it, which is safe. A request-scoped parent closes after the response, when a function-scoped child would already be closed, so FastAPI rejects it with `DependencyScopeError`.
- What goes wrong if a function-scoped dependency's value is read by a streamed response body?Its exit code has already run when the response starts streaming, because `scope="function"` closes it as soon as the endpoint returns. The streaming generator then reads from a closed resource and fails part-way through the body, after the status line has been sent. Keep the default request scope for anything a stream reads.
- Does scope change the error path when the endpoint raises?Not the ordering that matters to the client. When the endpoint raises, the exception unwinds through both stacks, so function- and request-scoped dependencies both see it at their `yield` and finish their cleanup before FastAPI's exception handlers build the error response.
- scope="function" re-creates the dependency for every function that declares it.
- The default scope of a yield dependency is "function".
- Both scopes run cleanup before the response; scope only changes setup order.
- FastAPI only notices a scope mismatch when the first request arrives.
- A request-scoped dependency may depend on a function-scoped one if declared first.
Assumes FastAPI 0.143; Depends(scope=...) arrived in 0.121, and older material that says cleanup always runs before (0.106 to 0.117) or after the response predates it.