Python + FastAPI Best Practices — Quick Reference

Layered Architecture

Router → Service → Repository → Database. Each layer only calls the one below it.

See code-patterns.md for full project structure and layer examples.

Pydantic v2

Separate Create/Update/Response schemas. Use ConfigDict(from_attributes=True) for ORM integration. Use str | None syntax (not Optional[str]).

See code-patterns.md for schema examples.

Async Patterns

async def for I/O routes, plain def for CPU-bound. Use lifespan context manager (not on_event). Use httpx.AsyncClient for external HTTP calls.

See code-patterns.md for async examples.

Soft Delete

Use a SoftDeleteMixin on SQLAlchemy models. Filter where(Model.deleted_at.is_(None)) in all queries.

See code-patterns.md for mixin and repository patterns.

Configuration

Use pydantic-settings for all config. Never hardcode secrets, URLs, or magic numbers.

See code-patterns.md for Settings class pattern.

Pagination

Use a generic PaginatedResponse[T] for all list endpoints. Always return total, page, limit, has_more.

See code-patterns.md for the pattern.

Gotchas

• async def vs def matters for performance. An async def route that calls blocking code (like time.sleep() or sync DB drivers) blocks the entire event loop. Use plain def for CPU-bound work — FastAPI runs it in a threadpool. Use async def only when you await something.

• datetime.utcnow() is deprecated since Python 3.12. Use datetime.now(UTC) instead. The old function returns a naive datetime (no timezone), which causes comparison bugs. The new one returns timezone-aware UTC.

• Mutable default arguments in Pydantic look safe but have a catch. tags: list[str] = [] works in Pydantic (it copies the default). But tags: list[str] = Field(default_factory=list) is explicit and safer for nested models. For simple fields, either works. For complex nested defaults, always use default_factory.

• from_attributes=True replaces orm_mode=True. Pydantic v2 changed the config API. Using the old orm_mode silently does nothing — your ORM objects won't serialize correctly.

• SQLAlchemy Column() is legacy. Use Mapped[type] with mapped_column() for SQLAlchemy 2.0. The old Column(String) still works but loses type checker support and IDE autocomplete.