fastapilisted
Install: claude install-skill mfmezger/ai_agent_dotfiles
# 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:
```text
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.
```bash
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`:
```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:
```python
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 alias