wxyc-fastapi

Shared FastAPI service template for WXYC's Python services. Consolidates the duplicated service scaffolding currently forked across library-metadata-lookup (LML), request-o-matic (rom), and semantic-index into a single package, eliminates measurable drift between the three forks, and gives the next FastAPI service a template to inherit instead of fork.

Status: shipping — published to PyPI as wxyc-fastapi (1.x; phases A–E landed, see CHANGELOG.md), consumed by library-metadata-lookup, request-o-matic, and semantic-index. The original implementation plan is at WXYC/wiki/plans/wxyc-fastapi; it traces back to P1 of the 2026-05-10 cross-repo contract audit (WXYC/wiki#51).

Package surface

wxyc_fastapi/
├── observability/
│   ├── sentry.py        # init_sentry(), add_breadcrumb(), capture_exception()
│   ├── telemetry.py     # RequestTelemetry, StepResult, track_step, as_server_timing
│   ├── cache_stats.py   # ContextVar, init_cache_stats, record_*, get_cache_stats
│   └── posthog.py       # get_posthog_client(event_prefix) — capture rate limiter, flush, shutdown
├── testing.py           # CountingPosthog + capture_budget: pin per-operation capture counts in tests
├── http/
│   └── singleton.py     # async_singleton(factory) - getter+closer pair w/ asyncio.Lock
├── healthcheck/
│   ├── liveness.py      # 200 OK with {"status":"healthy"} body, no probes
│   └── readiness.py     # readiness_router(checks: list[Check]) -> APIRouter
└── db/
    └── lazy_pg.py       # LazyPgConnection

Cross-language consolidation (codegen and healthcheck response shape) lives in wxyc-shared instead. See the plan's §2.4 for what lives where and why.

Phasing

Contributing

Implementation and migration tasks are filed as sub-issues of the rollout epic in this repo. See the issues tab and the project board for what's open.