Metadata-Version: 2.4
Name: py-cheema-api
Version: 1.0.1
Summary: py-cheema-api - a high-performance ASGI framework with compiled routing, DI, validation, and OpenAPI.
Author: Paresh Panat
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/pareshpanat/py-cheema-api
Project-URL: Repository, https://github.com/pareshpanat/py-cheema-api
Project-URL: Issues, https://github.com/pareshpanat/py-cheema-api/issues
Keywords: asgi,web,framework,api,openapi,performance
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: uvicorn>=0.23; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Provides-Extra: security
Requires-Dist: PyJWT[crypto]>=2.8; extra == "security"
Provides-Extra: pydantic
Requires-Dist: pydantic<3,>=2; extra == "pydantic"
Dynamic: license-file

# py-cheema-api

py-cheema-api is a small, fast ASGI web framework built from scratch (stdlib-only) with a focus on predictable performance.

## Features
- Trie router with `{param}` path params
- `APIRouter` composition with prefixes/tags via `include_router()`
- Compiled route plans (signature inspection happens at route registration, not per request)
- Dependency injection with `Depends()` including nested and yield-based dependencies
- Parameter source markers: `Query`, `Header`, `Cookie`, `Form`, `File`
- Built-in validation with `Model` + `field()` (supports `Annotated`, `Literal`, `Enum`, `datetime`, `UUID`, `Decimal`)
- Optional Pydantic v2 compatibility (request/response models + OpenAPI schema integration when installed)
- Multipart/form-data parsing with `UploadFile`
- Multipart hardening: per-file/part/field limits + upload spooling to disk
- `StreamingResponse`, `FileResponse`, `BackgroundTask`, and static file mounting
- Response primitives: `RedirectResponse`, `NegotiatedResponse`, cache header helpers, and `EventSourceResponse` for SSE
- File hardening: `ETag`/`If-None-Match` + byte range (`206`/`416`) support
- WebSocket route support via `@app.websocket(...)`
- Sub-app mounting via `app.mount("/prefix", sub_app)` and host routing via `app.mount_host("*.example.com", app)`
- WebSocket auth helpers (`websocket_token_auth`, `websocket_jwt_auth`) and OpenAPI WS extension docs (`x-cheema-websockets`)
- Security primitives: `api_key_auth()`, `bearer_auth()`, `jwt_auth()`, OAuth2 password/auth-code/client-credentials helpers with OpenAPI security schemas
- Session + CSRF protection primitives (`SessionMiddleware`, `CSRFMiddleware`, CSRF helpers)
- Testing utilities: sync `TestClient` and async `AsyncTestClient` with WebSocket test sessions
- OpenAPI at `/openapi.json`
- Swagger UI at `/docs` and ReDoc at `/redoc`
- Lifespan startup/shutdown handlers
- Lifespan state resources with cleanup guarantees (`app.add_state_resource(...)`)
- App-state dependency helpers (`app.state_dependency(...)`, `app_state_dependency(...)`, `get_app_state(...)`)
- Custom exception handlers with `@app.exception_handler(...)`
- Reliability defaults: request timeout, max body size, max concurrency
- Runtime settings model (`CheemaSettings`) + `Cheema.from_env()` for env-driven deploy config
- Graceful shutdown request draining (`shutdown_drain_timeout`)
- Background job primitives: `InMemoryJobQueue` with retries, delay/schedule, and idempotency keys
- Queue adapters: `CeleryQueueAdapter`, `RQQueueAdapter`, `RedisQueueAdapter`
- CI release gates: Python matrix tests/lint + package build and `twine check`, with trusted publishing workflow
- Benchmark suite + perf regression gates in CI (`benchmarks/bench_runtime.py`)
- `HTTPException` (alias for `HTTPError`) and a `py_cheema_api` import alias for FastAPI-style migrations
- `default=` on `Query`/`Header`/`Cookie`/`Form`/`File`/`Host`/`Body` for FastAPI-style optional params (e.g. `Query(default=10)`)
- Native `Model`/`field()` validated data supports both `item["field"]` and `item.field` access
- `TestClient`/`AsyncTestClient` accept `json=` and query strings embedded in the path, matching FastAPI's `TestClient`
- Pluggable `MemoryCache` primitive, shareable between `ResponseCacheMiddleware` and your own route handlers
- Built-in ops status endpoint via `app.add_status_route()` (route table, middleware stack, uptime, inflight requests, optional auth gate and custom `extra` payload)
- `response_class=` on route decorators (`@app.get(..., response_class=HTMLResponse)`), matching FastAPI's pattern for wrapping plain return values
- SPA fallback routing on `mount_static(..., spa_fallback=True)`, serving `index.html` for extensionless client-side routes while still 404ing missing real assets

## What's New

### v1.0.1
FastAPI migration parity fixes — see `MIGRATION.md` for the full guide:
- `HTTPException` alias for `HTTPError`
- `default=` support on all parameter markers (`Query`, `Header`, `Cookie`, `Form`, `File`, `Host`, `Body`)
- Pydantic `BaseModel` responses now serialize cleanly instead of being wrapped in an envelope
- Native `Model` validated data supports attribute access (`item.name`) alongside existing dict access (`item["name"]`)
- `TestClient`/`AsyncTestClient` accept `json=` and parse query strings embedded directly in the path
- `py_cheema_api` import alias, matching the PyPI distribution name

New primitives:
- `MemoryCache`: a pluggable in-process cache with per-entry TTL, usable directly by app code and shareable with `ResponseCacheMiddleware(cache=...)` so both can read/write the same store
- `app.add_status_route()`: a built-in ops status endpoint reporting the route table, middleware stack, app title/version, uptime, and inflight-request count, with an optional `auth` gate and an `extra` hook for custom stats (e.g. queue depth, connection counts)
- `response_class=` on `route()`/`get()`/`post()`/etc. (both `Cheema` and `APIRouter`): wraps a plain return value in the given `Response` subclass, e.g. `@app.get("/page", response_class=HTMLResponse)` returning a bare string. An explicit `Response` return still takes precedence.
- `mount_static(prefix, directory, spa_fallback=True, index_file="index.html")`: serves the mount's `index.html` for any unmatched path with no file extension (client-side routes), so a React/Vue/Angular build's own router can take over on refresh/direct navigation, while a genuinely missing asset (has a file extension, e.g. `/assets/app.js`) still 404s correctly. Off by default; existing `mount_static()` calls are unaffected.

### v1.0.0
Initial stable release under the `py-cheema-api` name (renamed from TurboAPI/`py-turbo-api`).

## Stability
- Compatibility policy: `API_COMPATIBILITY.md`
- Current status: v1.0.1

## Install

### From PyPI
```bash
pip install py-cheema-api
```

### Optional: Pydantic v2 compatibility
```bash
pip install "py-cheema-api[pydantic]"
```

PyPI: https://pypi.org/project/py-cheema-api/

## Run example
```bash
uvicorn app:app --reload
```

Open:
- http://127.0.0.1:8000/docs
- http://127.0.0.1:8000/openapi.json

## Documentation Tracks
- Docs home (GitHub Pages entry): `docs/index.md`
- Complete API reference: `docs/api-reference.md`
- Tutorial: `docs/tutorial.md`
- Advanced: `docs/advanced.md`
- Deployment: `docs/deployment.md`
- Security recipes: `docs/security-recipes.md`
- Why py-cheema-api + benchmark method: `docs/why-py-cheema-api.md`
- Migrating from FastAPI: `MIGRATION.md`
- Benchmark methodology: `BENCHMARKS.md`

## Benchmarks
```bash
python benchmarks/bench_runtime.py --baseline benchmarks/baseline.json --tolerance 1.20 --gate
```

## License
Apache-2.0 (see LICENSE).
