python-dev

Python Conventions

Stack choices

• FastAPI — async endpoints, dependency injection via Depends(), lifespan events
• Pydantic v2 — schemas at all boundaries, ConfigDict(from_attributes=True) for ORM models
• SQLAlchemy 2.0 — select() style, Mapped[], mapped_column(). No legacy 1.x Query API
• Alembic — async migrations, always review autogenerated output
• pytest + pytest-asyncio + httpx AsyncClient for testing

Coding standards

• Async-first — all I/O (DB, HTTP, LLM) must be async. No blocking calls in async paths
• Type hints everywhere — modern Python syntax (PEP 604 unions, generics)
• Pydantic at all boundaries — no raw dicts across module boundaries
• Separate request and response models — don't reuse the same schema for both
• Structured logging — use the project's logging setup, not bare print()
• Meaningful errors — HTTPException with correct status codes and clear messages
• Small, focused functions — single responsibility

Architecture

• Business logic lives in service modules, not in endpoint functions
• Endpoints: validate input, call services, return responses
• Use Depends() for sessions, config, auth, services
• Group by feature/domain when the project grows, not by layer
• Use lazy="selectin" or explicit eager loading to avoid N+1 queries
• One session per request via dependency injection

Testing

• Test behavior: inputs, outputs, status codes, side effects
• Use fixtures for shared setup — organize conftest.py by scope
• Mock external dependencies (LLM calls, external HTTP). Never hit real services in tests
• Cover: happy path, validation errors (422), auth failures (401/403), not-found (404)

Workflow

• Orient before coding — read existing code in the area, match patterns and naming conventions
• Small, focused changes — stay within scope, don't refactor unrelated code
• Write tests alongside implementation — new endpoints and services should ship with tests
• Validate after edits — run type checker and linter, run tests if they exist in the area
• If you change database models, create a new Alembic migration revision