cursorrules

FastAPI + Pydantic v2 + SQLAlchemy 2

Stack

• Python 3.12+
• FastAPI (latest)
• Pydantic v2 (no v1 syntax)
• SQLAlchemy 2.0 (new declarative + async)
• pytest + pytest-asyncio + httpx
• ruff for lint+format
• uv for dependency management

Project structure

src/
  app/
    main.py           # FastAPI app factory
    config.py         # Settings via pydantic-settings
    deps.py           # Dependencies (db session, current user)
    api/
      v1/
        routers/      # Each domain = one router file
        schemas/      # Pydantic request/response models
    models/           # SQLAlchemy ORM models
    services/         # Business logic, no FastAPI imports
    repositories/     # DB access, no business logic
    db/
      base.py
      session.py
tests/
  unit/
  integration/

Conventions

Type hints

• Always type all function signatures.
• Use X | None not Optional[X]. Use list[X] not List[X].
• Pydantic model_config = ConfigDict(from_attributes=True) for ORM mapping.

FastAPI routes

• One router per resource. Mount at /api/v1/<resource>.
• Use Annotated[Type, Depends(...)] for dependencies.
• Response models always declared explicitly: response_model=UserOut.
• 4xx errors via HTTPException. 5xx — let propagate, log in middleware.

Database

• Async only: AsyncSession, select(...), await session.execute(...).
• One unit of work per request via dependency.
• No raw SQL unless ORM can't express it.
• Migrations: alembic, autogenerate, review every diff.

Validation

• Pydantic at API boundary only. Inside services — dataclasses or plain types.
• Custom validators with @field_validator.

Errors

• Custom exception hierarchy: AppError → NotFound, Conflict, Forbidden.
• Exception handler middleware converts to JSON with stable error codes.

Tests

• pytest-asyncio mode = "auto".
• Integration tests use testcontainers-postgres.
• Factories with polyfactory for fixtures.
• Tests named test_<unit>_<scenario>_<expectation>.