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

svc_infra/api/fastapi/openapi/apply.py

@@ -1,13 +1,12 @@
 from __future__ import annotations
 
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 from fastapi import APIRouter
 
 
-def apply_default_security(
-    router: APIRouter, *, default_security: list[dict] | None
-) -> None:
+def apply_default_security(router: APIRouter, *, default_security: list[dict] | None) -> None:
     if default_security is None:
         return
     original_add = router.add_api_route
@@ -19,7 +18,7 @@ def apply_default_security(
             kwargs["openapi_extra"] = ox
         return original_add(path, endpoint, **kwargs)
 
-    setattr(router, "add_api_route", _wrapped_add_api_route)
+    router.add_api_route = _wrapped_add_api_route  # type: ignore[method-assign]
 
 
 def apply_default_responses(router: APIRouter, defaults: dict[int, dict]) -> None:
@@ -40,4 +39,4 @@ def apply_default_responses(router: APIRouter, defaults: dict[int, dict]) -> Non
         kwargs["responses"] = responses
         return original_add(path, endpoint, **kwargs)
 
-    setattr(router, "add_api_route", _wrapped_add_api_route)
+    router.add_api_route = _wrapped_add_api_route  # type: ignore[method-assign]

svc_infra/api/fastapi/openapi/conventions.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
-from typing import Any, Dict
+from typing import Any
 
 from fastapi import FastAPI
 
 from .mutators import conventions_mutator
 from .pipeline import apply_mutators
 
-PROBLEM_SCHEMA: Dict[str, Any] = {
+PROBLEM_SCHEMA: dict[str, Any] = {
     "type": "object",
     "properties": {
         "type": {
@@ -49,7 +49,7 @@ PROBLEM_SCHEMA: Dict[str, Any] = {
 }
 
 
-def _problem_example(**kw: Any) -> Dict[str, Any]:
+def _problem_example(**kw: Any) -> dict[str, Any]:
     base = {
         "type": "about:blank",
         "title": "Internal Server Error",
@@ -63,7 +63,7 @@ def _problem_example(**kw: Any) -> Dict[str, Any]:
     return base
 
 
-STANDARD_RESPONSES: Dict[str, Dict[str, Any]] = {
+STANDARD_RESPONSES: dict[str, dict[str, Any]] = {
     "BadRequest": {
         "description": "The request is malformed or missing required fields",
         "content": {

svc_infra/api/fastapi/openapi/mutators.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import re
-from typing import Callable, Dict, Iterable, Iterator, Tuple
+from collections.abc import Callable, Iterable, Iterator
 
 from ..auth.security import auth_login_path
 from .models import APIVersionSpec, ServiceInfo, VersionInfo
@@ -9,7 +9,7 @@ from .models import APIVersionSpec, ServiceInfo, VersionInfo
 _HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
 
 
-def _iter_ops(schema: dict) -> Iterator[Tuple[str, str, dict]]:
+def _iter_ops(schema: dict) -> Iterator[tuple[str, str, dict]]:
     """Yield (path, method, op) for each operation object."""
     paths = schema.get("paths") or {}
     for path, methods in paths.items():
@@ -273,9 +273,7 @@ def normalize_problem_and_examples_mutator():
         if not isinstance(val, dict):
             return
         inst = val.get("instance")
-        if isinstance(inst, str) and (
-            inst.startswith("/") or inst.startswith("about:")
-        ):
+        if isinstance(inst, str) and (inst.startswith("/") or inst.startswith("about:")):
             # make absolute to satisfy format: uri
             val["instance"] = ABSOLUTE_INSTANCE
 
@@ -481,7 +479,7 @@ def ensure_global_tags_mutator(default_desc: str = "Operations related to {tag}.
 
         # map existing tags by name and preserve their fields
         existing_list = schema.get("tags") or []
-        existing_map: Dict[str, dict] = {}
+        existing_map: dict[str, dict] = {}
         for item in existing_list:
             if isinstance(item, dict) and "name" in item:
                 existing_map[item["name"]] = dict(item)
@@ -498,9 +496,7 @@ def ensure_global_tags_mutator(default_desc: str = "Operations related to {tag}.
                     existing_map[name]["description"] = default_desc.format(tag=name)
 
         if existing_map:
-            schema["tags"] = sorted(
-                existing_map.values(), key=lambda x: x.get("name", "")
-            )
+            schema["tags"] = sorted(existing_map.values(), key=lambda x: x.get("name", ""))
 
         return schema
 
@@ -508,8 +504,8 @@ def ensure_global_tags_mutator(default_desc: str = "Operations related to {tag}.
 
 
 def attach_standard_responses_mutator(
-    codes: Dict[int, str] | None = None,
-    per_method: Dict[str, Iterable[int]] | None = None,
+    codes: dict[int, str] | None = None,
+    per_method: dict[str, Iterable[int]] | None = None,
     exclude_tags: set[str] | None = None,
     op_flag_disable: str = "x_disable_standard_responses",
 ):
@@ -657,9 +653,7 @@ def ensure_request_body_descriptions_mutator(
             if isinstance(rb, dict):
                 desc = rb.get("description")
                 if not isinstance(desc, str) or not desc.strip():
-                    rb["description"] = default_template.format(
-                        method=method.upper(), path=path
-                    )
+                    rb["description"] = default_template.format(method=method.upper(), path=path)
         return schema
 
     return m
@@ -847,9 +841,7 @@ def inject_safe_examples_mutator():
     """
 
     def _has_examples(mt_obj: dict) -> bool:
-        return isinstance(mt_obj, dict) and (
-            "example" in mt_obj or "examples" in mt_obj
-        )
+        return isinstance(mt_obj, dict) and ("example" in mt_obj or "examples" in mt_obj)
 
     def m(schema: dict) -> dict:
         schema = dict(schema)
@@ -1095,11 +1087,7 @@ def ensure_success_examples_mutator():
                 if not (200 <= ic < 300) or ic == 204:
                     continue
                 mt_obj = (resp.get("content") or {}).get("application/json")
-                if (
-                    not isinstance(mt_obj, dict)
-                    or "example" in mt_obj
-                    or "examples" in mt_obj
-                ):
+                if not isinstance(mt_obj, dict) or "example" in mt_obj or "examples" in mt_obj:
                     continue
                 sch = mt_obj.get("schema") or {}
 
@@ -1199,9 +1187,7 @@ def ensure_problem_examples_mutator():
                     if mt_obj is None:
                         # Create a basic media type referencing Problem schema when appropriate
                         if mt == "application/problem+json":
-                            mt_obj = {
-                                "schema": {"$ref": "#/components/schemas/Problem"}
-                            }
+                            mt_obj = {"schema": {"$ref": "#/components/schemas/Problem"}}
                             content[mt] = mt_obj
                         else:
                             continue
@@ -1495,12 +1481,8 @@ def attach_header_params_mutator():
                 if 200 <= ic < 300:
                     hdrs = resp.setdefault("headers", {})
                     hdrs.setdefault("ETag", {"$ref": "#/components/headers/ETag"})
-                    hdrs.setdefault(
-                        "Last-Modified", {"$ref": "#/components/headers/LastModified"}
-                    )
-                    hdrs.setdefault(
-                        "X-Request-Id", {"$ref": "#/components/headers/XRequestId"}
-                    )
+                    hdrs.setdefault("Last-Modified", {"$ref": "#/components/headers/LastModified"})
+                    hdrs.setdefault("X-Request-Id", {"$ref": "#/components/headers/XRequestId"})
                     hdrs.setdefault(
                         "X-RateLimit-Limit",
                         {"$ref": "#/components/headers/XRateLimitLimit"},

svc_infra/api/fastapi/openapi/pipeline.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Callable
+from collections.abc import Callable
 
 from fastapi import FastAPI
 from fastapi.openapi.utils import get_openapi
@@ -23,4 +23,4 @@ def apply_mutators(app: FastAPI, *mutators):
         app.openapi_schema = schema
         return schema
 
-    setattr(app, "openapi", patched)
+    app.openapi = patched  # type: ignore[method-assign]

svc_infra/api/fastapi/openapi/responses.py

@@ -1,32 +1,30 @@
 from __future__ import annotations
 
-from typing import Dict
-
 
 def ref(name: str) -> dict:
     return {"$ref": f"#/components/responses/{name}"}
 
 
-DEFAULT_PUBLIC: Dict[int, dict] = {
+DEFAULT_PUBLIC: dict[int, dict] = {
     400: ref("BadRequest"),
     422: ref("ValidationError"),
     500: ref("ServerError"),
 }
-DEFAULT_USER: Dict[int, dict] = {
+DEFAULT_USER: dict[int, dict] = {
     400: ref("BadRequest"),
     401: ref("Unauthorized"),
     403: ref("Forbidden"),
     422: ref("ValidationError"),
     500: ref("ServerError"),
 }
-DEFAULT_SERVICE: Dict[int, dict] = {
+DEFAULT_SERVICE: dict[int, dict] = {
     400: ref("BadRequest"),
     401: ref("Unauthorized"),
     403: ref("Forbidden"),
     429: ref("TooManyRequests"),
     500: ref("ServerError"),
 }
-DEFAULT_PROTECTED: Dict[int, dict] = {
+DEFAULT_PROTECTED: dict[int, dict] = {
     400: ref("BadRequest"),
     401: ref("Unauthorized"),
     403: ref("Forbidden"),

svc_infra/api/fastapi/openapi/security.py

@@ -6,9 +6,7 @@ from .mutators import auth_mutator
 from .pipeline import apply_mutators
 
 
-def _normalize_security_list(
-    sec: list | None, *, drop_schemes: set[str] | None = None
-) -> list:
+def _normalize_security_list(sec: list | None, *, drop_schemes: set[str] | None = None) -> list:
     if not sec:
         return []
     drop_schemes = drop_schemes or set()

svc_infra/api/fastapi/ops/add.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import os
-from typing import Callable
+from collections.abc import Callable
 
 from fastapi import FastAPI, HTTPException, Request
 from starlette.responses import JSONResponse
@@ -16,21 +16,19 @@ def add_probes(
     """Mount basic liveness/readiness/startup probes under prefix."""
     from svc_infra.api.fastapi.dual.public import public_router
 
-    router = public_router(
-        prefix=prefix, tags=["ops"], include_in_schema=include_in_schema
-    )
+    router = public_router(prefix=prefix, tags=["ops"], include_in_schema=include_in_schema)
 
     @router.get("/live")
-    async def live() -> JSONResponse:  # noqa: D401, ANN201
+    async def live() -> JSONResponse:
         return JSONResponse({"status": "ok"})
 
     @router.get("/ready")
-    async def ready() -> JSONResponse:  # noqa: D401, ANN201
+    async def ready() -> JSONResponse:
         # In the future, add checks (DB ping, cache ping) via DI hooks.
         return JSONResponse({"status": "ok"})
 
     @router.get("/startup")
-    async def startup_probe() -> JSONResponse:  # noqa: D401, ANN201
+    async def startup_probe() -> JSONResponse:
         return JSONResponse({"status": "ok"})
 
     app.include_router(router)
@@ -48,7 +46,7 @@ def add_maintenance_mode(
     """
 
     @app.middleware("http")
-    async def _maintenance_gate(request: Request, call_next):  # noqa: ANN001, ANN202
+    async def _maintenance_gate(request: Request, call_next):
         flag = str(os.getenv(env_var, "")).lower() in {"1", "true", "yes", "on"}
         if flag and request.method not in {"GET", "HEAD", "OPTIONS"}:
             path = request.scope.get("path", "")
@@ -65,7 +63,7 @@ def circuit_breaker_dependency(limit: int = 100, window_seconds: int = 60) -> Ca
     breaker. Here, we read an env var to simulate an open breaker.
     """
 
-    async def _dep(_: Request) -> None:  # noqa: D401, ANN202
+    async def _dep(_: Request) -> None:
         if str(os.getenv("CIRCUIT_OPEN", "")).lower() in {"1", "true", "yes", "on"}:
             raise HTTPException(status_code=503, detail="circuit open")
 

svc_infra/api/fastapi/pagination.py

@@ -4,14 +4,10 @@ import base64
 import contextvars
 import json
 import logging
+from collections.abc import Callable, Iterable, Sequence
 from typing import (
     Any,
-    Callable,
     Generic,
-    Iterable,
-    List,
-    Optional,
-    Sequence,
     TypeVar,
     cast,
 )
@@ -26,7 +22,7 @@ T = TypeVar("T")
 
 # ---------- Core query models ----------
 class CursorParams(BaseModel):
-    cursor: Optional[str] = None
+    cursor: str | None = None
     limit: int = 50
 
 
@@ -36,19 +32,19 @@ class PageParams(BaseModel):
 
 
 class FilterParams(BaseModel):
-    q: Optional[str] = None
-    sort: Optional[str] = None
-    created_after: Optional[str] = None
-    created_before: Optional[str] = None
-    updated_after: Optional[str] = None
-    updated_before: Optional[str] = None
+    q: str | None = None
+    sort: str | None = None
+    created_after: str | None = None
+    created_before: str | None = None
+    updated_after: str | None = None
+    updated_before: str | None = None
 
 
 # ---------- Envelope model ----------
 class Paginated(BaseModel, Generic[T]):
-    items: List[T]
-    next_cursor: Optional[str] = Field(None, description="Opaque cursor for next page")
-    total: Optional[int] = Field(None, description="Total items (optional)")
+    items: list[T]
+    next_cursor: str | None = Field(None, description="Opaque cursor for next page")
+    total: int | None = Field(None, description="Total items (optional)")
 
 
 # ---------- Cursor helpers ----------
@@ -57,13 +53,13 @@ def _encode_cursor(payload: dict) -> str:
     return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
 
 
-def decode_cursor(token: Optional[str]) -> dict[Any, Any]:
+def decode_cursor(token: str | None) -> dict[Any, Any]:
     """Public: decode an incoming cursor token for debugging/ops."""
     if not token:
         return {}
     s = token + "=" * (-len(token) % 4)
     raw = base64.urlsafe_b64decode(s.encode("ascii")).decode("utf-8")
-    return cast(dict[Any, Any], json.loads(raw))
+    return cast("dict[Any, Any]", json.loads(raw))
 
 
 # ---------- Context ----------
@@ -97,10 +93,8 @@ class PaginationContext(Generic[T]):
         self.limit_override = limit_override
 
     @property
-    def cursor(self) -> Optional[str]:
-        return (
-            (self.cursor_params or CursorParams()).cursor if self.allow_cursor else None
-        )
+    def cursor(self) -> str | None:
+        return (self.cursor_params or CursorParams()).cursor if self.allow_cursor else None
 
     @property
     def limit(self) -> int:
@@ -113,16 +107,12 @@ class PaginationContext(Generic[T]):
         return 50
 
     @property
-    def page(self) -> Optional[int]:
+    def page(self) -> int | None:
         return self.page_params.page if (self.allow_page and self.page_params) else None
 
     @property
-    def page_size(self) -> Optional[int]:
-        return (
-            self.page_params.page_size
-            if (self.allow_page and self.page_params)
-            else None
-        )
+    def page_size(self) -> int | None:
+        return self.page_params.page_size if (self.allow_page and self.page_params) else None
 
     @property
     def offset(self) -> int:
@@ -134,8 +124,8 @@ class PaginationContext(Generic[T]):
         self,
         items: list[T],
         *,
-        next_cursor: Optional[str] = None,
-        total: Optional[int] = None,
+        next_cursor: str | None = None,
+        total: int | None = None,
     ):
         if self.envelope:
             return Paginated[T](items=items, next_cursor=next_cursor, total=total)
@@ -143,15 +133,15 @@ class PaginationContext(Generic[T]):
 
     def next_cursor_from_last(
         self, items: Sequence[T], *, key: Callable[[T], str | int]
-    ) -> Optional[str]:
+    ) -> str | None:
         if not items:
             return None
         last_key = key(items[-1])
         return _encode_cursor({"after": last_key})
 
 
-_pagination_ctx: contextvars.ContextVar[PaginationContext | None] = (
-    contextvars.ContextVar("pagination_ctx", default=None)
+_pagination_ctx: contextvars.ContextVar[PaginationContext | None] = contextvars.ContextVar(
+    "pagination_ctx", default=None
 )
 
 
@@ -171,9 +161,7 @@ def use_pagination() -> PaginationContext:
 
 
 # ---------- Utilities ----------
-def text_filter(
-    items: Iterable[T], q: Optional[str], *getters: Callable[[T], str]
-) -> list[T]:
+def text_filter(items: Iterable[T], q: str | None, *getters: Callable[[T], str]) -> list[T]:
     if not q:
         return list(items)
     ql = q.lower()
@@ -195,7 +183,7 @@ def sort_by(
     key: Callable[[T], Any],
     desc: bool = False,
 ) -> list[T]:
-    return sorted(list(items), key=key, reverse=desc)
+    return sorted(items, key=key, reverse=desc)
 
 
 def cursor_window(items, *, cursor, limit, key, descending: bool, offset: int = 0):

svc_infra/api/fastapi/routers/__init__.py

@@ -4,7 +4,7 @@ import importlib
 import logging
 import pkgutil
 from types import ModuleType
-from typing import Any, Optional
+from typing import Any
 
 from fastapi import FastAPI
 from fastapi.routing import APIRoute
@@ -55,9 +55,7 @@ def _validate_base_package(base_package: str) -> ModuleType:
     try:
         package_module: ModuleType = importlib.import_module(base_package)
     except Exception as exc:
-        raise RuntimeError(
-            f"Could not import base_package '{base_package}': {exc}"
-        ) from exc
+        raise RuntimeError(f"Could not import base_package '{base_package}': {exc}") from exc
 
     if not hasattr(package_module, "__path__"):
         raise RuntimeError(
@@ -67,21 +65,17 @@ def _validate_base_package(base_package: str) -> ModuleType:
     return package_module
 
 
-def _normalize_environment(environment: Optional[Environment | str]) -> Environment:
+def _normalize_environment(environment: Environment | str | None) -> Environment:
     """Normalize the environment parameter."""
     return (
         CURRENT_ENVIRONMENT
         if environment is None
-        else (
-            Environment(environment)
-            if not isinstance(environment, Environment)
-            else environment
-        )
+        else (Environment(environment) if not isinstance(environment, Environment) else environment)
     )
 
 
 def _should_force_include_in_schema(
-    environment: Environment, force_include_in_schema: Optional[bool]
+    environment: Environment, force_include_in_schema: bool | None
 ) -> bool:
     """Determine if routers should be forced to include in schema."""
     if force_include_in_schema is None:
@@ -99,12 +93,9 @@ def _is_router_excluded_by_environment(
 
     # Support ALL_ENVIRONMENTS as a special value
     if router_excluded_envs is ALL_ENVIRONMENTS or (
-        isinstance(router_excluded_envs, set)
-        and router_excluded_envs == ALL_ENVIRONMENTS
+        isinstance(router_excluded_envs, set) and router_excluded_envs == ALL_ENVIRONMENTS
     ):
-        logger.debug(
-            f"Skipping router module {module_name} due to ALL_ENVIRONMENTS exclusion."
-        )
+        logger.debug(f"Skipping router module {module_name} due to ALL_ENVIRONMENTS exclusion.")
         return True
 
     # Normalize to set of Environment or str
@@ -117,16 +108,11 @@ def _is_router_excluded_by_environment(
     normalized_excluded_envs: set[Environment | str] = set()
     for e in router_excluded_envs:
         try:
-            normalized_excluded_envs.add(
-                Environment(e) if not isinstance(e, Environment) else e
-            )
+            normalized_excluded_envs.add(Environment(e) if not isinstance(e, Environment) else e)
         except Exception:
             normalized_excluded_envs.add(str(e))
 
-    if (
-        environment in normalized_excluded_envs
-        or str(environment) in normalized_excluded_envs
-    ):
+    if environment in normalized_excluded_envs or str(environment) in normalized_excluded_envs:
         logger.debug(
             f"Skipping router module {module_name} due to ROUTER_EXCLUDED_ENVIRONMENTS restriction: {router_excluded_envs}"
         )
@@ -225,10 +211,10 @@ def _process_router_module(
 def register_all_routers(
     app: FastAPI,
     *,
-    base_package: Optional[str] = None,
+    base_package: str | None = None,
     prefix: str = "",
-    environment: Optional[Environment | str] = None,
-    force_include_in_schema: Optional[bool] = None,
+    environment: Environment | str | None = None,
+    force_include_in_schema: bool | None = None,
 ) -> None:
     """
     Recursively discover and register all FastAPI routers under a routers package.
@@ -250,24 +236,18 @@ def register_all_routers(
     """
     if base_package is None:
         if __package__ is None:
-            raise RuntimeError(
-                "Cannot derive base_package; please pass base_package explicitly."
-            )
+            raise RuntimeError("Cannot derive base_package; please pass base_package explicitly.")
         base_package = __package__
 
     package_module = _validate_base_package(base_package)
     environment = _normalize_environment(environment)
-    force_include = _should_force_include_in_schema(
-        environment, force_include_in_schema
-    )
+    force_include = _should_force_include_in_schema(environment, force_include_in_schema)
 
     for _, module_name, _ in pkgutil.walk_packages(
         package_module.__path__, prefix=f"{base_package}."
     ):
         if _should_skip_module(module_name):
-            logger.debug(
-                "Skipping router module due to exclusion/private: %s", module_name
-            )
+            logger.debug("Skipping router module due to exclusion/private: %s", module_name)
             continue
 
         try:
@@ -276,6 +256,4 @@ def register_all_routers(
             logger.exception("Failed to import router module %s: %s", module_name, exc)
             continue
 
-        _process_router_module(
-            app, module, module_name, prefix, environment, force_include
-        )
+        _process_router_module(app, module, module_name, prefix, environment, force_include)