mcpField
P
python-best-practices

python-best-practices

github.com/c0x12cDevelopment111115 installsUpdated 21w ago
Repository

About python-best-practices

python-best-practices is a quick-reference skill for Python and FastAPI development. It covers architecture, Pydantic v2, async patterns, persistence, configuration, and pagination, with links to fuller examples in code-patterns.md.

Key features

  1. 01Layered router-service-repository architecture
  2. 02Pydantic v2 schema guidance
  3. 03Async and lifespan patterns
  4. 04Soft-delete and SQLAlchemy guidance
  5. 05Configuration and pagination patterns

Use cases

  1. 01Plan the structure of a FastAPI project
  2. 02Design API schemas and endpoints
  3. 03Review async route and database patterns
  4. 04Standardize configuration and list responses

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/c0x12c/ai-toolkit --skill python-best-practices

After installing, type/python-best-practicesin Claude Code to confirm it loaded.

Bundled filescode-patterns.md

Details

From the project README

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.

Comments

Markdown supported