python-prolisted

# Python Pro (3.10+) Framework-agnostic guidance for modern, type-checked Python services. Assumes the `python` dhpk module's tooling baseline (ruff for lint+format, pyright or mypy for types, `uv run` as the default runner — all overridable). For web-API specifics see the `fastapi` module; for tests see the `pytest` module. ## Typing discipline - **Annotate every public function** (params + return). Prefer `X | None` over `Optional[X]`, `list[str]` over `List[str]` (PEP 585 3.9+, PEP 604 3.10+). - Run the type checker as a gate, not a suggestion. ccas runs **pyright strict**; mypy is the alternative. Don't add `# type: ignore` without a reason comment. - Model data with `@dataclass(slots=True)` or **pydantic** models, not bare dicts. Pydantic at the I/O boundary (request/response, config); dataclasses for internal value objects. - Use `typing.Protocol` for structural interfaces and dependency-injection seams (host-testable code) instead of inheritance. ## Async-await discipline - Never call blocking I/O inside an `async def` coroutine — it stalls the event loop. Wrap unavoidable blocking calls in `await asyncio.to_thread(...)`. - Don't mix sync and async DB sessions. With SQLAlchemy 2.0 async, every query is `await session.execute(...)`; never hold a session across `await` boundaries it doesn't own. - Guard external calls with timeouts (`asyncio.wait_for`, httpx `timeout=`); an unbounded `await` is a latent hang. ccas isolates poison PDFs this way. - U