FastAPI: Documenting Additional API Responses
Document every possible API response, not just the happy path. The `responses` decorator parameter lets you define alternative status codes and schemas, like a 404 error model, making your OpenAPI docs complete.
FastAPI: Configure API Metadata for Better Docs
Think of FastAPI metadata as your project's business card. It sets the title, version, and description in your auto-generated docs, making your API professional and discoverable. The main footgun is forgetting to update the version string after a release.
HTTP Basic Auth: Simple but Insecure Access Control
HTTP Basic Auth is a simple gatekeeper for your API, prompting users for a username and password directly in the browser. It's useful for internal tools, but never use it over unencrypted HTTP as credentials are sent in a trivially decodable format.
Debugging Python's Asyncio
Debugging asyncio is about finding what's blocking the single-threaded event loop. Use its debug mode to detect slow callbacks and `run_in_executor` to offload CPU-bound work. The biggest mistake is calling blocking code directly, which stalls the entire app.
asyncio Event Loop Policies: A Deprecated Pattern
Think of an event loop policy as the global factory for asyncio's event loops, controlling which loop is created and how it's retrieved. It was used to swap implementations, but the entire API is deprecated in Python 3.14 and will be removed in 3.16.
asyncio: Transports Move Bytes, Protocols Decide Which Bytes
asyncio Transports are the "how" (moving bytes), while Protocols are the "what" (deciding which bytes to send). They're the low-level foundation for libraries handling raw socket I/O.
Async Generators: `yield` in an `async` World
Async generators let you write I/O-bound data streams with the elegance of `yield`. An `async def` function with `yield` produces values one at a time, pausing for I/O without blocking. This is ideal for streaming data from a database.
Python's Asyncio Subprocesses: Non-Blocking Shell Commands
Run external commands without blocking your async app's event loop. `asyncio.create_subprocess_shell` lets you launch processes and await their results, keeping your server responsive.
asyncio Queues: Coordinating Asynchronous Tasks
An asyncio queue is a channel for coroutines to safely exchange data. It's ideal for producer-consumer patterns, like a web crawler feeding URLs to parsers. The main footgun: it's not thread-safe and must be used within a single event loop.
Coordinating Asyncio Tasks with Locks and Events
asyncio sync primitives are traffic signals for coroutines, preventing collisions over shared state. Use a Lock for exclusive access or an Event to signal multiple tasks to proceed. Footgun: these are for asyncio tasks only, not OS threads.
The asyncio Event Loop: One Thread, Many Tasks
The asyncio event loop is a manager for a single-threaded process, juggling tasks to prevent idleness during slow I/O. It's the core of apps like FastAPI, handling network requests efficiently. The footgun is interacting with it directly; use `asyncio.run()`.
FastAPI: Mounting Independent Sub-Applications
Mounting delegates a URL prefix to a separate FastAPI app, giving it its own isolated logic and API docs. Use it to combine microservices or isolate domains. The footgun: the main app's dependencies and middleware do not apply to the sub-app.
Pydantic BaseSettings: Typed, Layered Configuration
Pydantic's BaseSettings treats configuration as typed data, not just strings. It automatically loads and validates settings from environment variables, .env files, and secrets stores into a Python object.
FastAPI: Splitting Your App with `include_router`
`app.include_router` is like plugging a pre-wired power strip of API endpoints into your main FastAPI app. It lets you organize a large app into smaller files by feature, then combine them. The footgun is forgetting to add a URL `prefix` for each router.
FastAPI's Depends: Let the Framework Handle Setup
Think of `Depends` as a pre-flight checklist for your API endpoints. You list required setup tasks, like getting a user or a database session, and FastAPI runs them for you. This is key for sharing logic like auth or database connections across many routes.
FastAPI: Returning HTML with HTMLResponse
Override FastAPI's default JSON output by using `HTMLResponse` to return a raw HTML string directly from an endpoint. It's for simple status pages or server-side rendered components.
Pydantic Computed Fields: Serialize Derived Values
A Pydantic computed field makes a derived value, like an area from width and length, part of your model's serialized output. Use it to include calculated attributes when calling `.model_dump()`.
Pydantic: Configuring Models with `model_config`
Think of `model_config` as the settings panel for your Pydantic models, letting you change validation rules like string length or immutability. Use it to enforce global constraints or make models immutable. The footgun is using the old `class Config:` from V1.
Pydantic's Data Coercion: From Raw Data to Python Types
Pydantic automatically converts raw data, like strings from a JSON request, into the Python types you declare. It's how FastAPI turns a JSON body into a typed Python object.
Pydantic: Required vs. Optional Fields
In Pydantic, a field is required by default. To make it optional, you must provide a default value, like `name: str = "guest"` or `age: int | None = None`. This is key for flexible API request bodies.