Cursor Rules for Python + FastAPI

---
description: Python + FastAPI conventions for this codebase
globs: ["**/*.py"]
alwaysApply: false
---

- Python 3.12+ idioms: type hints on every function signature (parameters and return), | unions over Optional, pathlib over os.path, f-strings over format().
- FastAPI routes: async def by default; use sync def ONLY for CPU-bound work or sync-only libraries (FastAPI threadpools it). Never call blocking I/O (requests, time.sleep, sync DB drivers) inside an async route. That stalls the event loop.
- Pydantic v2 everywhere at the boundaries: request bodies, response_model on every route, settings via pydantic-settings. No raw dicts crossing API boundaries. Use model_validate / model_dump, never the v1 .dict()/.parse_obj() API.
- Dependencies over globals: DB sessions, auth context, and config arrive via Depends(), never module-level singletons imported into routes.
- Errors: raise HTTPException with explicit status codes in routes; domain code raises domain exceptions that handlers translate. Never return {"error": ...} with a 200.
- Every route declares response_model and status_code explicitly: implicit 200-with-whatever-serializes is how schemas rot.
- Tests: pytest with httpx.AsyncClient against the app; fixtures in conftest.py; no test hits a real external service.
- Match the structure of the nearest existing module (routers/, services/, models/ split). Do not introduce a new architecture pattern into one file.
- Never add a dependency, change pyproject.toml, or create new top-level directories without being asked.