svc-infra 0.1.706__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/api/fastapi/setup.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 import os
 from collections import defaultdict
-from typing import Iterable, Sequence
+from collections.abc import Iterable, Sequence
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -85,9 +85,7 @@ def _setup_cors(app: FastAPI, public_cors_origins: list[str] | str | None = None
     if isinstance(public_cors_origins, list):
         param_origins = [o.strip() for o in public_cors_origins if o and o.strip()]
     elif isinstance(public_cors_origins, str):
-        param_origins = [
-            o.strip() for o in public_cors_origins.split(",") if o and o.strip()
-        ]
+        param_origins = [o.strip() for o in public_cors_origins.split(",") if o and o.strip()]
     else:
         param_origins = []
 
@@ -106,7 +104,7 @@ def _setup_cors(app: FastAPI, public_cors_origins: list[str] | str | None = None
     if not origins:
         return
 
-    cors_kwargs = dict(allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
+    cors_kwargs = {"allow_credentials": True, "allow_methods": ["*"], "allow_headers": ["*"]}
 
     # Check for "*" (allow all) first
     if "*" in origins:
@@ -176,9 +174,7 @@ def _dump_or_none(model):
 def _build_child_app(
     service: ServiceInfo, spec: APIVersionSpec, skip_paths: list[str] | None = None
 ) -> FastAPI:
-    title = (
-        f"{service.name} • {spec.tag}" if getattr(spec, "tag", None) else service.name
-    )
+    title = f"{service.name} • {spec.tag}" if getattr(spec, "tag", None) else service.name
     child = FastAPI(
         title=title,
         version=service.release,
@@ -192,9 +188,7 @@ def _build_child_app(
     _setup_middlewares(child, skip_paths=skip_paths)
 
     # ---- OpenAPI pipeline (DRY!) ----
-    include_api_key = (
-        bool(spec.include_api_key) if spec.include_api_key is not None else False
-    )
+    include_api_key = bool(spec.include_api_key) if spec.include_api_key is not None else False
     tag_str = str(spec.tag).strip("/")
     mount_path = f"/{tag_str}"
     server_url = (
@@ -272,9 +266,7 @@ def _build_parent_app(
     )
     # app-provided root routers
     for pkg in _coerce_list(root_routers):
-        register_all_routers(
-            parent, base_package=pkg, prefix="", environment=CURRENT_ENVIRONMENT
-        )
+        register_all_routers(parent, base_package=pkg, prefix="", environment=CURRENT_ENVIRONMENT)
 
     return parent
 
@@ -294,8 +286,8 @@ class RouteLoggerMiddleware:
         path = scope.get("path", "")
         method = scope.get("method", "")
 
-        # Skip specified paths
-        if any(skip in path for skip in self.skip_paths):
+        # Skip specified paths using prefix matching
+        if any(path.startswith(skip) for skip in self.skip_paths):
             await self.app(scope, receive, send)
             return
 
@@ -303,15 +295,11 @@ class RouteLoggerMiddleware:
         async def send_wrapper(message):
             if message["type"] == "http.response.start":
                 route = scope.get("route")
-                route_path = getattr(route, "path_format", None) or getattr(
-                    route, "path", None
-                )
+                route_path = getattr(route, "path_format", None) or getattr(route, "path", None)
                 if route_path:
                     root_path = scope.get("root_path", "") or ""
                     headers = list(message.get("headers", []))
-                    headers.append(
-                        (b"x-handled-by", f"{method} {root_path}{route_path}".encode())
-                    )
+                    headers.append((b"x-handled-by", f"{method} {root_path}{route_path}".encode()))
                     message = {**message, "headers": headers}
             await send(message)
 
@@ -367,9 +355,7 @@ def setup_service_api(
         cards.append(
             CardSpec(
                 tag="",
-                docs=DocTargets(
-                    swagger="/docs", redoc="/redoc", openapi_json="/openapi.json"
-                ),
+                docs=DocTargets(swagger="/docs", redoc="/redoc", openapi_json="/openapi.json"),
             )
         )
 
@@ -393,15 +379,11 @@ def setup_service_api(
                 cards.append(
                     CardSpec(
                         tag=scope.strip("/"),
-                        docs=DocTargets(
-                            swagger=swagger, redoc=redoc, openapi_json=openapi_json
-                        ),
+                        docs=DocTargets(swagger=swagger, redoc=redoc, openapi_json=openapi_json),
                     )
                 )
 
-        html = render_index_html(
-            service_name=service.name, release=service.release, cards=cards
-        )
+        html = render_index_html(service_name=service.name, release=service.release, cards=cards)
         return HTMLResponse(html)
 
     return parent

svc_infra/api/fastapi/tenancy/add.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Optional
+from collections.abc import Callable
+from typing import Any
 
 from fastapi import FastAPI
 
 from .context import set_tenant_resolver
 
 
-def add_tenancy(app: FastAPI, *, resolver: Optional[Callable[..., Any]] = None) -> None:
+def add_tenancy(app: FastAPI, *, resolver: Callable[..., Any] | None = None) -> None:
     """Wire tenancy resolver for the application.
 
     Provide a resolver(request, identity, header) -> Optional[str] to override

svc_infra/api/fastapi/tenancy/context.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Annotated, Any, Callable, Optional
+from collections.abc import Callable
+from typing import Annotated, Any
 
 from fastapi import Depends, HTTPException, Request
 
@@ -10,11 +11,11 @@ except Exception:  # pragma: no cover - fallback for minimal builds
     OptionalIdentity = None  # type: ignore[misc,assignment]
 
 
-_tenant_resolver: Optional[Callable[..., Any]] = None
+_tenant_resolver: Callable[..., Any] | None = None
 
 
 def set_tenant_resolver(
-    fn: Optional[Callable[..., Any]],
+    fn: Callable[..., Any] | None,
 ) -> None:
     """Set or clear a global override hook for tenant resolution.
 
@@ -33,9 +34,9 @@ async def _maybe_await(x):
 
 async def resolve_tenant_id(
     request: Request,
-    tenant_header: Optional[str] = None,
+    tenant_header: str | None = None,
     identity: Any = Depends(OptionalIdentity) if OptionalIdentity else None,  # type: ignore[arg-type]
-) -> Optional[str]:
+) -> str | None:
     """Resolve tenant id from override, identity, header, or request.state.
 
     Order:
@@ -91,7 +92,7 @@ async def resolve_tenant_id(
 
 
 async def require_tenant_id(
-    tenant_id: Optional[str] = Depends(resolve_tenant_id),
+    tenant_id: str | None = Depends(resolve_tenant_id),
 ) -> str:
     if not tenant_id:
         raise HTTPException(status_code=400, detail="tenant_context_missing")
@@ -100,7 +101,7 @@ async def require_tenant_id(
 
 # DX aliases
 TenantId = Annotated[str, Depends(require_tenant_id)]
-OptionalTenantId = Annotated[Optional[str], Depends(resolve_tenant_id)]
+OptionalTenantId = Annotated[str | None, Depends(resolve_tenant_id)]
 
 
 __all__ = [

svc_infra/api/fastapi/versioned.py

@@ -9,7 +9,8 @@ See: svc-infra/docs/versioned-integrations.md
 
 from __future__ import annotations
 
-from typing import Any, Callable, TypeVar
+from collections.abc import Callable
+from typing import Any, TypeVar
 from unittest.mock import patch
 
 from fastapi import APIRouter, FastAPI
@@ -78,7 +79,7 @@ def extract_router(
         nonlocal captured_router
         captured_router = router
 
-    setattr(mock_app, "include_router", _capture_router)
+    mock_app.include_router = _capture_router  # type: ignore[method-assign]
 
     # Patch add_prefixed_docs to prevent separate card (no-op if function doesn't call it)
     def _noop_docs(*args: Any, **kwargs: Any) -> None:

svc_infra/app/env.py

@@ -5,7 +5,7 @@ import warnings
 from enum import StrEnum
 from functools import cache
 from pathlib import Path
-from typing import List, NamedTuple, Optional
+from typing import NamedTuple
 
 from dotenv import load_dotenv
 
@@ -39,7 +39,7 @@ SYNONYMS: dict[str, Environment] = {
     "production": PROD_ENV,
 }
 
-ALL_ENVIRONMENTS = {e for e in Environment}
+ALL_ENVIRONMENTS = set(Environment)
 
 
 def _normalize(raw: str | None) -> Environment | None:
@@ -129,12 +129,10 @@ def pick(*, prod, nonprod=None, dev=None, test=None, local=None):
         return local
     if nonprod is not None:
         return nonprod
-    raise ValueError(
-        "pick(): No value found for environment and 'nonprod' was not provided."
-    )
+    raise ValueError("pick(): No value found for environment and 'nonprod' was not provided.")
 
 
-def find_env_file(start: Optional[Path] = None) -> Optional[Path]:
+def find_env_file(start: Path | None = None) -> Path | None:
     env_file = os.getenv("APP_ENV_FILE") or os.getenv("SVC_INFRA_ENV_FILE")
     if env_file:
         p = Path(env_file).expanduser()
@@ -148,7 +146,7 @@ def find_env_file(start: Optional[Path] = None) -> Optional[Path]:
     return None
 
 
-def load_env_if_present(path: Optional[Path], *, override: bool = False) -> List[str]:
+def load_env_if_present(path: Path | None, *, override: bool = False) -> list[str]:
     if not path:
         return []
     before = dict(os.environ)

svc_infra/app/logging/add.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Sequence
 from logging.config import dictConfig
-from typing import TYPE_CHECKING, Sequence, cast
+from typing import TYPE_CHECKING, cast
 
 from svc_infra.app.env import CURRENT_ENVIRONMENT
 

svc_infra/app/logging/filter.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Iterable
+from collections.abc import Iterable
 
 
 def _is_metrics_like(record: logging.LogRecord, paths: Iterable[str]) -> bool:

svc_infra/app/logging/formats.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Sequence
 from enum import StrEnum
-from typing import Sequence, cast
+from typing import cast
 
 from pydantic import BaseModel
 
@@ -108,7 +109,7 @@ def _read_level() -> str:
     from svc_infra.app.env import pick
 
     return cast(
-        str,
+        "str",
         pick(prod="INFO", nonprod="DEBUG", dev="DEBUG", test="DEBUG", local="DEBUG"),
     ).upper()
 

svc_infra/app/root.py

@@ -2,8 +2,8 @@ from __future__ import annotations
 
 import os
 import subprocess
+from collections.abc import Iterable
 from pathlib import Path
-from typing import Iterable, Optional
 
 DEFAULT_SENTRIES: tuple[str, ...] = (
     ".git",
@@ -36,7 +36,7 @@ def _is_root_marker(dir_: Path, sentries: Iterable[str]) -> bool:
     return any((dir_ / name).exists() for name in sentries)
 
 
-def _git_toplevel(start: Path) -> Optional[Path]:
+def _git_toplevel(start: Path) -> Path | None:
     try:
         out = subprocess.check_output(
             ["git", "rev-parse", "--show-toplevel"],
@@ -50,7 +50,7 @@ def _git_toplevel(start: Path) -> Optional[Path]:
 
 
 def resolve_project_root(
-    start: Optional[Path] = None,
+    start: Path | None = None,
     *,
     env_var: str = ENV_VAR,
     extra_sentries: Iterable[str] = (),

svc_infra/billing/__init__.py

@@ -1,3 +1,19 @@
+"""Billing module for usage tracking, metering, and invoicing.
+
+Primary API:
+    AsyncBillingService - Async billing service
+
+Models:
+    UsageEvent, UsageAggregate, Invoice, InvoiceLine, Plan, Subscription, etc.
+
+Example:
+    from svc_infra.billing import AsyncBillingService
+
+    service = AsyncBillingService(async_session, tenant_id)
+    await service.record_usage(metric="api_calls", amount=1, ...)
+"""
+
+from .async_service import AsyncBillingService
 from .models import (
     Invoice,
     InvoiceLine,
@@ -8,9 +24,11 @@ from .models import (
     UsageAggregate,
     UsageEvent,
 )
-from .service import BillingService
 
 __all__ = [
+    # Primary API
+    "AsyncBillingService",
+    # Models
     "UsageEvent",
     "UsageAggregate",
     "Plan",
@@ -19,5 +37,4 @@ __all__ = [
     "Price",
     "Invoice",
     "InvoiceLine",
-    "BillingService",
 ]

svc_infra/billing/async_service.py

@@ -1,8 +1,30 @@
+"""Async Billing Service - Primary billing API.
+
+This is the recommended billing service for all new code. It provides
+full async/await support for usage tracking, aggregation, and invoicing.
+
+Usage:
+    from svc_infra.billing import AsyncBillingService
+
+    async with async_session_maker() as session:
+        service = AsyncBillingService(session, tenant_id="tenant_123")
+        await service.record_usage(
+            metric="api_calls",
+            amount=1,
+            at=datetime.now(timezone.utc),
+            idempotency_key="unique-key",
+            metadata={"endpoint": "/api/v1/users"},
+        )
+
+See also:
+    - models: Invoice, UsageEvent, UsageAggregate, etc.
+"""
+
 from __future__ import annotations
 
 import uuid
-from datetime import datetime, timedelta, timezone
-from typing import Optional, Sequence
+from collections.abc import Sequence
+from datetime import UTC, datetime, timedelta
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -25,7 +47,7 @@ class AsyncBillingService:
         metadata: dict | None,
     ) -> str:
         if at.tzinfo is None:
-            at = at.replace(tzinfo=timezone.utc)
+            at = at.replace(tzinfo=UTC)
         evt = UsageEvent(
             id=str(uuid.uuid4()),
             tenant_id=self.tenant_id,
@@ -40,9 +62,7 @@ class AsyncBillingService:
         return evt.id
 
     async def aggregate_daily(self, *, metric: str, day_start: datetime) -> int:
-        day_start = day_start.replace(
-            hour=0, minute=0, second=0, microsecond=0, tzinfo=timezone.utc
-        )
+        day_start = day_start.replace(hour=0, minute=0, second=0, microsecond=0, tzinfo=UTC)
         next_day = day_start + timedelta(days=1)
         total = 0
         rows: Sequence[UsageEvent] = (
@@ -88,7 +108,7 @@ class AsyncBillingService:
         return total
 
     async def list_daily_aggregates(
-        self, *, metric: str, date_from: Optional[datetime], date_to: Optional[datetime]
+        self, *, metric: str, date_from: datetime | None, date_to: datetime | None
     ) -> list[UsageAggregate]:
         q = select(UsageAggregate).where(
             UsageAggregate.tenant_id == self.tenant_id,

svc_infra/billing/jobs.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import inspect
-from datetime import datetime, timezone
-from typing import Any, Awaitable, Callable, Dict, Optional
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Any
 
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
@@ -23,7 +24,7 @@ async def job_aggregate_daily(
     """
     svc = AsyncBillingService(session=session, tenant_id=tenant_id)
     if day_start.tzinfo is None:
-        day_start = day_start.replace(tzinfo=timezone.utc)
+        day_start = day_start.replace(tzinfo=UTC)
     await svc.aggregate_daily(metric=metric, day_start=day_start)
 
 
@@ -41,9 +42,9 @@ async def job_generate_monthly_invoice(
     """
     svc = AsyncBillingService(session=session, tenant_id=tenant_id)
     if period_start.tzinfo is None:
-        period_start = period_start.replace(tzinfo=timezone.utc)
+        period_start = period_start.replace(tzinfo=UTC)
     if period_end.tzinfo is None:
-        period_end = period_end.replace(tzinfo=timezone.utc)
+        period_end = period_end.replace(tzinfo=UTC)
     return await svc.generate_monthly_invoice(
         period_start=period_start, period_end=period_end, currency=currency
     )
@@ -66,7 +67,7 @@ def enqueue_aggregate_daily(
     payload = {
         "tenant_id": tenant_id,
         "metric": metric,
-        "day_start": day_start.astimezone(timezone.utc).isoformat(),
+        "day_start": day_start.astimezone(UTC).isoformat(),
     }
     queue.enqueue(BILLING_AGGREGATE_JOB, payload, delay_seconds=delay_seconds)
 
@@ -82,8 +83,8 @@ def enqueue_generate_monthly_invoice(
 ) -> None:
     payload = {
         "tenant_id": tenant_id,
-        "period_start": period_start.astimezone(timezone.utc).isoformat(),
-        "period_end": period_end.astimezone(timezone.utc).isoformat(),
+        "period_start": period_start.astimezone(UTC).isoformat(),
+        "period_end": period_end.astimezone(UTC).isoformat(),
         "currency": currency,
     }
     queue.enqueue(BILLING_INVOICE_JOB, payload, delay_seconds=delay_seconds)
@@ -94,7 +95,7 @@ def make_daily_aggregate_tick(
     *,
     tenant_id: str,
     metric: str,
-    when: Optional[datetime] = None,
+    when: datetime | None = None,
 ):
     """Return an async function that enqueues a daily aggregate job.
 
@@ -103,18 +104,16 @@ def make_daily_aggregate_tick(
     """
 
     async def _tick():
-        ts = (when or datetime.now(timezone.utc)).astimezone(timezone.utc)
+        ts = (when or datetime.now(UTC)).astimezone(UTC)
         day_start = ts.replace(hour=0, minute=0, second=0, microsecond=0)
-        enqueue_aggregate_daily(
-            queue, tenant_id=tenant_id, metric=metric, day_start=day_start
-        )
+        enqueue_aggregate_daily(queue, tenant_id=tenant_id, metric=metric, day_start=day_start)
 
     return _tick
 
 
 def make_billing_job_handler(
     *,
-    session_factory: "async_sessionmaker[AsyncSession]",
+    session_factory: async_sessionmaker[AsyncSession],
     webhooks: WebhookService,
 ) -> Callable[[Job], Awaitable[None]]:
     """Create a worker handler that processes billing jobs and emits webhooks.
@@ -139,7 +138,7 @@ def make_billing_job_handler(
 
     async def _handler(job: Job) -> None:
         name = job.name
-        data: Dict[str, Any] = job.payload or {}
+        data: dict[str, Any] = job.payload or {}
         if name == BILLING_AGGREGATE_JOB:
             tenant_id = str(data.get("tenant_id"))
             metric = str(data.get("metric"))
@@ -156,7 +155,7 @@ def make_billing_job_handler(
                 {
                     "tenant_id": tenant_id,
                     "metric": metric,
-                    "day_start": day_start.astimezone(timezone.utc).isoformat(),
+                    "day_start": day_start.astimezone(UTC).isoformat(),
                     "total": int(total),
                 },
             )
@@ -166,12 +165,7 @@ def make_billing_job_handler(
             period_start_raw = data.get("period_start")
             period_end_raw = data.get("period_end")
             currency = str(data.get("currency"))
-            if (
-                not tenant_id
-                or not period_start_raw
-                or not period_end_raw
-                or not currency
-            ):
+            if not tenant_id or not period_start_raw or not period_end_raw or not currency:
                 return
             period_start = datetime.fromisoformat(str(period_start_raw))
             period_end = datetime.fromisoformat(str(period_end_raw))
@@ -186,8 +180,8 @@ def make_billing_job_handler(
                 {
                     "tenant_id": tenant_id,
                     "invoice_id": invoice_id,
-                    "period_start": period_start.astimezone(timezone.utc).isoformat(),
-                    "period_end": period_end.astimezone(timezone.utc).isoformat(),
+                    "period_start": period_start.astimezone(UTC).isoformat(),
+                    "period_end": period_end.astimezone(UTC).isoformat(),
                     "currency": currency,
                 },
             )
@@ -218,20 +212,16 @@ def add_billing_jobs(
 
             async def _tick_fn(tid=tenant_id, m=metric):
                 # Enqueue for the current UTC day
-                now = datetime.now(timezone.utc)
+                now = datetime.now(UTC)
                 day_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
-                enqueue_aggregate_daily(
-                    queue, tenant_id=tid, metric=m, day_start=day_start
-                )
+                enqueue_aggregate_daily(queue, tenant_id=tid, metric=m, day_start=day_start)
 
-            scheduler.add_task(
-                f"billing.aggregate.{tenant_id}.{metric}", interval, _tick_fn
-            )
+            scheduler.add_task(f"billing.aggregate.{tenant_id}.{metric}", interval, _tick_fn)
         elif name == "invoice":
             tenant_id = j["tenant_id"]
             currency = j["currency"]
-            pstart = datetime.fromisoformat(j["period_start"]).astimezone(timezone.utc)
-            pend = datetime.fromisoformat(j["period_end"]).astimezone(timezone.utc)
+            pstart = datetime.fromisoformat(j["period_start"]).astimezone(UTC)
+            pend = datetime.fromisoformat(j["period_end"]).astimezone(UTC)
 
             async def _tick_inv(tid=tenant_id, cs=currency, ps=pstart, pe=pend):
                 enqueue_generate_monthly_invoice(