fastapi/fastapi
github.com/fastapi/fastapi ↗ · 2950 files · 21.0 MB
FastAPI framework, high performance, easy to learn, fast to code, ready for production --- Documentation: https://fastapi.tiangolo.com Source Code: https://github.com/fastapi/fastapi --- FastAPI is a modern, fast (high-performance), web framework for building
Overview
This is the FastAPI framework source repository at version 0.141.1 — a Pydantic v2-only, Starlette-based ASGI web framework whose distinguishing trick is deriving request parsing, validation, serialization and an OpenAPI 3.1 schema from ordinary Python type hints on endpoint functions. This tree is notably ahead of the classic FastAPI architecture: `include_router()` no longer flattens child routes into the parent but stores an `_IncludedRouter` wrapper resolved at match time, the package ships first-class Server-Sent Events (`fastapi/sse.py`) and JSON-Lines streaming, a `app.frontend()` / `router.frontend()` low-priority static-SPA router, and a bundled agent skill at `fastapi/.agents/skills/fastapi/SKILL.md`. The repo is overwhelmingly documentation and tests: 1692 Markdown files across 13 translated locales, 594 test files, and 464 runnable tutorial sources in `docs_src/` that the test suite executes directly. Its audience is Python API developers, and the repo itself enforces 100% line coverage, strict mypy, ty, and Ruff on every push.
System map
The shipped artifact is the `fastapi/` package (~21k lines across 56 files), a thin-but-deep layer over Starlette and Pydantic v2. `fastapi/applications.py` defines the `FastAPI` app class (subclassing `starlette.applications.Starlette`) and `fastapi/routing.py` — the largest file at 6447 lines — defines `APIRouter`, `APIRoute`, the request handler factory, and the frontend static-file routing. There is no database or storage layer; the only persistent state is in-process route tables and the memoised OpenAPI schema. Everything else in the repo is supporting apparatus: `docs/` (13 locales), `docs_src/` (executable tutorial examples on `PYTHONPATH` during tests), `scripts/` (docs build, translation, release, sponsor tooling), and 23 GitHub Actions workflows. Deployment is a PyPI wheel built by pdm-backend and published via `uv publish` with OIDC trusted publishing; the docs deploy separately to Cloudflare Pages.
- The public API surface is re-exported from `fastapi/__init__.py`, which pins `__version__ = "0.141.1"` and exposes exactly 20 names including `FastAPI`, `APIRouter`, `Depends`, `Security`, `BackgroundTasks`, `UploadFile`, `HTTPException`, `WebSocketException` and Starlette's `status` module.
- `fastapi/routing.py` (6447 lines) and `fastapi/applications.py` (4774 lines) hold the bulk of the logic; `param_functions.py` is third at 2460 lines but is almost entirely `annotated_doc.Doc` docstrings for `Query`/`Path`/`Header`/`Body`/`Depends`.
- Runtime boundaries are ASGI-only: `FastAPI.__call__` injects `root_path` into the scope then delegates to Starlette, and `build_middleware_stack()` composes `ServerErrorMiddleware` → user middleware → `ExceptionMiddleware` → `AsyncExitStackMiddleware` → `self.router`.
- FastAPI-specific per-request state is carried in three ASGI scope keys holding `AsyncExitStack`s: `fastapi_middleware_astack` (set by `AsyncExitStackMiddleware` for closing uploaded files), plus `fastapi_inner_astack` and `fastapi_function_astack` set in the vendored `request_response`/`websocket_session` wrappers for request- and function-scoped `yield` dependencies.
- Pydantic v1 support has been fully removed: `fastapi/_compat/__init__.py` re-exports only from `.shared` and `.v2`, and `PydanticV1NotSupportedError` is raised from `fastapi/encoders.py` and `fastapi/utils.py` when a v1 model is detected.
- Validation is delegated to a single `ModelField` wrapper in `fastapi/_compat/v2.py` that owns a `pydantic.TypeAdapter` and exposes `validate`, `serialize` (dump_python) and `serialize_json` (dump_json).
- The CLI entrypoint `fastapi = "fastapi.cli:main"` is a shim that imports `fastapi_cli.cli.main` and raises a RuntimeError telling the user to `pip install "fastapi[standard]"` if the optional package is absent; `fastapi/__main__.py` calls the same function.
- Runtime dependencies are minimal and pinned by floor: `starlette>=0.46.0`, `pydantic>=2.9.0`, `typing-extensions>=4.8.0`, `typing-inspection>=0.4.2`, `annotated-doc>=0.0.2`, with Python >= 3.10 required.
- `fastapi/staticfiles.py`, `fastapi/templating.py`, `fastapi/testclient.py`, `fastapi/requests.py` and `fastapi/websockets.py` are one-to-three-line re-export shims over Starlette, so those integrations (Jinja2, httpx TestClient) are Starlette's, not FastAPI's.
- Build/test/lint commands are shell scripts: `scripts/test.sh` runs `pytest -n auto --dist loadgroup tests scripts/tests/` with `PYTHONPATH=./docs_src`, `scripts/test-cov.sh` adds `--cov --cov-context=test`, and `scripts/lint.sh` runs `mypy fastapi`, `ty check`, `ruff check`, `ruff format --check`.
- Release shape: `.github/workflows/publish.yml` triggers on GitHub release publication and runs `uv build` then `uv publish` with `id-token: write` (OIDC trusted publishing, no stored PyPI token).
- Docs deploy is a separate pipeline: `deploy-docs.yml` fires on `workflow_run` completion of Build Docs, downloads `docs-site-*` artifacts and pushes to Cloudflare Pages, reporting status through `scripts/deploy_docs_status.py`.
Feature catalog
The user-facing feature set is the decorator API (`@app.get/put/post/delete/options/head/patch/trace`, `@app.websocket`, `@app.middleware`, `@app.exception_handler`), the parameter-declaration vocabulary (`Path`, `Query`, `Header`, `Cookie`, `Body`, `Form`, `File`, `Depends`, `Security`), the auto-generated OpenAPI 3.1 document plus Swagger UI and ReDoc pages, and seven built-in security schemes. This version adds three substantial features beyond classic FastAPI: Server-Sent Events via `response_class=EventSourceResponse`, JSON-Lines streaming from generator endpoints, and `app.frontend()` for serving built SPA assets as low-priority routes. Dependencies gained an explicit `scope` of `"function"` or `"request"`. Two response classes — `ORJSONResponse` and `UJSONResponse` — are now deprecated in favour of a Pydantic `dump_json` fast path.
- `FastAPI.setup()` registers up to four non-schema routes at construction: `openapi_url` (default `/openapi.json`), `docs_url` (`/docs`, Swagger UI), `swagger_ui_oauth2_redirect_url`, and `redoc_url` (`/redoc`); each is skipped when its URL is set to `None`.
- All eight HTTP verb decorators plus `api_route`, `add_api_route`, `websocket`, `add_api_websocket_route`, `websocket_route`, `on_event`, `middleware`, `exception_handler` and `include_router` are defined on `FastAPI` and mirrored on `APIRouter`.
- Server-Sent Events: setting `response_class=EventSourceResponse` on a generator path operation makes the router encode each yielded item into SSE wire format via `format_sse_event`, set `Cache-Control: no-cache` and `X-Accel-Buffering: no`, and inject a `: ping` keepalive comment every `_PING_INTERVAL` (15s) of idleness.
- `ServerSentEvent` is a Pydantic model with `data`, `raw_data`, `event`, `id`, `retry`, `comment`; validators reject multi-line `event`/`id` values and null bytes in `id`, and a model validator forbids setting `data` and `raw_data` together.
- JSON-Lines streaming: when `is_json_stream` is set, generator endpoints are wrapped into a `StreamingResponse` with media type `application/jsonl`, each item serialized by `_serialize_data` and terminated with `\n`.
- `app.frontend(path, directory=..., fallback="auto", check_dir="auto")` serves a built SPA; API routes match first and the frontend is consulted only through `_match_low_priority`, with `fallback="auto"` preferring `404.html` and falling back to `index.html` only for navigation requests that accept `text/html`.
- Seven security schemes ship in `fastapi/security/`: `APIKeyQuery`, `APIKeyHeader`, `APIKeyCookie`, `HTTPBasic`, `HTTPBearer`, `HTTPDigest`, `OAuth2` (with `OAuth2PasswordBearer` and `OAuth2AuthorizationCodeBearer`) and `OpenIdConnect`, plus the `OAuth2PasswordRequestForm` dependency and `SecurityScopes`.
- Dependency scoping is a first-class feature: `params.Depends` is a frozen dataclass carrying `dependency`, `use_cache` and `scope: Literal["function", "request"] | None`, and `DependencyScopeError` is raised at `get_dependant` time if a request-scoped generator dependency depends on a function-scoped one.
- `app.webhooks` is a dedicated `APIRouter` whose routes are documented under the OpenAPI `webhooks` key rather than `paths`.
- `strict_content_type` (default `True`) is threaded from app → router → route → handler; when False, a body with no Content-Type header is still parsed as JSON.
- `ORJSONResponse` and `UJSONResponse` are marked `@deprecated` with `FastAPIDeprecationWarning`, directing users to declare a return type so Pydantic serializes on the Rust side instead.
- `app.dependency_overrides` is a plain dict on the app used as the `dependency_overrides_provider`; `solve_dependencies` re-derives a fresh `Dependant` for any overridden callable so the substitute's own signature is honoured.
Data flow
Input arrives as an ASGI scope. Static declaration time happens first: at decoration, `get_dependant()` walks the endpoint signature with `analyze_param()` and sorts every parameter into `path_params`/`query_params`/`header_params`/`cookie_params`/`body_params`/`dependencies` on a `Dependant` dataclass, each field wrapped in a `ModelField` holding a Pydantic `TypeAdapter`. At request time the handler reads and decodes the body (form vs JSON vs raw bytes), then `solve_dependencies()` recursively resolves sub-dependencies, coerces each parameter group against its `ModelField`, and returns a `SolvedDependency` bundle of values, errors, background tasks and a mutable `Response`. Output flows back through `serialize_response()` (or the streaming serializers) and out as a Starlette `Response`. State owners are the router's route list, the memoised `app.openapi_schema`, and the per-request `AsyncExitStack`s in the ASGI scope.
- Body decoding branches on content type: form bodies go through `await request.form()` with `body.close` pushed onto the middleware exit stack; otherwise raw bytes are parsed as JSON only when the Content-Type maintype is `application` and the subtype is `json` or ends in `+json`, else passed through as bytes.
- A `json.JSONDecodeError` during body parsing is converted into a `RequestValidationError` with a synthetic `json_invalid` error at loc `("body", e.pos)`; any other parse exception becomes a 400 `HTTPException` with detail 'There was an error parsing the body'.
- `solve_dependencies()` resolves sub-dependencies depth-first before extracting path/query/header/cookie values, and memoises each result in `dependency_cache` keyed by `_get_cache_key` — a tuple of `(call, sorted oauth scopes, computed scope)` — so the same dependency called twice in one request runs once unless `use_cache=False`.
- Generator dependencies are entered as context managers by `_solve_generator`: async generators via `asynccontextmanager`, sync generators via `contextmanager_in_threadpool`, and pushed onto `fastapi_inner_astack` unless the dependency declares `scope="function"`, in which case `fastapi_function_astack` is used so it tears down before the response is sent.
- `contextmanager_in_threadpool` deliberately gives `__exit__` its own `CapacityLimiter(1)` so a blocking teardown cannot deadlock against the shared AnyIO threadpool used by a connection pool inside the dependency.
- Form bodies flow through `_extract_form_body`, which reads `UploadFile` values into `bytes` when the declared annotation is bytes, expands sequence-of-bytes fields, and passes through any unmatched form keys as single values or lists.
- `request_body_to_args` collapses to a single un-embedded field when `len(body_fields) == 1 and not embed_body_fields`, and in that case a `BaseModel`-annotated form body is exploded into its model fields before validation.
- Response serialization has a fast path: when a `response_field` exists and no custom `response_class` was supplied, `serialize_response(dump_json=True)` calls `ModelField.serialize_json` and the bytes are wrapped in a bare `Response(media_type="application/json")`, skipping the dict → `json.dumps` round trip.
- Headers set on the injected `Response` object by dependencies are merged into the final response via `response.headers.raw.extend(solved_result.response.headers.raw)` on every branch (SSE, JSONL, raw stream, and normal).
- When `is_body_allowed_for_status_code(status_code)` is false (1xx, 204, 205, 304), the serialized body is discarded by setting `response.body = b""`.
- Validation failures never reach the endpoint: `errors` accumulated by `solve_dependencies` short-circuit the handler and raise `RequestValidationError`, which the default handler renders as HTTP 422 with `{"detail": jsonable_encoder(exc.errors())}`.
- The OpenAPI document is produced once and cached on `app.openapi_schema`, invalidated by comparing `self.router._get_routes_version()` — a recursive counter that sums `_routes_version` across all `_IncludedRouter` children — against `_openapi_routes_version`.
Behavior traces
Three flows dominate: application construction, a normal HTTP request, and OpenAPI generation. Construction is eager — dependants and response fields are computed at decoration time, so route registration errors surface at import. A request walks ASGI middleware, router matching (now indirected through `_IncludedRouter` for included routers), the exit-stack-wrapping `request_response` shim, dependency solving, endpoint invocation, and serialization. Streaming requests diverge at the handler into three branches (SSE, JSONL, raw generator). WebSockets follow a parallel but simpler path with no body parsing and no response serialization.
- Startup trace: `FastAPI.__init__` assigns metadata, asserts `title` and `version` when `openapi_url` is truthy, constructs `self.router = APIRouter(...)` with `dependency_overrides_provider=self`, seeds three default `exception_handlers`, and finally calls `self.setup()` which registers the `/openapi.json`, `/docs`, oauth2-redirect and `/redoc` routes.
- Route registration trace: `@app.get(...)` → `app.router.add_api_route` → `APIRoute.__init__` → `_populate_api_route_state(...)` (which builds `dependant`, `body_field`, `response_field`, `stream_item_field`, `unique_id`) → `self.app = request_response(self.get_route_handler())`.
- Lifespan trace: `APIRouter.app` routes `scope["type"] == "lifespan"` to `self.lifespan`; when no custom lifespan is given, `_DefaultLifespan` (re-vendored after Starlette removed it) calls `router._startup()` / `router._shutdown()` so `on_startup`/`on_shutdown` handlers still work, and `include_router` merges child lifespans via `_merge_lifespan_context`.
- Matching trace for an included router: `APIRouter.app` iterates `self.routes`, an `_IncludedRouter` entry answers `matches()` by building `_EffectiveRouteContext` objects that apply the accumulated prefix/tags/dependencies, then `handle()` dispatches through `_handle_selected`.
- Request trace (happy path): `request_response.app` creates the `Request`, opens `fastapi_inner_astack` and `fastapi_function_astack`, awaits the handler, sends the response, then asserts `response_awaited` — raising a `FastAPIError` naming the bare-`except`-in-a-yield-dependency footgun if the stack unwound without sending.
- Handler trace: `get_request_handler.app` → `_extract_endpoint_context(dependant.call)` → body read → `solve_dependencies(...)` → branch on `is_sse_stream` / `is_json_stream` / generator / plain → `run_endpoint_function` → `serialize_response` → `_build_response_args` → Response.
- Sync endpoints are offloaded: `run_endpoint_function` calls `run_in_threadpool(dependant.call, **values)` when `_is_coroutine_callable(dependant.call)` is false, and `serialize_response` likewise runs `field.validate` in a threadpool for sync endpoints.
- SSE trace: the generator is obtained, wrapped in `_sse_producer_cm()` entered on `fastapi_inner_astack` (so teardown is structured rather than via `GeneratorExit`), each item routed through `_serialize_sse_item` → `format_sse_event`, then yielded through `_sse_with_checkpoints` which `await anyio.sleep(0)` after each chunk so cancellation can be delivered.
- WebSocket trace: `websocket_session` opens the same two exit stacks, `get_websocket_app.app` builds an endpoint context labelled `WS <path>`, calls `solve_dependencies` with no body, raises `WebSocketRequestValidationError` on errors, and otherwise awaits the endpoint directly — there is no response serialization step.
- WebSocket validation failures close the socket with code 1008 (`WS_1008_POLICY_VIOLATION`) and the encoded errors as the reason, via `websocket_request_validation_exception_handler`.
- Frontend fallback trace: `_FrontendStaticFiles.get_response` rejects non-GET/HEAD with 405 or 404, looks up the static resource, redirects directory hits missing a trailing slash, then applies the `404.html` / `index.html` fallback — the latter only if `_is_frontend_navigation_request` finds `text/html` or `application/xhtml+xml` with non-zero q in the Accept header.
- OpenAPI trace: `app.openapi()` → `get_openapi(...)` → `get_fields_from_routes` (collects body/response/stream/param `ModelField`s across `iter_route_contexts`) → `get_flat_models_from_fields` → `get_model_name_map` → `get_definitions` → per-route `get_openapi_path` → `jsonable_encoder(OpenAPI(**output), by_alias=True, exclude_none=True)`.
Testing signals
Testing is the repo's centre of gravity: 594 files under `tests/`, 213 top-level `test_*.py` modules, plus `tests/test_tutorial/` mirroring the 77 directories of `docs_src/` so every documented example is executed. The stack is pytest 9 with `pytest-xdist` (`-n auto --dist loadgroup`), `anyio[trio]`, `inline-snapshot` (used in ~299 files), `dirty-equals` (~31 files), `pytest-timeout` at 20s, and `filterwarnings = ["error"]`. CI enforces `coverage report --fail-under=100` over `fastapi`, `tests` and `docs_src` combined, across a matrix of Windows/macOS/Ubuntu and Python 3.10–3.14t, including free-threaded builds and a Starlette-from-git leg. Performance has its own gates via CodSpeed wall-clock and memory benchmarks. The notable gap is that everything runs through the in-process `TestClient`; there is no test that boots a real uvicorn server.
- The test command is `pytest -n auto --dist loadgroup tests scripts/tests/` with `PYTHONPATH=./docs_src`, so tutorial modules are importable by name from the tutorial tests.
- pytest is configured with `--strict-config --strict-markers --ignore=docs_src`, `strict_xfail = true`, `filterwarnings = ["error"]` and a 20-second per-test timeout, so any unexpected warning fails the suite.
- Coverage is measured over three source roots (`docs_src`, `tests`, `fastapi`) with `parallel = true` and per-runner `CONTEXT`, and the `coverage-combine` CI job ends with `coverage report --fail-under=100`.
- The CI matrix covers Windows and macOS on Python 3.14 and 3.14t (free-threaded) plus targeted Ubuntu/macOS legs for 3.10 (with `uv-resolution: lowest-direct` and a forced `pydantic==2.9.0`), 3.12, 3.13 and 3.14, and a `starlette-git` leg installing Starlette from main.
- A dedicated `regression-test` job checks out the PR base revision, applies only the PR's test diff, and warns via `::warning::` if the changed tests already pass without the code change — an automated 'does this test actually prove the fix' gate.
- Performance regressions are gated by two CodSpeed jobs: `pytest tests/benchmarks --codspeed` in simulation mode and `pytest tests/memory_benchmarks --codspeed` in memory mode.
- `inline-snapshot` is the dominant assertion style for OpenAPI and error payloads, appearing in roughly 299 test files, with CI setting `INLINE_SNAPSHOT_DEFAULT_FLAGS: review` to prevent silent snapshot rewrites.
- The new frontend feature is densely covered: `tests/test_frontend.py` has 40+ tests including Accept-header q-value parsing, path-segment boundary matching, trailing-slash normalization, dependency ordering across nested `include_router`, and `PermissionError`/`ENAMETOOLONG` lookup failures.
- Streaming has dedicated suites for SSE (`tests/test_sse.py`), cancellation (`tests/test_stream_cancellation.py`), item validation errors (`tests/test_stream_json_validation_error.py`), bare types and status codes, plus tutorial tests under `tests/test_tutorial/test_server_sent_events` and `test_stream_json_lines`.
- Security coverage is per-scheme and per-variant — around 30 files spanning `test_security_http_basic*`, `test_security_api_key_*`, `test_security_oauth2*`, `test_security_scopes*`, `test_security_openid_connect*`, plus `test_webhooks_security.py` and `test_top_level_security_scheme_in_openapi.py`.
- Performance claims in the code are pinned by behavioural tests: `tests/test_dump_json_fast_path.py` patches `starlette.responses.json.dumps` and asserts it is never called on the default-response-class path.
- Static analysis is part of the gate, not optional: `.pre-commit-config.yaml` runs ruff check/format, `mypy fastapi` (with `strict = true`), `ty check` (`error-on-warning = true`), typos, and `zizmor` over `.github/workflows/`.
Risk map
As a library, the dangerous surfaces are file IO (the new frontend static server), auth scheme edge cases, and the streaming/exit-stack machinery where resource teardown is subtle. The frontend server is the newest and widest-blast-radius addition: it reads arbitrary files from a user-supplied directory on every unmatched request. The included-router rework is the deepest structural change and introduces a per-request handler rebuild plus a ContextVar hand-off that the code itself flags as temporary. Two caches — `_endpoint_context_cache` and the `lru_cache`d callable classifiers — are keyed by object identity, which is correct only as long as the keyed objects outlive the cache. Repo-level supply-chain risk is actively managed: all Actions are SHA-pinned, `permissions: {}` is the default, `persist-credentials: false` on every checkout, and zizmor lints the workflows.
- `_FrontendStaticFiles` serves files from a user-supplied directory on every request that no API route matched; it mitigates traversal by normalizing the path (`os.path.normpath(os.path.join(*path.split("/")))`), delegating to Starlette's `lookup_path`, and passing `follow_symlink=False`, but the blast radius of a bug here is arbitrary file disclosure.
- `_lookup_path` maps a `PermissionError` on the filesystem to an HTTP 401 response, which conflates a server-side filesystem permission problem with a client authentication failure and can leak the existence of unreadable paths.
- `APIRoute.handle` rebuilds the entire request handler — `request_response(self.get_route_handler())`, which re-runs `get_request_handler` — on every single request whenever an `_EffectiveRouteContext` is present, i.e. for all routes reached through `include_router`.
- The effective-route context is passed from `handle()` to `get_route_handler()` through a module-level ContextVar rather than an argument, and the code carries a `TODO: Replace or deprecate this no-scope hook` — any subclass overriding `get_route_handler()` interacts with this implicitly.
- `_endpoint_context_cache` is an unbounded module-level `dict[int, EndpointContext]` keyed by `id(func)`; entries are never evicted, so a process that creates endpoint callables dynamically grows the dict without bound and could in principle collide on a recycled `id`.
- The callable classifiers `_is_gen_callable`/`_is_async_gen_callable`/`_is_coroutine_callable` use `lru_cache(maxsize=4096)` keyed by a `_CallIdentity` whose `__hash__` is `id(self.call)`, so the cache holds a strong reference to every classified callable and identity reuse after GC is the correctness assumption.
- `HTTPBasic.__call__` base64-decodes the Authorization header and splits on `:`; it returns the raw username and password with no timing-safe comparison anywhere in the framework — constant-time credential checking is left entirely to the application.
- Every security scheme has an `auto_error=False` mode that returns `None` instead of raising 401; a dependency written against that mode that forgets to check for `None` silently authenticates everyone.
- The default Swagger UI and ReDoc pages load JavaScript and CSS from `cdn.jsdelivr.net` (and Google Fonts for ReDoc) with no SRI hashes, so `/docs` and `/redoc` execute third-party CDN code by default in every FastAPI app.
- Swagger UI parameter injection is defended by `_html_safe_json`, which escapes `<`, `>` and `&` before interpolating user-supplied `swagger_ui_parameters` and `init_oauth` into a `<script>` block — but `oauth2_redirect_url` is interpolated into the same script with no escaping.
- `_extract_endpoint_context` calls `inspect.getsourcefile` and `getsourcelines`, embedding absolute server file paths into `ValidationException.__str__`; these appear in logs and in `ResponseValidationError` tracebacks but not in the 422 JSON body, which only serializes `exc.errors()`.
- `request_response` detects a swallowed exception in a `yield` dependency only after the fact, by checking a `response_awaited` flag and raising a `FastAPIError` with a docs link — a heuristic guard rather than a structural fix.
Extension points
FastAPI's extension model is almost entirely composition and subclassing rather than registries. The three canonical hooks are `route_class` on `APIRouter` (swap `APIRoute` for a subclass overriding `get_route_handler`), `dependency_overrides` (a dict keyed by the original callable), and `exception_handlers` (a dict keyed by exception type or status code). Beyond those, `SecurityBase` is the contract for new auth schemes, `generate_unique_id_function` controls operation IDs for client generators, `default_response_class` and `response_class` control output encoding, and `openapi_extra` plus overriding `app.openapi()` let you post-process the schema. The `DefaultPlaceholder`/`Default()` sentinel is the mechanism that lets app → router → route parameter inheritance distinguish 'not set' from 'explicitly set to the default value'.
- `APIRouter(route_class=...)` accepts any `APIRoute` subclass; the documented pattern is to override `get_route_handler()` to wrap the returned coroutine, and `tests/test_custom_route_class.py` plus `docs_src/custom_request_and_route/` exercise it.
- New authentication schemes plug in by subclassing `SecurityBase` — a two-attribute protocol (`model: SecurityBaseModel`, `scheme_name: str`) — which `_is_security_scheme` detects via `isinstance` on the unwrapped callable to feed OpenAPI `securitySchemes`.
- `dependency_overrides` is the testing seam: any object with a `.dependency_overrides` dict can be passed as `dependency_overrides_provider`, and `solve_dependencies` rebuilds the `Dependant` from the substitute callable so its own parameters are resolved.
- `exception_handlers` is a mutable dict keyed by exception class or the ints 500 / `Exception`; `build_middleware_stack` splits the 500/`Exception` entry out as `ServerErrorMiddleware`'s handler and hands the rest to `ExceptionMiddleware`.
- `generate_unique_id_function` (default `generate_unique_id`, which slugifies `route.name + path_format + method`) is inheritable app → router → route and is the hook for client-generator-friendly operation IDs.
- The `DefaultPlaceholder` / `Default()` pattern plus `get_value_or_default` is how a router's setting overrides an app's only when explicitly provided — `Default(JSONResponse)` is not the same as passing `JSONResponse`.
- `_RouterIncludeContext.for_include` and `.combine` are the single place where inherited router attributes (prefix, tags, dependencies, responses, callbacks, deprecated, include_in_schema, unique-id fn, strict_content_type) are merged — new inheritable router options must be added to both methods.
- `_low_priority_routes` on `APIRouter` is a general extension slot, not frontend-specific: `frontend()` appends a `_FrontendRouteGroup` to it, and `_match_low_priority` consults the list only after normal matching and redirect-slashes handling fail.
- Custom response encodings plug in by subclassing `starlette.responses.Response` and passing it as `response_class`; `EventSourceResponse` is itself just such a marker subclass, detected with `lenient_issubclass(actual_response_class, EventSourceResponse)`.
- OpenAPI can be extended at three levels: per-operation `openapi_extra` on a route, whole-document post-processing by reassigning `app.openapi`, and swapping the `openapi_url`/`docs_url`/`redoc_url` routes by passing `None` and registering your own.
- `jsonable_encoder` accepts `custom_encoder` and `sqlalchemy_safe`, and the class→encoder mapping is precomputed by `generate_encoders_by_class_tuples(ENCODERS_BY_TYPE)`, which is the hook for adding new type serializers.
- Middleware plugs in three ways: the `middleware=[Middleware(...)]` constructor argument, `app.add_middleware(...)`, and the `@app.middleware("http")` decorator which wraps the function in `BaseHTTPMiddleware`.
Contributor handoff
Read `fastapi/.agents/skills/fastapi/SKILL.md` first — it is the project's own statement of intended API style and is authoritative for any user-facing example you write. Then read `fastapi/routing.py` (specifically `get_request_handler`, `include_router`, and the `_IncludedRouter`/`_EffectiveRouteContext` pair) and `fastapi/dependencies/utils.py` (`get_dependant`, `analyze_param`, `solve_dependencies`), because nearly every behavioural change lands in one of those. The hard constraints are 100% coverage, strict mypy plus ty, `filterwarnings = ["error"]`, and `inline-snapshot` review mode — a change that is functionally right but leaves a line uncovered or emits a warning will fail CI. Dependency files are off-limits to non-org contributors and enforced by a workflow that auto-closes such PRs.
- Read first, in order: `fastapi/.agents/skills/fastapi/SKILL.md` (conventions), `fastapi/applications.py#L873-1164` (app construction), `fastapi/routing.py#L375-762` (the request handler), `fastapi/dependencies/utils.py#L271-733` (dependency graph + solving), `fastapi/_compat/v2.py#L114-235` (ModelField).
- Run `bash scripts/test.sh` for the suite and `bash scripts/lint.sh` before proposing a change; `scripts/format.sh` applies `ruff --fix` and `ruff format` across `fastapi tests docs_src scripts`.
- Any new library code must be covered — CI runs `coverage report --fail-under=100` over `fastapi`, `tests` and `docs_src` combined, so genuinely unreachable branches need an explicit `# pragma: no cover` (the existing convention in `fastapi/dependencies/models.py`).
- New documentation examples belong in `docs_src/<topic>/tutorialNNN_py310.py` with a matching `tests/test_tutorial/test_<topic>/test_tutorialNNN.py`; `docs_src` is on `PYTHONPATH` during tests and excluded from pytest collection.
- Snapshot assertions must not be silently regenerated: CI sets `INLINE_SNAPSHOT_DEFAULT_FLAGS: review`, and the `[tool.inline-snapshot]` fix/create flags in `pyproject.toml` are commented out on purpose.
- Do not edit `pyproject.toml` or `uv.lock` on behalf of an outside contributor: `guard-dependencies.yml` auto-comments and closes any PR touching them unless the author is an org MEMBER/OWNER or `dependabot[bot]`.
- Only `docs/en/` is hand-edited; the `ensure-non-translated` pre-commit hook rejects modifications to non-English docs outside the translated set, and `README.md` is generated from `docs/en/docs/index.md` by the `generate-readme` hook.
- Trap: `include_router` no longer copies routes. Code that assumes `app.routes` is a flat list of `APIRoute` objects will silently miss included routes — iterate with `routing.iter_route_contexts(routes)` and unwrap via `RouteContext`, the way `get_fields_from_routes` does.
- Trap: after adding or mutating routes at runtime you must go through `add_route`/`add_api_route`/`include_router`/`frontend`, all of which call `_mark_routes_changed()`; appending directly to `router.routes` will leave the cached `app.openapi_schema` stale.
- Trap: three distinct `AsyncExitStack`s live in the scope with different lifetimes — `fastapi_middleware_astack` (files), `fastapi_inner_astack` (request-scoped yield deps and the SSE producer), `fastapi_function_astack` (function-scoped yield deps). Picking the wrong one changes when teardown runs relative to the response being sent.
- Trap: every new streaming code path needs an `await anyio.sleep(0)` checkpoint after each yielded chunk, or client-disconnect cancellation is never delivered — the existing sites cite issue #14680.
- Safe edit boundary: `fastapi/staticfiles.py`, `fastapi/templating.py`, `fastapi/testclient.py`, `fastapi/requests.py`, `fastapi/websockets.py`, `fastapi/logger.py` and `fastapi/middleware/*.py` (except `asyncexitstack.py`) are pure re-exports — behaviour changes belong upstream in Starlette, not here.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 1692 | docs/config |
| Python | 1138 | 99% |
| YAML | 42 | docs/config |
| HTML | 5 | docs/config |
| Shell | 5 | 0% |
| JavaScript | 4 | 0% |
| CSS | 3 | docs/config |
| TOML | 1 | 0% |
Start reading here
Probable source entrypoint: pyproject.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
fastapi/ (56 files)
Repository structure
| Top-level path | Files |
|---|---|
docs/ | 1733 |
tests/ | 594 |
docs_src/ | 464 |
scripts/ | 68 |
fastapi/ | 56 |
.github/ | 28 |
Docs found: README.mddocs/de/docs/_llm-test.mddocs/de/docs/about/index.mddocs/de/docs/advanced/additional-responses.mddocs/de/docs/advanced/additional-status-codes.mddocs/de/docs/advanced/advanced-dependencies.mddocs/de/docs/advanced/advanced-python-types.mddocs/de/docs/advanced/async-tests.mddocs/de/docs/advanced/behind-a-proxy.mddocs/de/docs/advanced/custom-response.md
Package
pyproject.toml — fastapi v{ source = "file", path = "fastapi/__init__.py" }, 56 declared dependencies.
standardfastapi-cli[standard]fastar#httpx#jinja2#python-multipart#email-validator#
CI & config entrypoints
README.md— Repository readme.github/workflows/guard-dependencies.yml— GitHub Actions workflow.github/workflows/smokeshow.yml— GitHub Actions workflow.github/workflows/issue-manager.yml— GitHub Actions workflow.github/workflows/deploy-docs.yml— GitHub Actions workflow.github/workflows/publish.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow.github/workflows/pre-commit.yml— GitHub Actions workflow.github/workflows/add-to-project.yml— GitHub Actions workflow.github/workflows/create-draft-release.yml— GitHub Actions workflow
Structural health signals
Average score 8.2/10 across 96 analyzed source files; 12 hotspots surfaced.
scripts/docs.py— 919 lines, score 4.7 (Large file, Deep nesting)fastapi/routing.py— 1236 lines, score 5.4 (Large file, Deep nesting)fastapi/dependencies/utils.py— 1053 lines, score 5.4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
50113da16fec2026-09-01 — 📝 Update release notesad263df5a4a52026-09-01 — ⬆ Bump the python-packages group across 1 directory with 15 updates (#16285)965b72225a482026-09-01 — 📝 Update release notesfcf472e93a262026-09-01 — ⬆ Bump starlette from 1.3.1 to 1.6.0 (#16289)fc5f36b17d0d2026-09-01 — 📝 Update release notes