ia-python-services

# Python Services & CLI ## Working rules - Validate external inputs and responses at boundaries; preserve exception causes. - **Keep missing results distinct from empty results.** When an empty collection means success, require the response field instead of defaulting it to empty; an all-default model can validate `{}` as success. Test missing, misspelled, explicitly empty, and populated payloads through the real validation boundary. - Keep simple sequential work synchronous. Bound concurrent work, preserve cancellation, and keep task references. - Give network calls timeouts; retry only failures and operations whose semantics permit it. - Enforce job idempotency with atomic writes and database constraints. - Preserve published API behavior and shared migration history. - Match telemetry to an operational question and verify its output. ## Discipline - Simplicity first: every change as simple as possible, impact minimal code - Only touch what's necessary; avoid introducing unrelated changes - No hacky workarounds: if a fix feels wrong, step back and implement the clean solution - Before adding a new abstraction, verify it appears in 3+ places. If not, inline it. - Verify: see Verify section below; pass all checks with zero warnings before declaring done ## Verify - `uv run pytest` passes with zero failures - `uv run ruff check .` passes with zero warnings - `uv run ty check .` passes with zero errors - Coverage target: 80%+ (`uv run pytest --cov`; add `--cov-report=html` for a browsable report) ## Task-specific references Read the relevant reference before implementing or reviewing the matching behavior: - For packaging, environment configuration, CLI setup, or pytest behavior: [tooling-and-tests.md](./references/tooling-and-tests.md). - For asyncio, background jobs, retries, pooling, timeouts, or health checks: [concurrency-and-resilience.md](./references/concurrency-and-resilience.md). - For APIs, validation, errors, migrations, logging, metrics, or traces: [service-boundaries.md](./references/service-boundaries.md). Existing specialized references, when the corresponding topic applies: - [cli-tools.md](./references/cli-tools.md). - [fastapi.md](./references/fastapi.md).