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

svc_infra/api/fastapi/pagination.py

@@ -3,11 +3,24 @@ from __future__ import annotations
 import base64
 import contextvars
 import json
-from typing import Any, Callable, Generic, Iterable, List, Optional, Sequence, TypeVar
+import logging
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    TypeVar,
+    cast,
+)
 
 from fastapi import Query, Request
 from pydantic import BaseModel, Field
 
+logger = logging.getLogger(__name__)
+
 T = TypeVar("T")
 
 
@@ -44,13 +57,13 @@ def _encode_cursor(payload: dict) -> str:
     return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
 
 
-def decode_cursor(token: Optional[str]) -> dict:
+def decode_cursor(token: Optional[str]) -> 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 json.loads(raw)
+    return cast(dict[Any, Any], json.loads(raw))
 
 
 # ---------- Context ----------
@@ -85,11 +98,15 @@ class PaginationContext(Generic[T]):
 
     @property
     def cursor(self) -> Optional[str]:
-        return (self.cursor_params or CursorParams()).cursor if self.allow_cursor else None
+        return (
+            (self.cursor_params or CursorParams()).cursor if self.allow_cursor else None
+        )
 
     @property
     def limit(self) -> int:
-        if self.allow_cursor and self.cursor_params and self.cursor_params.cursor is not None:
+        # For cursor-based pagination, always honor the requested limit, even on the first page
+        # (cursor may be None for the first page).
+        if self.allow_cursor and self.cursor_params:
             return self.cursor_params.limit
         if self.allow_page and self.page_params:
             return self.limit_override or self.page_params.page_size
@@ -101,7 +118,11 @@ class PaginationContext(Generic[T]):
 
     @property
     def page_size(self) -> Optional[int]:
-        return self.page_params.page_size if (self.allow_page and self.page_params) else None
+        return (
+            self.page_params.page_size
+            if (self.allow_page and self.page_params)
+            else None
+        )
 
     @property
     def offset(self) -> int:
@@ -110,7 +131,11 @@ class PaginationContext(Generic[T]):
         return 0
 
     def wrap(
-        self, items: list[T], *, next_cursor: Optional[str] = None, total: Optional[int] = None
+        self,
+        items: list[T],
+        *,
+        next_cursor: Optional[str] = None,
+        total: Optional[int] = None,
     ):
         if self.envelope:
             return Paginated[T](items=items, next_cursor=next_cursor, total=total)
@@ -125,8 +150,8 @@ class PaginationContext(Generic[T]):
         return _encode_cursor({"after": last_key})
 
 
-_pagination_ctx: contextvars.ContextVar[PaginationContext] = contextvars.ContextVar(
-    "pagination_ctx", default=None
+_pagination_ctx: contextvars.ContextVar[PaginationContext | None] = (
+    contextvars.ContextVar("pagination_ctx", default=None)
 )
 
 
@@ -146,7 +171,9 @@ 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: Optional[str], *getters: Callable[[T], str]
+) -> list[T]:
     if not q:
         return list(items)
     ql = q.lower()
@@ -157,8 +184,8 @@ def text_filter(items: Iterable[T], q: Optional[str], *getters: Callable[[T], st
                 if ql in (g(it) or "").lower():
                     out.append(it)
                     break
-            except Exception:
-                pass
+            except Exception as e:
+                logger.debug("text_filter getter failed for item: %s", e)
     return out
 
 
@@ -215,7 +242,7 @@ def make_pagination_injector(
     # Cursor-only (common case)
     if allow_cursor and not allow_page and not include_filters:
 
-        async def _inject(
+        async def _inject_cursor(
             request: Request,
             cursor: str | None = Query(None),
             limit: int = Query(default_limit, ge=1, le=max_limit),
@@ -233,12 +260,12 @@ def make_pagination_injector(
             )
             return None
 
-        return _inject
+        return _inject_cursor
 
     # Cursor + filters
     if allow_cursor and not allow_page and include_filters:
 
-        async def _inject(
+        async def _inject_cursor_with_filters(
             request: Request,
             cursor: str | None = Query(None),
             limit: int = Query(default_limit, ge=1, le=max_limit),
@@ -270,12 +297,12 @@ def make_pagination_injector(
             )
             return None
 
-        return _inject
+        return _inject_cursor_with_filters
 
     # Page-only
     if not allow_cursor and allow_page:
 
-        async def _inject(
+        async def _inject_page(
             request: Request,
             page: int = Query(1, ge=1),
             page_size: int = Query(default_limit, ge=1, le=max_limit),
@@ -293,10 +320,10 @@ def make_pagination_injector(
             )
             return None
 
-        return _inject
+        return _inject_page
 
     # Both cursor + page (rare; exposes all)
-    async def _inject(
+    async def _inject_all(
         request: Request,
         cursor: str | None = Query(None),
         limit: int = Query(default_limit, ge=1, le=max_limit),
@@ -336,7 +363,7 @@ def make_pagination_injector(
         )
         return None
 
-    return _inject
+    return _inject_all
 
 
 # ----- Convenience helpers for routers -----

svc_infra/api/fastapi/routers/__init__.py

@@ -4,12 +4,18 @@ import importlib
 import logging
 import pkgutil
 from types import ModuleType
-from typing import Optional
+from typing import Any, Optional
 
 from fastapi import FastAPI
 from fastapi.routing import APIRoute
 
-from svc_infra.app.env import ALL_ENVIRONMENTS, CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV, Environment
+from svc_infra.app.env import (
+    ALL_ENVIRONMENTS,
+    CURRENT_ENVIRONMENT,
+    DEV_ENV,
+    LOCAL_ENV,
+    Environment,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -49,7 +55,9 @@ 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(
@@ -64,7 +72,11 @@ def _normalize_environment(environment: Optional[Environment | str]) -> Environm
     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
+        )
     )
 
 
@@ -87,9 +99,12 @@ 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
@@ -99,14 +114,19 @@ def _is_router_excluded_by_environment(
         )
         return False
 
-    normalized_excluded_envs = set()
+    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}"
         )
@@ -126,7 +146,7 @@ def _is_router_included_by_environment(
             f"ROUTER_ENVIRONMENTS in {module_name} must be a set/list/tuple, got {type(router_envs)}"
         )
         return True
-    normalized = set()
+    normalized: set[Environment | str] = set()
     for e in router_envs:
         try:
             normalized.add(Environment(e) if not isinstance(e, Environment) else e)
@@ -163,7 +183,7 @@ def _build_include_kwargs(module: ModuleType, prefix: str, force_include: bool)
     router_tag = getattr(module, "ROUTER_TAG", None)
     include_in_schema = getattr(module, "INCLUDE_ROUTER_IN_SCHEMA", True)
 
-    include_kwargs = {"prefix": prefix}
+    include_kwargs: dict[str, Any] = {"prefix": prefix}
     if router_prefix:
         include_kwargs["prefix"] = prefix.rstrip("/") + router_prefix
     if router_tag:
@@ -230,18 +250,24 @@ 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:
@@ -250,4 +276,6 @@ 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
+        )

svc_infra/api/fastapi/routers/ping.py

@@ -14,6 +14,7 @@ router = public_router(tags=["Health Check"])
     PING_PATH,
     status_code=status.HTTP_200_OK,
     description="Operation to check if the service is up and running",
+    operation_id="health_ping_get",
 )
 def ping():
     logging.info("Health check: /ping endpoint accessed. Service is responsive.")