Metadata-Version: 2.3
Name: svc-infra
Version: 0.1.635
Summary: Infrastructure for building and deploying prod-ready services
License: MIT
Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
Author: Ali Khatami
Author-email: aliikhatami94@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Provides-Extra: duckdb
Provides-Extra: metrics
Provides-Extra: mssql
Provides-Extra: mysql
Provides-Extra: pg
Provides-Extra: pg2
Provides-Extra: redshift
Provides-Extra: snowflake
Provides-Extra: sqlite
Requires-Dist: adyen (>=13.4.0,<14.0.0)
Requires-Dist: ai-infra (>=0.1.63,<0.2.0)
Requires-Dist: aiosqlite (>=0.20.0,<0.21.0) ; extra == "sqlite"
Requires-Dist: alembic (>=1.13.2,<2.0.0)
Requires-Dist: asyncpg (>=0.30.0,<0.31.0) ; extra == "pg"
Requires-Dist: authlib (>=1.6.2,<2.0.0)
Requires-Dist: cashews[redis] (>=7.4.1,<8.0.0)
Requires-Dist: duckdb (>=1.1.3,<2.0.0) ; extra == "duckdb"
Requires-Dist: email-validator (>=2.2.0,<3.0.0)
Requires-Dist: fastapi (>=0.116.1,<0.117.0)
Requires-Dist: fastapi-users-db-sqlalchemy (>=7.0.0,<8.0.0)
Requires-Dist: fastapi-users[oauth] (>=14.0.1,<15.0.0)
Requires-Dist: greenlet (>=3,<4)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: httpx-oauth (>=0.16.1,<0.17.0)
Requires-Dist: itsdangerous (>=2.2.0,<3.0.0)
Requires-Dist: mcp (>=1.13.0,<2.0.0)
Requires-Dist: motor (>=3.7.1,<4.0.0)
Requires-Dist: mysqlclient (>=2.2.4,<3.0.0) ; extra == "mysql"
Requires-Dist: opentelemetry-exporter-otlp (>=1.36.0,<2.0.0)
Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-httpx (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-requests (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-instrumentation-sqlalchemy (>=0.57b0,<0.58)
Requires-Dist: opentelemetry-propagator-b3 (>=1.36.0,<2.0.0)
Requires-Dist: opentelemetry-sdk (>=1.36.0,<2.0.0)
Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
Requires-Dist: pre-commit (>=4.3.0,<5.0.0)
Requires-Dist: prometheus-client (>=0.22.1,<0.23.0) ; extra == "metrics"
Requires-Dist: psycopg2-binary (>=2.9.10,<3.0.0) ; extra == "pg2"
Requires-Dist: psycopg[binary] (>=3.2.10,<4.0.0) ; extra == "pg"
Requires-Dist: pydantic-settings (>=2.10.1,<3.0.0)
Requires-Dist: pymysql (>=1.1.1,<2.0.0) ; extra == "mysql"
Requires-Dist: pyodbc (>=5.1.0,<6.0.0) ; extra == "mssql"
Requires-Dist: pyotp (>=2.9.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
Requires-Dist: redis (>=6.4.0,<7.0.0)
Requires-Dist: redshift-connector (>=2.0.918,<3.0.0) ; extra == "redshift"
Requires-Dist: snowflake-connector-python (>=3.12.0,<4.0.0) ; extra == "snowflake"
Requires-Dist: sqlalchemy[asyncio] (>=2.0.43,<3.0.0)
Requires-Dist: stripe (>=13.0.1,<14.0.0)
Requires-Dist: typer (>=0.16.1,<0.17.0)
Project-URL: Documentation, https://github.com/your-org/svc-infra#readme
Project-URL: Homepage, https://github.com/your-org/svc-infra
Project-URL: Issues, https://github.com/your-org/svc-infra/issues
Project-URL: Repository, https://github.com/your-org/svc-infra
Description-Content-Type: text/markdown

# svc-infra

[![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
[![Docs](https://img.shields.io/badge/docs-reference-blue)](.)

svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.

## Helper index

| Area | What it covers | Guide |
| --- | --- | --- |
| Getting Started | Overview and entry points | [This page](getting-started.md) |
| Environment | Feature switches and env vars | [Environment](environment.md) |
| API | FastAPI bootstrap, middleware, docs wiring | [API guide](api.md) |
| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](auth.md) |
| Security | Password policy, lockout, signed cookies, headers | [Security](security.md) |
| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](database.md) |
| Tenancy | Multi-tenant boundaries and helpers | [Tenancy](tenancy.md) |
| Idempotency | Idempotent endpoints and middleware | [Idempotency](idempotency.md) |
| Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](rate-limiting.md) |
| Cache | cashews decorators, namespace management, TTL helpers | [Cache](cache.md) |
| Jobs | JobQueue, scheduler, CLI worker | [Jobs](jobs.md) |
| Observability | Prometheus, Grafana, OpenTelemetry | [Observability](observability.md) |
| Ops | Probes, breakers, SLOs & dashboards | [Ops](ops.md) |
| Webhooks | Subscription store, signing, retry worker | [Webhooks](webhooks.md) |
| CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](cli.md) |
| Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](docs-and-sdks.md) |
| Acceptance | Acceptance harness and flows | [Acceptance](acceptance.md), [Matrix](acceptance-matrix.md) |
| Contributing | Dev setup and quality gates | [Contributing](contributing.md) |
| Repo Review | Checklist for releasing/PRs | [Repo review](repo-review.md) |
| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](data-lifecycle.md) |

## Minimal FastAPI bootstrap

```python
from fastapi import Depends
from svc_infra.api.fastapi.ease import easy_service_app
from svc_infra.api.fastapi.db.sql.add import add_sql_db
from svc_infra.cache import init_cache
from svc_infra.jobs.easy import easy_jobs
from svc_infra.webhooks.fastapi import require_signature

app = easy_service_app(name="Billing", release="1.2.3")
add_sql_db(app)              # reads SQL_URL / DB_* envs
init_cache()                 # honors CACHE_PREFIX / CACHE_VERSION
queue, scheduler = easy_jobs()  # switches via JOBS_DRIVER / REDIS_URL

@app.post("/webhooks/billing")
async def handle_webhook(payload = Depends(require_signature(lambda: ["current", "next"]))):
    queue.enqueue("process-billing-webhook", payload)
    return {"status": "queued"}
```

## Environment switches

- **API** – toggle logging/observability and docs exposure with `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and `CORS_ALLOW_ORIGINS`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
- **Auth** – configure JWT secrets, SMTP, cookies, and policy using the `AUTH_…` settings family (e.g., `AUTH_JWT__SECRET`, `AUTH_SMTP_HOST`, `AUTH_SESSION_COOKIE_SECURE`). 【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
- **Database** – set connection URLs or components via `SQL_URL`/`SQL_URL_FILE`, `DB_DIALECT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, plus Mongo knobs like `MONGO_URL`, `MONGO_DB`, and `MONGO_URL_FILE`. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】【F:src/svc_infra/db/sql/utils.py†L85-L206】【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】
- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:src/svc_infra/docs/jobs.md†L11-L48】
- **Cache** – namespace keys and lifetimes through `CACHE_PREFIX`, `CACHE_VERSION`, and TTL overrides `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG`. 【F:src/svc_infra/cache/README.md†L20-L173】【F:src/svc_infra/cache/ttl.py†L26-L55】
- **Observability** – turn metrics on/off or adjust scrape paths with `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and Prometheus/Grafana flags like `SVC_INFRA_DISABLE_PROMETHEUS`, `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:src/svc_infra/docs/webhooks.md†L32-L53】
- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:src/svc_infra/docs/security.md†L24-L70】

