python-patterns

# Python Patterns > Python development principles and decision-making for 2025. > **Learn to THINK, not memorize patterns.** ## When to Use Use this skill when making Python architecture decisions, choosing frameworks, designing async patterns, or structuring Python projects. --- ## ⚠️ How to Use This Skill This skill teaches **decision-making principles**, not fixed code to copy. - ASK user for framework preference when unclear - Choose async vs sync based on CONTEXT - Don't default to same framework every time --- ## 1. Framework Selection (2025) ### Decision Tree ``` What are you building? │ ├── API-first / Microservices │ └── FastAPI (async, modern, fast) │ ├── Full-stack web / CMS / Admin │ └── Django (batteries-included) │ ├── Simple / Script / Learning │ └── Flask (minimal, flexible) │ ├── AI/ML API serving │ └── FastAPI (Pydantic, async, uvicorn) │ └── Background workers └── Celery + any framework ``` ### Comparison Principles | Factor | FastAPI | Django | Flask | |--------|---------|--------|-------| | **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning | | **Async** | Native | Django 5.0+ | Via extensions | | **Admin** | Manual | Built-in | Via extensions | | **ORM** | Choose your own | Django ORM | Choose your own | | **Learning curve** | Low | Medium | Low | ### Selection Questions to Ask: 1. Is this API-only or full-stack? 2. Need admin interface? 3. Team familiar with async? 4. Existing infrastructure? --- ## 2. Async vs Sync Decision ### When to Use Async ``` async def is better when: ├── I/O-bound operations (database, HTTP, file) ├── Many concurrent connections ├── Real-time features ├── Microservices communication └── FastAPI/Starlette/Django ASGI def (sync) is better when: ├── CPU-bound operations ├── Simple scripts ├── Legacy codebase ├── Team unfamiliar with async └── Blocking libraries (no async version) ``` ### The Golden Rule ``` I/O-bound → async (waiting for external) CPU-bound → sync + multiprocessing (computing) Don't: ├── Mix sync and async carelessly ├── Use sync libraries in async code └── Force async for CPU work ``` ### Async Library Selection | Need | Async Library | |------|---------------| | HTTP client | httpx | | PostgreSQL | asyncpg | | Redis | aioredis / redis-py async | | File I/O | aiofiles | | Database ORM | SQLAlchemy 2.0 async, Tortoise | --- ## 3. Type Hints Strategy ### When to Type ``` Always type: ├── Function parameters ├── Return types ├── Class attributes ├── Public APIs Can skip: ├── Local variables (let inference work) ├── One-off scripts ├── Tests (usually) ``` ### Common Type Patterns ```python # These are patterns, understand them: # Optional → might be None from typing import Optional def find_user(id: int) -> Optional[User]: ... # Union → one of multiple types def process(data: str | dict) -> None: ... # Generic collections def get_items() -> list[Item]: ... def get_mapping() -> dict[str, int]: ... # Callable from typing import Callable def apply(fn: Callable[[int], str]) -> str: ... ``` ### Pydantic for Validation ``` When to use Pydantic: ├── API request/response models ├── Configuration/settings ├── Data validation ├── Serialization Benefits: ├── Runtime validation ├── Auto-generated JSON schema ├── Works with FastAPI natively └── Clear error messages ``` --- ## 4. Project Structure Principles ### Structure Selection ``` Small project / Script: ├── main.py ├── utils.py └── requirements.txt Medium API: ├── app/ │ ├── __init__.py │ ├── main.py │ ├── models/ │ ├── routes/ │ ├── services/ │ └── schemas/ ├── tests/ └── pyproject.toml Large application: ├── src/ │ └── myapp/ │ ├── core/ │ ├── api/ │ ├── services/ │ ├── models/ │ └── ... ├── tests/ └── pyproject.toml ``` ### FastAPI Structure Principles ``` Organize by feature or layer: By layer: ├── routes/ (API endpoints) ├── services/ (business logic) ├── models/ (database models) ├── schemas/ (Pydantic models) └── dependencies/ (shared deps) By feature: ├── users/ │ ├── routes.py │ ├── service.py │ └── schemas.py └── products/ └── ... ``` --- ## 5. Django Principles (2025) ### Django Async (Django 5.0+) ``` Django supports async: ├── Async views ├── Async middleware ├── Async ORM (limited) └── ASGI deployment When to use async in Django: ├── External API calls ├── WebSocket (Channels) ├── High-concurrency views └── Background task triggering ``` ### Django Best Practices ``` Model design: ├── Fat models, thin views ├── Use managers for common queries ├── Abstract base classes for shared fields Views: ├── Class-based for complex CRUD ├── Function-based for simple endpoints ├── Use viewsets with DRF Queries: ├── select_related() for FKs ├── prefetch_related() for M2M ├── Avoid N+1 queries └── Use .only() for specific fields ``` --- ## 6. FastAPI Principles ### async def vs def in FastAPI ``` Use async def when: ├── Using async database drivers ├── Making async HTTP calls ├── I/O-bound operations └── Want to handle concurrency Use def when: ├── Blocking operations ├── Sync database drivers ├── CPU-bound work └── FastAPI runs in threadpool automatically ``` ### Dependency Injection ``` Use dependencies for: ├── Database sessions ├── Current user / Auth ├── Configuration ├── Shared resources Benefits: ├── Testability (mock dependencies) ├── Clean separation ├── Automatic cleanup (yield) ``` ### Pydantic v2 Integration ```python # FastAPI + Pydantic are tightly integrated: # Request validation @app.post("/users") async def create(user: UserCreate) -> UserResponse: # user is already validated ... # Response serialization # Return type becomes response schema ``` --- ## 7. Background Tasks ### Selection Guide | Solution | Best For | |----------|----------| | **BackgroundTasks** | Simple, in-process tasks | | **Celery** | Distributed, complex workflows | | **ARQ** | Async, Redis-based | | **RQ** | Simple Redis queue | | **Dramatiq** | Actor-based, simpler than Celery | ### When to Use Each ``` FastAPI BackgroundTasks: ├── Quick operations ├── No persistence needed ├── Fire-and-forget └── Same process Celery/ARQ: ├── Long-running tasks ├── Need retry logic ├── Distributed workers ├── Persistent queue └── Complex workflows ``` --- ## 8. Error Handling Principles ### Exception Strategy ``` In FastAPI: ├── Create custom exception classes ├── Register exception handlers ├── Return consistent error format └── Log without exposing internals Pattern: ├── Raise domain exceptions in services ├── Catch and transform in handlers └── Client gets clean error response ``` ### Error Response Philosophy ``` Include: ├── Error code (programmatic) ├── Message (human readable) ├── Details (field-level when applicable) └── NOT stack traces (security) ``` --- ## 9. Testing Principles ### Testing Strategy | Type | Purpose | Tools | |------|---------|-------| | **Unit** | Business logic | pytest | | **Integration** | API endpoints | pytest + httpx/TestClient | | **E2E** | Full workflows | pytest + DB | ### Async Testing ```python # Use pytest-asyncio for async tests import pytest from httpx import AsyncClient @pytest.mark.asyncio async def test_endpoint(): async with AsyncClient(app=app, base_url="http://test") as client: response = await client.get("/users") assert response.status_code == 200 ``` ### Fixtures Strategy ``` Common fixtures: ├── db_session → Database connection ├── client → Test client ├── authenticated_user → User with token └── sample_data → Test data setup ``` --- ## 10. Decision Checklist Before implementing: - [ ] **Asked user about framework preference?** - [ ] **Chosen framework for THIS context?** (not just default) - [ ] **Decided async vs sync?** - [ ] **Planned type hint strategy?** - [ ] **Defined project structure?** - [ ] **Planned error handling?** - [ ] **Considered background tasks?** --- ## 11. Anti-Patterns to Avoid ### ❌ DON'T: - Default to Django for simple APIs (FastAPI may be better) - Use sync libraries in async code - Skip type hints for public APIs - Put business logic in routes/views - Ignore N+1 queries - Mix async and sync carelessly ### ✅ DO: - Choose framework based on context - Ask about async requirements - Use Pydantic for validation - Separate concerns (routes → services → repos) - Test critical paths --- > **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best. ## Limitations - Use this skill only when the task clearly matches the scope described above. - Do not treat the output as a substitute for environment-specific validation, testing, or expert review. - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.