Metadata-Version: 2.4
Name: wxyc-fastapi
Version: 0.2.0
Summary: Shared FastAPI service primitives for WXYC: Sentry init, request telemetry, cache-stats recorder, PostHog wrapper
Author: WXYC Engineering
License: MIT
Project-URL: Homepage, https://github.com/WXYC/wxyc-fastapi
Project-URL: Repository, https://github.com/WXYC/wxyc-fastapi
Project-URL: Issues, https://github.com/WXYC/wxyc-fastapi/issues
Project-URL: Changelog, https://github.com/WXYC/wxyc-fastapi/blob/main/CHANGELOG.md
Project-URL: Plan, https://github.com/WXYC/wiki/blob/main/plans/wxyc-fastapi.md
Keywords: fastapi,sentry,posthog,telemetry,wxyc
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.25
Requires-Dist: sentry-sdk[fastapi]>=2.0
Provides-Extra: posthog
Requires-Dist: posthog>=3.0; extra == "posthog"
Provides-Extra: asyncpg
Requires-Dist: asyncpg>=0.29; extra == "asyncpg"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: posthog>=3.0; extra == "dev"
Dynamic: license-file

# wxyc-fastapi

Shared FastAPI service template for WXYC's Python services. Consolidates the duplicated service scaffolding currently forked across [library-metadata-lookup (LML)](https://github.com/WXYC/library-metadata-lookup), [request-o-matic (rom)](https://github.com/WXYC/request-o-matic), and [semantic-index](https://github.com/WXYC/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:** scaffolding. The implementation plan is at [`WXYC/wiki/plans/wxyc-fastapi`](https://github.com/WXYC/wiki/blob/main/plans/wxyc-fastapi.md). The rollout is tracked in the org-level project board *wxyc-fastapi rollout* and traces back to **P1** of the [2026-05-10 cross-repo contract audit (WXYC/wiki#51)](https://github.com/WXYC/wiki/issues/51).

## Package surface (planned)

```
wxyc_fastapi/
├── observability/
│   ├── sentry.py        # init_sentry(), add_breadcrumb(), capture_exception()
│   ├── telemetry.py     # RequestTelemetry, StepResult, track_step
│   ├── cache_stats.py   # ContextVar, init_cache_stats, record_*, get_cache_stats
│   └── posthog.py       # get_posthog_client(event_prefix), flush_posthog(), shutdown_posthog()
├── 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`](https://github.com/WXYC/wxyc-shared) instead. See the plan's §2.4 for what lives where and why.

## Phasing

| Phase | Module | Version |
|---|---|---|
| A | `observability/*` (sentry, telemetry, cache_stats, posthog) | v0.1.0 |
| B | `healthcheck/*` (Python implementation) | v0.2.0 |
| C | Healthcheck response schemas in `wxyc-shared/api.yaml` (parallel with B) | (no `wxyc-fastapi` version bump) |
| D | `http/singleton` | v0.3.0 |
| E | `db/lazy_pg` | v1.0.0 |

## Contributing

Implementation and migration tasks are filed as sub-issues of the rollout epic in this repo. See the [issues tab](https://github.com/WXYC/wxyc-fastapi/issues) and the project board for what's open.
