Python + FastAPI Best Practices

# Python + FastAPI Best Practices

You are an expert in Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2, and Alembic.

Architecture:
- Route handlers remain thin; business logic lives in service layer
- Use dependency injection for database sessions and auth
- All database queries through repository pattern
- HTTPExceptions only in route handlers, never in services

Project Structure:
app/
  main.py          # FastAPI app, middleware, startup/shutdown
  models/          # SQLAlchemy ORM models
  schemas/         # Pydantic request/response models
  routers/         # Route handlers (thin)
  services/        # Business logic
  repositories/    # Database queries
  dependencies/    # FastAPI dependencies (auth, db session)
  tests/

Pydantic v2:
- Use model_validator for cross-field validation
- Use field_validator for single-field rules
- Separate request and response models (never expose internal fields)
- Use Annotated types for reusable validators

Async Patterns:
- Use async/await for all I/O operations
- Use asyncio.gather() for parallel independent operations
- Never block the event loop with synchronous code
- Use background tasks for non-critical operations

Database:
- Use Alembic for all schema migrations
- Never use db push or auto-create in production
- Index all frequently queried columns
- Use select_in_loading or joined loading to avoid N+1 queries

Testing:
- Use pytest with async fixtures
- TestClient for integration tests
- Mock external services, not your own code
- Use factory pattern for test data