python-samples-fastapi-restful: Instructions file for Claude Code

CLAUDE.md

Claude Code

• Run /pre-commit to execute the full pre-commit checklist for this project.
• Run /pre-release before tagging a release.
• See .claude/skills/create-issue/SKILL.md for the SDD issue workflow, and .claude/skills/add-endpoint/SKILL.md for the endpoint/schema workflows.

Structure

Layer rule: Routes → Services → SQLAlchemy → SQLite. Routes handle HTTP concerns only; business logic belongs in services. Never skip a layer. tools/ is legacy (superseded by Alembic migrations); gunicorn.conf.py is used by the Docker entrypoint.

Coding Guidelines

• Naming: snake_case (files, functions, variables), PascalCase (classes)
• Type hints: Required everywhere — functions, variables, return types
• Async: All routes and service functions must be async def; use AsyncSession (never Session); use aiosqlite (never sqlite3); use SQLAlchemy 2.0 select() (never session.query())
• API contract: camelCase JSON via Pydantic alias_generator=to_camel; Python internals stay snake_case
• Models: PlayerRequestModel (no id, used for POST/PUT) and PlayerResponseModel (includes id: UUID, used for GET/POST responses). One request model intentionally covers both POST and PUT — per-operation differences (conflict check on POST, mismatch guard on PUT) are handled at the route layer, not by duplicating the model. Never reintroduce the removed PlayerModel; it was removed because a single flat model conflated ORM, request, and response concerns.
• Primary key: UUID surrogate key (id) — opaque, internal, used for GET by id only. UUID v4 for API-created records; UUID v5 (deterministic) for migration-seeded records. squad_number is the natural key — human-readable, domain-meaningful, used for all mutation endpoints (PUT, DELETE) and preferred for all external consumers
• Caching: cache key "players" (hardcoded); clear on POST/PUT/DELETE; X-Cache header (HIT/MISS)
• Errors: Catch specific exceptions with rollback in services; Pydantic validation returns 422 (not 400); squad number mismatch on PUT returns 400 (not 422 — it is a semantic error, not a validation failure)
• Logging: logging module only; never print()
• Tests: integration tests against the real SQLite DB (seeded via Alembic migrations) via TestClient — no mocking. Naming pattern test_request_{method}_{resource}_{context}_response_{outcome}; docstrings single-line, concise; tests/player_fake.py for test data; tests/conftest.py provides a function-scoped client fixture for isolation; tests/test_main.py excluded from Black; tests/test_migrations.py covers Alembic downgrade paths
• Decisions: justify every decision on its own technical merits; never use "another project does it this way" as a reason — that explains nothing and may mean replicating a mistake
• Avoid: sync DB access, mixing sync/async, print(), missing type hints, unhandled exceptions