python-best-practices

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.