fastapi

FastAPI Conventions

Assume the general Python tooling conventions from the python-stack skill. This skill only covers FastAPI-specific patterns.

App Layout

Prefer a small, explicit structure:

src/<package>/
  main.py
  routers/
    __init__.py
    items.py
  dependencies.py
  schemas.py
  models.py
  settings.py

• Keep the ASGI app in main.py
• Group path operations into routers by bounded area
• Put shared dependency helpers in dependencies.py
• Keep request/response schemas separate from persistence models when that improves clarity

Running the App

Prefer the FastAPI CLI over invoking Uvicorn directly.

uv run fastapi dev src/<package>/main.py
uv run fastapi run src/<package>/main.py

If the project has a stable app entrypoint, prefer configuring it in pyproject.toml:

[tool.fastapi]
entrypoint = "src.<package>.main:app"

Path Operations

Use one HTTP operation per function. Do not collapse multiple methods into a single handler.

Use Annotated for request parameters and dependencies:

from typing import Annotated

from fastapi import APIRouter, Depends, Path, Query

router = APIRouter(prefix="/items", tags=["items"])

ItemId = Annotated[int, Path(ge=1)]
SearchQuery = Annotated[str | None, Query(max_length=100)]


@router.get("/{item_id}")
async def get_item(item_id: ItemId, q: SearchQuery = None) -> dict[str, str | int | None]:
    return {"item_id": item_id, "q": q}

• Prefer reusable type aliases for common dependencies and parameter declarations
• Do not use ... as a required marker in FastAPI parameters or Pydantic fields
• Do not use @app.api_route(..., methods=[...]) unless there is a strong reason

Request and Response Models

Declare response types deliberately.

• Prefer a concrete return type when the returned value already matches the public schema
• Use response_model= when the runtime return value differs from the public schema
• Treat response models as a data-exposure boundary; never return raw internal models that contain secrets or extra fields
• Prefer regular Pydantic models or standard typed containers over RootModel