python3-web

Python Web

Load python3-core for standing defaults. Load python3-typing for request/response modeling. Load python3-testing for endpoint and auth tests.

Quality Checklist

• Route handlers contain NO business logic — only validation, delegation, response mapping
• No framework objects (Request, Response, ORM models) leak into domain layer
• model_config = {"strict": True} on all request models
• Separate request and response models per endpoint — never reuse ORM models as API schemas
• Auth resolved at edge; domain functions receive typed identity, never raw tokens
• Domain exceptions mapped to HTTP status codes at boundary, not scattered through handlers
• Async handlers use httpx.AsyncClient — never requests (blocks event loop)
• Background tasks hold no references to request-scoped objects

Gotchas

Trap	What to do instead
FastAPI dep ordering assumptions	Dependencies resolve by graph, not definition order — chain explicitly if order matters
Pydantic v1/v2 method mixing	v2: model_dump(), model_dump_json(), model_validate() — never .dict() / .json()
import requests in async handler	requests blocks event loop; use httpx.AsyncClient with async with
Django ORM in async views	Bare Model.objects.get() blocks; use aget() (Django 4.1+) or sync_to_async
allow_origins=["*"]	Enumerate specific origins — * disables credential support, security risk
Single model for request + response + DB	Three separate models: CreateUserRequest, UserResponse, UserDB

Decision Table: Sync vs Async

Scenario	Use	Why
CPU-bound processing	Sync + thread pool	async doesn't help CPU work
Multiple external API calls	Async + httpx.AsyncClient	Concurrent I/O without threads
Simple CRUD with sync ORM	Sync handlers	Async adds complexity with no benefit
WebSocket connections	Async (required)	Inherently long-lived

Layer Separation

HTTP Layer (routes) → validated typed request models
Domain Layer (logic) → typed domain objects
Data Layer (repo/ORM)