# FastAPI source notes

Repo: `fastapi/fastapi`
Local checkout: `/home/ubuntu/repos/rodin-sources/fastapi`

## Why this repo was chosen
- Core framework source plus first-party docs/tests. It is the best place to separate actual repeated FastAPI conventions from tutorial folklore.
- Especially useful here because the same patterns appear in docs examples, framework internals, and tests: router composition, dependency injection, semantic exceptions, and dependency-driven test seams.

## Repeated patterns

### 1) App assembly is declarative: app-level and router-level configuration carry shared concerns
- `docs_src/bigger_applications/app_an_py310/main.py:7-18` creates the app with a global dependency, then includes routers with per-router prefix/tags/dependencies/responses.
- `docs_src/bigger_applications/app_an_py310/routers/items.py:5-10` shows the same concern split one level down: the router owns prefix/tags/dependencies/common responses.
- `fastapi/applications.py:330-348` documents that `FastAPI(..., dependencies=[...])` applies those dependencies to every path operation, including sub-routers.

Why chosen:
- This is not a one-off tutorial style; the public constructor explicitly supports the same pattern the docs teach.

Implication for synthesis:
- Favor centralized app/router configuration for auth headers, tags, common responses, and prefixes.
- Do not describe thin handlers as a style preference only; the framework API is built to move cross-cutting concerns out of handlers.

### 2) Dependencies are first-class request wiring, including teardown-aware resources
- `docs_src/bigger_applications/app_an_py310/dependencies.py:6-13` keeps request validation in dedicated dependency callables that raise HTTP errors directly.
- `fastapi/routing.py:95-136` wraps request handling in nested `AsyncExitStack`s specifically so dependency setup/teardown, including `yield` dependencies, participates in request lifecycle.
- `tests/test_dependency_security_overrides.py:24-29` defines a route entirely in terms of `Security(...)` and `Depends(...)` collaborators.

Why chosen:
- This combines public examples with internal lifecycle machinery. Dependencies are not sugar over helper calls; they are a core execution model.

Caveat / counterexample:
- `fastapi/routing.py:124-130` raises a `FastAPIError` if application code swallows an exception in a `yield` dependency and fails to re-raise. So "just hide cleanup in a dependency" is incomplete; dependency cleanup must preserve exception flow.

Implication for synthesis:
- Prefer dependencies for auth, validated request context, DB/session access, and request-scoped resources.
- Mention that `yield` dependencies are appropriate when setup/teardown must be coupled to a request.

### 3) Handlers and dependencies raise semantic HTTP exceptions; framework handlers translate them
- `docs_src/bigger_applications/app_an_py310/routers/items.py:21-25` raises `HTTPException(404, ...)` when an item is missing.
- `docs_src/bigger_applications/app_an_py310/routers/items.py:28-38` adds operation-specific response metadata and raises `HTTPException(403, ...)` for forbidden updates.
- `fastapi/exception_handlers.py:11-26` turns `HTTPException` and `RequestValidationError` into HTTP responses, including a 422 JSON body for validation failures.
- `fastapi/exception_handlers.py:13-17` also shows a subtle rule: statuses that must not include a body return a bare `Response`, not JSON.

Why chosen:
- The docs examples and framework exception handlers line up exactly: route code signals semantics, framework code owns response formatting.

Implication for synthesis:
- Recommend raising semantic exceptions from route/dependency code instead of hand-building error JSON in each handler.
- Note that response-body behavior is status-sensitive and partly framework-owned.

### 4) Preferred test seam: override dependencies, not handler internals
- `tests/test_dependency_security_overrides.py:24-29` keeps the route signature explicit about collaborators.
- `tests/test_dependency_security_overrides.py:44-63` replaces both ordinary dependencies and security dependencies through `app.dependency_overrides`, then resets overrides after each test.

Why chosen:
- This is a repo-level testing pattern, not an incidental example.

Caveat / counterexample:
- The reset step is part of the pattern, not cleanup fluff: `tests/test_dependency_security_overrides.py:52-63` clears `app.dependency_overrides = {}` after each override-based test.

Implication for synthesis:
- When describing testing conventions, emphasize overrideable dependency seams as the intended unit of substitution.

## Strong citation candidates
- Global dependencies apply across sub-routers: `fastapi/applications.py:330-348`
- Dependency lifecycle is request-lifecycle machinery, not style guidance: `fastapi/routing.py:95-136`
- `yield` dependency exception-swallowing failure mode: `fastapi/routing.py:124-130`
- Central exception translation, including no-body statuses: `fastapi/exception_handlers.py:11-17`

## Pattern candidates supported by this repo
- centralize cross-cutting concerns in app/router configuration
- use dependencies as the main request-wiring mechanism
- use `yield` dependencies for request-scoped resources with teardown
- raise semantic `HTTPException`s from handlers/dependencies and let framework handlers shape responses
- test by overriding dependencies and resetting overrides explicitly