Master Python Architecture & Decision-Making

Python Patterns covers decision-level Python architecture guidance across eleven areas rather than syntax basics. Framework Selection uses a decision tree and comparison principles to choose between frameworks based on project needs. Async vs Sync Decision states a golden rule for when async is worth its complexity, plus async library selection guidance. Type Hints Strategy covers when to type and common type patterns:

### 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: ...

plus Pydantic for validation - used for API request/response models, configuration, data validation, and serialization, valued for runtime validation, auto-generated JSON schema, and native FastAPI integration. Project Structure Principles gives structure templates scaled by project size, from a small script (main.py, utils.py) to a medium API's app/ layout, plus FastAPI-specific structure principles. Django Principles covers Django 5.0+ async support and Django best practices. FastAPI Principles covers when to use async def versus def in route handlers, dependency injection, and Pydantic v2 integration for request validation and response serialization, where the return type annotation becomes the response schema. Background Tasks gives a selection guide for when to use each background-execution mechanism. Error Handling Principles covers exception strategy and error-response philosophy. Testing Principles covers testing strategy, async testing via pytest-asyncio, and fixture strategy. A Decision Checklist and a list of anti-patterns to avoid versus recommended practices close out the guide.

Use this skill when making Python architecture decisions - framework selection, async versus sync design, type hint strategy, project structure, Django or FastAPI-specific choices, background task design, error handling strategy, or testing strategy. The golden rule for the async decision is stated directly: I/O-bound work goes async, CPU-bound work stays synchronous plus multiprocessing, and sync libraries should never be called from async code.

Given a Python architecture decision, the skill outputs the relevant decision framework - a decision tree, a selection guide, or a golden rule - matched to the specific choice being made (framework, async model, type strategy, project layout, background task mechanism, error handling approach, or testing approach), plus a closing decision checklist and named anti-patterns to avoid with their recommended alternatives.

Covers FastAPI (async def vs def, dependency injection, Pydantic v2 request/response integration), Django (5.0+ async support, best practices), Pydantic (validation, JSON schema generation), and pytest-asyncio for async test execution. Async library selection maps each need to a named library: httpx for HTTP clients, asyncpg for PostgreSQL, aioredis or redis-py's async mode for Redis, aiofiles for file I/O, and SQLAlchemy 2.0 async or Tortoise for the ORM layer.

Python developers and architects making structural decisions - which framework, whether to go async, how to type-hint, how to structure a project, how to handle errors and background tasks - who want decision frameworks and golden rules rather than a syntax reference.