dhpk-python-pro

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.
• Use asyncio.TaskGroup (3.11+) or asyncio.gather for fan-out; propagate cancellation rather than swallowing CancelledError.

Errors & logging

• No print() in library/app code — use the logging module (structured JSON in ccas). print is for CLIs/scripts only. The post-edit hook flags stray prints.
• Define a project exception hierarchy (class AppError(Exception) → specific subclasses). Raise specific, catch specific. Never except Exception: pass — log with context and re-raise or convert. (See the silent-failure-hunter agent.)
• Preserve the chain: raise NewError(...) from err. Don't discard the original traceback.
• Validate inputs at the boundary and fail fast with a descriptive message; don't let a None or malformed value propagate three layers deep.