All examples

Python FastAPI service

Async FastAPI service with SQLAlchemy 2.0, Alembic migrations, strict typing, and money stored in minor units.

Composed from the python-fastapi rules pack. Same file from the CLI: aibysitter init --packs python-fastapi --format claude

Written for this site, CC0, scored by this linter, not tested against any agent.

File

CLAUDE.md, 41 lines

Format

CLAUDE.md

Save as

CLAUDE.md

Category

Python

Tags

• Python
• FastAPI
• SQLAlchemy
• pytest
• uv

License

CC0 1.0, public domain. No attribution needed.

Download CLAUDE.md Lint a copy

Badge

Markdown for a README:

[![Aibysitter lint score: A 100](https://aibysitting.net/gallery/python-fastapi/badge.svg)](https://aibysitting.net/Gallery/python-fastapi)

CLAUDE.md

View rendered

# Python FastAPI service

Python 3.12, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL, Alembic. Dependencies and commands run through uv.

## Commands
- Install: `uv sync`
- Run: `uv run fastapi dev src/<app>/main.py`
- Test: `uv run pytest`
- Lint: `uv run ruff check .`
- Format: `uv run ruff format .`
- Type check: `uv run mypy src`
- New migration: `uv run alembic revision --autogenerate -m "<summary>"`, then read the generated file before committing it.

## Layout
- `src/<app>/api/`: routers, one module per resource.
- `src/<app>/services/`: business logic. No FastAPI imports.
- `src/<app>/db/`: models, session, repositories.
- `tests/` mirrors `src/<app>/`.

## API
- Request and response bodies are Pydantic v2 models in `src/<app>/schemas/`. ORM models are never returned from a route.
- Routes declare `response_model` and an explicit `status_code`.
- `HTTPException` is raised only in routers. Services raise domain errors from `<app>.errors`, and `api/errors.py` maps them to status codes.
- Database sessions come from the `get_session` dependency. Services do not open sessions.

## Money
- Amounts are integers in minor units (cents). No floats for money.
- Every amount is stored with an ISO 4217 currency code next to it.

## Code style
- Every function signature has type hints. `mypy --strict` passes for `src/`.
- Ruff rules live in `pyproject.toml`. A `# noqa` comment always names the rule code.
- Timestamps use `datetime.now(tz=UTC)`. Naive datetimes are a bug.

## Tests
- pytest with `pytest-asyncio`. Async tests use the `async_client` fixture from `tests/conftest.py`.
- Database tests run against the Postgres container started by `docker compose up -d db`.
- A bug fix starts with a failing test that reproduces the bug.

## Done
- `ruff check`, `ruff format --check`, `mypy`, and `pytest` all pass.

1. # Python FastAPI service
3. Python 3.12, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL, Alembic. Dependencies and commands run through uv.
5. ## Commands
6. - Install: `uv sync`
7. - Run: `uv run fastapi dev src/<app>/main.py`
8. - Test: `uv run pytest`
9. - Lint: `uv run ruff check .`
10. - Format: `uv run ruff format .`
11. - Type check: `uv run mypy src`
12. - New migration: `uv run alembic revision --autogenerate -m "<summary>"`, then read the generated file before committing it.
14. ## Layout
15. - `src/<app>/api/`: routers, one module per resource.
16. - `src/<app>/services/`: business logic. No FastAPI imports.
17. - `src/<app>/db/`: models, session, repositories.
18. - `tests/` mirrors `src/<app>/`.
20. ## API
21. - Request and response bodies are Pydantic v2 models in `src/<app>/schemas/`. ORM models are never returned from a route.
22. - Routes declare `response_model` and an explicit `status_code`.
23. - `HTTPException` is raised only in routers. Services raise domain errors from `<app>.errors`, and `api/errors.py` maps them to status codes.
24. - Database sessions come from the `get_session` dependency. Services do not open sessions.
26. ## Money
27. - Amounts are integers in minor units (cents). No floats for money.
28. - Every amount is stored with an ISO 4217 currency code next to it.
30. ## Code style
31. - Every function signature has type hints. `mypy --strict` passes for `src/`.
32. - Ruff rules live in `pyproject.toml`. A `# noqa` comment always names the rule code.
33. - Timestamps use `datetime.now(tz=UTC)`. Naive datetimes are a bug.
35. ## Tests
36. - pytest with `pytest-asyncio`. Async tests use the `async_client` fixture from `tests/conftest.py`.
37. - Database tests run against the Postgres container started by `docker compose up -d db`.
38. - A bug fix starts with a failing test that reproduces the bug.
40. ## Done
41. - `ruff check`, `ruff format --check`, `mypy`, and `pytest` all pass.