skip to content

Yield Teardown & Scopes

A dependency that yields sets up before the handler and cleans up after it, and its scope decides whether cleanup waits for the response. Interviewers ask where a session commit belongs.

on this pageshow

explore

questions

5

In FastAPI, how does a dependency written with yield instead of return run setup and cleanup around a request?

level: juniorimportance: must knowfreq 62%

answer

  1. before, during, after
  2. the yielded value is injected
  3. try / finally around the yield
  4. cleanup in reverse order
  5. default timing: after the response

basics

~20 s

FastAPI runs the code before the yield ahead of the endpoint, injects the yielded value, and runs the code after it once the request finishes, by default after the response is sent. Wrap the yield in try/finally.

solid answer

~40 s

FastAPI turns a dependency that uses `yield` instead of `return` into a context manager. Everything up to the `yield` runs before the path operation, the yielded value is what the parameter receives, and everything after the `yield` is exit code. In FastAPI 0.143 a yield dependency defaults to `scope="request"`, so after a normal return its exit code runs once the response has been sent. If the endpoint raises, FastAPI throws that exception into the generator at the `yield`, so code that must always run belongs in `finally`. With several yield dependencies, exit code runs in reverse order of setup, so a dependency's cleanup can still use its sub-dependencies. Use exactly one `yield`, written as a plain `def` or `async def` generator; FastAPI does the wrapping itself.

code

python · 25 lines
python
import tempfile
from pathlib import Path
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException

app = FastAPI()


def get_workdir():
    tmp = tempfile.TemporaryDirectory(prefix="render-")
    print("setup:", tmp.name)
    try:
        yield Path(tmp.name)  # this value is what the endpoint receives
    finally:
        tmp.cleanup()  # runs whether the endpoint returned or raised
        print("teardown: removed", tmp.name)


@app.post("/renders/{name}")
def create_render(name: str, workdir: Annotated[Path, Depends(get_workdir)]):
    if name == "bad":
        raise HTTPException(status_code=400, detail="Unsupported template")
    (workdir / f"{name}.txt").write_text("rendered")
    return {"files": sorted(p.name for p in workdir.iterdir())}

go deeper

for a junior

Recall the three parts: code before the yield, the yielded value injected into the endpoint, and exit code after it. Say that cleanup belongs in a finally block.

for a middle

Explain that the endpoint's exception is thrown in at the yield, that nested dependencies close in reverse order, and that the default request scope runs cleanup after the response.

for a senior

Show you know where cleanup timing bites: an error response is sent only after cleanup, a successful one before it, and anything the yielded object is handed to must not outlive the request.

for a principal

Treat yield dependencies as the team's standard for every per-request resource, and set a convention that cleanup lives in finally so reviews can spot a leak at a glance.

## What a yield dependency is A **dependency** in FastAPI is a callable that you hand to `fastapi.Depends`; FastAPI calls it for each request and passes its result to the **path operation function** (the endpoint). A normal dependency uses `return`. A **yield dependency** uses `yield` instead, and that single change gives it a second half: code that runs *after* the endpoint is done. Internally FastAPI wraps an `async def` generator with `contextlib.asynccontextmanager` and a plain `def` generator with `contextlib.contextmanager` (run through its thread pool), then enters the result on an exit stack it keeps for the request. You never write those decorators yourself. | | `return` dependency | `yield` dependency | |---|---|---| | Value injected | the returned value | the yielded value | | Code after the value | none | **exit code**, run later | | Sees the endpoint's exception | no | yes, thrown in at the `yield` | | Typical use | parsing, lookups | anything opened that must be closed | ## The lifecycle, step by step For a request to an endpoint that depends on `get_workdir`, which creates a temporary directory: 1. FastAPI calls `get_workdir()` and runs it up to the `yield`; the directory is created. 2. The yielded `Path` becomes the endpoint's `workdir` argument. 3. The endpoint runs and returns, or raises. 4. On a normal return, FastAPI builds and sends the response; with the default `scope="request"` the exit code runs **after** the response has gone out, including after any background tasks attached to it. 5. If the endpoint raised, FastAPI throws the exception into the generator at the `yield` first, and only then do its exception handlers build the error response. The default timing is one of the things that changed between releases, which is why this answer assumes FastAPI 0.143. `Depends(scope="function")` moves the exit code to just after the endpoint returns, before the response is sent. ## What goes on each side of the yield The split maps naturally onto resources that are acquired and released: | Before the `yield` | After the `yield` | |---|---| | create a temporary working directory | delete it with its contents | | open an outbound client or connection | close it and release its pool | | acquire a lock or a quota slot | release it | | record a start time | record the duration | The yielded object can be anything: the directory's `Path`, the client, or a small object bundling both. Other dependencies may declare it as a sub-dependency and receive the same value. ## Writing cleanup that always runs Because an exception from the endpoint arrives *at the `yield` line*, a bare statement after the `yield` is skipped whenever the endpoint fails. That is why the documented shape is: - `try:` around the `yield`, so the exception can be seen; - `finally:` for the steps that must happen on both paths, such as removing the temporary directory or closing an outbound client; - an `except` only when you have something to do with that specific error, and then a bare `raise` so FastAPI still sees it. Setup that fails before the `yield` behaves differently: the endpoint never runs, and the dependency's own exit code is not reached (a `finally` runs only if the failing line was already inside the `try`). ## Several yield dependencies: reverse order Dependencies form a tree, and any of them may yield. FastAPI enters them in the order it resolves them, sub-dependencies first, and closes them in **reverse** (last in, first out). If `get_c` depends on `get_b`, which depends on `get_a`, the exit code runs `get_c`, then `get_b`, then `get_a`. The reason is practical: a dependency's cleanup may still need the value it received, so that value must still be open when the cleanup runs. ## Rules that trip people up - **One `yield` per dependency.** A second `yield` makes the underlying context manager fail with `RuntimeError: generator didn't stop`. - **Do not decorate it with `@contextlib.contextmanager`.** FastAPI looks through the decorator, sees a generator function, wraps it again, and the request fails with a server error. - **`def` or `async def` both work.** A `def` generator runs its setup and exit code in worker threads; an `async def` one runs on the event loop. - **The yielded object must not outlive the request.** Anything that keeps using it after the exit code has run, such as work handed off to a background task, should open its own resource instead. The database session recipe built on this mechanism, with its commit and rollback, is covered in the material on a session per request.

  • If the endpoint raises, does a yield dependency's cleanup run before or after the error response is sent?
    Before. The exception unwinds through the exit stack first, so FastAPI throws it into each yield dependency at its `yield` and runs their `finally` blocks, and only then do the exception handlers build and send the error response. That holds even for the default `scope="request"`, whose cleanup otherwise waits until after a successful response.
  • What happens when a yield dependency raises before reaching its yield?
    The endpoint never runs and the exception goes to FastAPI's exception handling, so an `HTTPException` raised there becomes the error response. That dependency's code after the `yield` never runs; its `finally` runs only if the failing line was inside the `try`. Yield dependencies that already finished setup are still closed, in reverse order.
  • Why does FastAPI close nested yield dependencies in reverse order?
    Because a dependency's exit code may still use what it received. If a cleanup step writes a final record through a client provided by a sub-dependency, that client must still be open, so FastAPI closes the outer dependency first and the sub-dependency after it, last in, first out.

A tool-hire counter: staff prepare the kit before handing it over, you use it for the job, and they check it back in and clean it only after you have left, whatever state it comes back in.

  • A plain statement after the yield runs even when the endpoint raises.
  • You should decorate a yield dependency with @contextlib.contextmanager first.
  • By default the code after the yield always runs before the response is sent.
  • Nested yield dependencies are closed in the same order they were set up.
  • Only async def generators can be used as yield dependencies.

Assumes FastAPI 0.143; from 0.106 to 0.117 the exit code ran before the response was sent, 0.118 moved it back after the response, and 0.121 added scope to choose.

open as a page

In FastAPI 0.143, how do Depends(scope="function") and the default "request" scope change when a yield dependency's cleanup runs?

level: middleimportance: should knowfreq 42%

basics

~20 s

With 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.

open as a page

A FastAPI yield dependency catches the endpoint's exception with except Exception and never re-raises it; what does the client get, and what do the logs show?

level: seniorimportance: should knowfreq 40%

basics

~20 s

In FastAPI 0.143 the client gets a 500, even for an HTTPException, and with the default scope the log shows a FastAPIError about a response not awaited instead of the original error. End the except with raise.

open as a page

In FastAPI 0.143, a yield dependency raises HTTPException(413) in its code after the yield on a successful request; what does the client receive?

level: seniorimportance: should knowfreq 25%

basics

~20 s

With the default request scope the client receives the endpoint's 200, because the response was already sent; the HTTPException only produces a RuntimeError in the server log. Declared with Depends(scope="function"), the 413 replaces the response.

open as a page

In FastAPI, where do a plain def yield dependency's setup and cleanup run, and why does its cleanup get its own thread limiter?

level: middleimportance: nice to knowfreq 20%

basics

~20 s

FastAPI runs a def yield dependency's setup in the thread pool under anyio's shared limiter, and its exit code in a worker thread under a fresh one-slot limiter, so cleanup never queues behind the shared one.

open as a page