Python Engineering
Production-grade patterns drawn from (not requiring) exemplar projects—FastAPI, Poetry, HTTPX, Celery, Black—as reference. Apply the patterns with any stack.
This skill is structured per the skill-creator: essentials and navigation in SKILL.md; detailed patterns in references/, loaded only when needed (progressive disclosure).
When to Read Which Reference
| Need | Read |
|---|---|
| Package layout, DI, config, plugins | references/architecture.md |
| Logging, metrics, tracing, health | references/observability.md |
| Test structure, fixtures, CI | references/testing.md |
| Async safety, concurrency, throughput | references/performance-concurrency.md |
| GIL, packaging, I/O, reliability | references/core-practices.md |
Quick Patterns
- Structure: Separate routing, domain, persistence, integration; use dependency injection and typed config (any framework or stdlib).
- Observability: Structured logs with correlation IDs; metrics (Prometheus/StatsD); health/readiness endpoints; distinguish operational vs programmer errors.
- Tests: Pyramid (unit → integration → e2e); fixtures for isolation; parametrize edge cases; parallel CI; avoid hidden network/time.
- Concurrency: Async for I/O; threads for blocking libs; processes for CPU-bound. One long-lived client per dependency; timeouts and backpressure everywhere.
- Reliability: Context managers for cleanup; validate at boundaries; no blocking calls in async paths; idempotent retries and circuit breaking for I/O.
Quick Reference / Examples
| Task | Approach |
|---|---|
| Inject dependencies | Use typed getters or framework DI; see references/architecture.md. |
| Structured logging | Log with extra dict and correlation ID; see references/observability.md. |
| Reuse HTTP client | One long-lived client per app; timeouts on every call. See references/performance-concurrency.md. |
| Resource cleanup | Use context managers; avoid blocking in async. See references/core-practices.md. |
| Isolate tests | Fixtures, parametrize, no hidden network/time. See references/testing.md. |
Context manager (reliable cleanup):
with open(path) as f:
process(f.read())
# or async: async with client: ...
Structured log / typed config:
logger.info("request_handled", extra={"request_id": req_id, "path": path})
# Config: Settings from Pydantic BaseSettings or env, validated at startup.
Workflow
- Designing a new service → Read references/architecture.md, then references/core-practices.md.
- Adding monitoring → Read references/observability.md.
- Writing or refactoring tests → Read references/testing.md.
- Optimizing or introducing async/threads/workers → Read references/performance-concurrency.md.
Keep SKILL.md lean; load reference files only when relevant to the task.