persistence-kit 3.3.0__tar.gz → 3.5.0__tar.gz

{persistence_kit-3.3.0 → persistence_kit-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.3.0
+Version: 3.5.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -21,6 +21,7 @@ Classifier: Typing :: Typed
 Provides-Extra: all
 Provides-Extra: api
 Provides-Extra: dynamodb
+Provides-Extra: restclient
 Provides-Extra: security
 Provides-Extra: security-cognito
 Provides-Extra: storage-routes
@@ -29,6 +30,7 @@ Provides-Extra: testing
 Requires-Dist: asyncpg (>=0.30.0,<0.31.0)
 Requires-Dist: boto3 (>=1.35.0,<2.0.0) ; extra == "storage-s3" or extra == "security-cognito" or extra == "dynamodb" or extra == "all"
 Requires-Dist: fastapi (>=0.115.0,<0.116.0) ; extra == "api" or extra == "storage-routes" or extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
+Requires-Dist: httpx (>=0.28.0,<0.29.0) ; extra == "restclient" or extra == "testing" or extra == "all"
 Requires-Dist: motor (>=3.7.1,<4.0.0)
 Requires-Dist: pydantic-settings (>=2.3.0,<3.0.0)
 Requires-Dist: pyjwt[crypto] (>=2.10.1,<3.0.0) ; extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"

{persistence_kit-3.3.0 → persistence_kit-3.5.0}/persistence_kit/__init__.py

@@ -32,6 +32,7 @@ from .storage import (
     get_export_storage,
 )
 from .authenticated_user import AuthenticatedUser
+from .resilience import CircuitBreaker, CircuitOpenError, CircuitState
 from .utils.upsert import dataclass_field_names, upsert_entity
 
 _OPTIONAL_EXPORTS = {
@@ -175,6 +176,83 @@ _OPTIONAL_EXPORTS = {
         "guess_export_media_type",
         "storage-routes",
     ),
+    "build_rest_client": (
+        "persistence_kit.restclient.factory",
+        "build_rest_client",
+        "restclient",
+    ),
+    "RestClientRegistry": (
+        "persistence_kit.restclient.registry",
+        "RestClientRegistry",
+        "restclient",
+    ),
+    "HttpxRestClient": (
+        "persistence_kit.restclient.client",
+        "HttpxRestClient",
+        "restclient",
+    ),
+    "MemoryRestClient": (
+        "persistence_kit.restclient.memory",
+        "MemoryRestClient",
+        "restclient",
+    ),
+    "ServiceConfig": (
+        "persistence_kit.restclient.config",
+        "ServiceConfig",
+        "restclient",
+    ),
+    "RetryPolicy": (
+        "persistence_kit.restclient.retry",
+        "RetryPolicy",
+        "restclient",
+    ),
+    "StaticEndpointResolver": (
+        "persistence_kit.restclient.resolver",
+        "StaticEndpointResolver",
+        "restclient",
+    ),
+    "DirectoryEndpointResolver": (
+        "persistence_kit.restclient.resolver",
+        "DirectoryEndpointResolver",
+        "restclient",
+    ),
+    "decode": ("persistence_kit.restclient.mapping", "decode", "restclient"),
+    "encode": ("persistence_kit.restclient.mapping", "encode", "restclient"),
+    "NoAuth": ("persistence_kit.restclient.auth", "NoAuth", "restclient"),
+    "ApiKeyAuth": ("persistence_kit.restclient.auth", "ApiKeyAuth", "restclient"),
+    "BearerAuth": ("persistence_kit.restclient.auth", "BearerAuth", "restclient"),
+    "BasicAuth": ("persistence_kit.restclient.auth", "BasicAuth", "restclient"),
+    "OAuth2ClientCredentials": (
+        "persistence_kit.restclient.auth",
+        "OAuth2ClientCredentials",
+        "restclient",
+    ),
+    "LoginTokenAuth": (
+        "persistence_kit.restclient.auth",
+        "LoginTokenAuth",
+        "restclient",
+    ),
+    "RestClient": ("persistence_kit.restclient.contracts", "RestClient", "restclient"),
+    "Authenticator": (
+        "persistence_kit.restclient.contracts",
+        "Authenticator",
+        "restclient",
+    ),
+    "EndpointResolver": (
+        "persistence_kit.restclient.contracts",
+        "EndpointResolver",
+        "restclient",
+    ),
+    "RestClientError": (
+        "persistence_kit.restclient.errors",
+        "RestClientError",
+        "restclient",
+    ),
+    "RestHTTPError": (
+        "persistence_kit.restclient.errors",
+        "RestHTTPError",
+        "restclient",
+    ),
 }
 
 __all__ = [
@@ -200,6 +278,9 @@ __all__ = [
     "is_duplicate_startup_error",
     "run_startup_bootstrap",
     "AuthenticatedUser",
+    "CircuitBreaker",
+    "CircuitState",
+    "CircuitOpenError",
     "dataclass_field_names",
     "upsert_entity",
     "ObjectStorage",

persistence_kit-3.5.0/persistence_kit/resilience/__init__.py

@@ -0,0 +1,11 @@
+from persistence_kit.resilience.circuit import (
+    CircuitBreaker,
+    CircuitOpenError,
+    CircuitState,
+)
+
+__all__ = [
+    "CircuitBreaker",
+    "CircuitState",
+    "CircuitOpenError",
+]

persistence_kit-3.5.0/persistence_kit/resilience/circuit.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import time
+from enum import Enum
+
+
+class CircuitState(str, Enum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitOpenError(Exception):
+    """Raised when an operation is short-circuited because the circuit is open."""
+
+
+class CircuitBreaker:
+    """Generic in-process circuit breaker for any external operation.
+
+    Domain-agnostic: it only counts successes and failures. The caller decides
+    what counts as a failure (an exception, a 5xx status, a slow response, a DB
+    error) and calls :meth:`record_failure` / :meth:`record_success`, gating each
+    attempt on :meth:`allow` (or :meth:`guard`).
+
+    After ``failure_threshold`` consecutive failures the circuit opens and calls
+    are rejected for ``recovery_timeout`` seconds. It then moves to half-open and
+    lets ``half_open_max_calls`` probe calls through: a success closes it, a
+    failure re-opens it.
+
+    Not synchronized; intended for a single event loop per breaker instance.
+    """
+
+    def __init__(
+        self,
+        *,
+        failure_threshold: int = 5,
+        recovery_timeout: float = 30.0,
+        half_open_max_calls: int = 1,
+    ) -> None:
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.half_open_max_calls = half_open_max_calls
+        self._state = CircuitState.CLOSED
+        self._failures = 0
+        self._opened_at = 0.0
+        self._half_open_calls = 0
+
+    @property
+    def state(self) -> CircuitState:
+        return self._state
+
+    def allow(self) -> bool:
+        if self._state is CircuitState.OPEN:
+            if time.monotonic() - self._opened_at >= self.recovery_timeout:
+                self._state = CircuitState.HALF_OPEN
+                self._half_open_calls = 0
+            else:
+                return False
+        if self._state is CircuitState.HALF_OPEN:
+            if self._half_open_calls >= self.half_open_max_calls:
+                return False
+            self._half_open_calls += 1
+        return True
+
+    def guard(self, message: str = "Circuito abierto; operacion corto-circuitada.") -> None:
+        if not self.allow():
+            raise CircuitOpenError(message)
+
+    def record_success(self) -> None:
+        self._failures = 0
+        self._half_open_calls = 0
+        self._state = CircuitState.CLOSED
+
+    def record_failure(self) -> None:
+        if self._state is CircuitState.HALF_OPEN:
+            self._trip()
+            return
+        self._failures += 1
+        if self._failures >= self.failure_threshold:
+            self._trip()
+
+    def _trip(self) -> None:
+        self._state = CircuitState.OPEN
+        self._opened_at = time.monotonic()
+        self._half_open_calls = 0

persistence_kit-3.5.0/persistence_kit/restclient/__init__.py

@@ -0,0 +1,105 @@
+from persistence_kit.restclient.auth import (
+    ApiKeyAuth,
+    ApiKeyLocation,
+    BasicAuth,
+    BearerAuth,
+    LoginTokenAuth,
+    NoAuth,
+    OAuth2ClientCredentials,
+)
+from persistence_kit.resilience import CircuitBreaker, CircuitState
+from persistence_kit.restclient.config import ServiceConfig
+from persistence_kit.restclient.contracts import (
+    Authenticator,
+    EndpointResolver,
+    RestClient,
+    RestRequest,
+    RestResponse,
+)
+from persistence_kit.restclient.errors import (
+    RestAuthError,
+    RestCircuitOpenError,
+    RestClientError,
+    RestConfigError,
+    RestHTTPError,
+    RestTimeoutError,
+    RestTransportError,
+)
+from persistence_kit.restclient.aggregate import (
+    Expansion,
+    expand,
+    expand_chain,
+    expand_recursive,
+)
+from persistence_kit.restclient.factory import build_rest_client
+from persistence_kit.restclient.mapping import (
+    ModelMappingMixin,
+    decode,
+    encode,
+)
+from persistence_kit.restclient.memory import MemoryRestClient
+from persistence_kit.restclient.populate import (
+    RestRelation,
+    RestRelationRegistry,
+    populate,
+)
+from persistence_kit.restclient.payload import serialize_xml
+from persistence_kit.restclient.registry import RegisteredService, RestClientRegistry
+from persistence_kit.restclient.resolver import (
+    DirectoryEndpointResolver,
+    StaticEndpointResolver,
+)
+from persistence_kit.restclient.retry import RetryPolicy
+
+__all__ = [
+    "RestClient",
+    "RestRequest",
+    "RestResponse",
+    "Authenticator",
+    "EndpointResolver",
+    "ServiceConfig",
+    "StaticEndpointResolver",
+    "DirectoryEndpointResolver",
+    "serialize_xml",
+    "RetryPolicy",
+    "CircuitBreaker",
+    "CircuitState",
+    "decode",
+    "encode",
+    "ModelMappingMixin",
+    "expand",
+    "expand_chain",
+    "expand_recursive",
+    "Expansion",
+    "populate",
+    "RestRelation",
+    "RestRelationRegistry",
+    "NoAuth",
+    "ApiKeyAuth",
+    "ApiKeyLocation",
+    "BearerAuth",
+    "BasicAuth",
+    "OAuth2ClientCredentials",
+    "LoginTokenAuth",
+    "MemoryRestClient",
+    "RestClientRegistry",
+    "RegisteredService",
+    "build_rest_client",
+    "RestClientError",
+    "RestConfigError",
+    "RestAuthError",
+    "RestTimeoutError",
+    "RestTransportError",
+    "RestCircuitOpenError",
+    "RestHTTPError",
+    "HttpxRestClient",
+]
+
+
+def __getattr__(name: str):
+    if name == "HttpxRestClient":
+        from persistence_kit.restclient.client import HttpxRestClient
+
+        globals()[name] = HttpxRestClient
+        return HttpxRestClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

persistence_kit-3.5.0/persistence_kit/restclient/aggregate.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Sequence
+
+Fetch = Callable[[Any], Awaitable[Sequence[Any]]]
+Attach = "str | Callable[[Any, list[Any]], None]"
+
+
+def _attach(node: Any, children: list[Any], attach: Any) -> None:
+    if callable(attach):
+        attach(node, children)
+    elif isinstance(node, dict):
+        node[attach] = children
+    else:
+        setattr(node, attach, children)
+
+
+@dataclass(slots=True)
+class Expansion:
+    """One level of a hierarchy: how to fetch a node's children and where to
+    place them on the node."""
+
+    fetch: Fetch
+    attach: Any
+
+
+async def expand(
+    nodes: Sequence[Any],
+    fetch: Fetch,
+    attach: Any,
+    *,
+    concurrency: int = 8,
+) -> list[Any]:
+    """Fetch the children of every node concurrently, attach them, and return the
+    flattened next frontier so levels can be chained.
+
+    ``fetch`` is any async ``node -> children``; it needs no knowledge of the
+    transport. ``attach`` is a field name (attribute or dict key) or a callable
+    ``(node, children) -> None``.
+    """
+    nodes = list(nodes)
+    if not nodes:
+        return []
+
+    semaphore = asyncio.Semaphore(max(1, concurrency))
+
+    async def run(node: Any) -> list[Any]:
+        async with semaphore:
+            children = list(await fetch(node))
+        _attach(node, children, attach)
+        return children
+
+    results = await asyncio.gather(*(run(node) for node in nodes))
+
+    frontier: list[Any] = []
+    for children in results:
+        frontier.extend(children)
+    return frontier
+
+
+async def expand_chain(
+    roots: Sequence[Any],
+    expansions: Sequence[Expansion],
+    *,
+    concurrency: int = 8,
+) -> list[Any]:
+    """Apply several expansion levels in a single call. Each level expands the
+    frontier produced by the previous one, so ``roots`` ends up fully nested."""
+    frontier: list[Any] = list(roots)
+    for expansion in expansions:
+        frontier = await expand(
+            frontier, expansion.fetch, expansion.attach, concurrency=concurrency
+        )
+    return list(roots)
+
+
+async def expand_recursive(
+    nodes: Sequence[Any],
+    fetch: Fetch,
+    attach: Any,
+    *,
+    concurrency: int = 8,
+    max_depth: int | None = None,
+) -> list[Any]:
+    """Expand a self-referential hierarchy of homogeneous nodes until no children
+    are returned or ``max_depth`` is reached."""
+    roots = list(nodes)
+    frontier = roots
+    depth = 0
+    while frontier and (max_depth is None or depth < max_depth):
+        frontier = await expand(frontier, fetch, attach, concurrency=concurrency)
+        depth += 1
+    return roots

persistence_kit-3.5.0/persistence_kit/restclient/auth/__init__.py

@@ -0,0 +1,16 @@
+from persistence_kit.restclient.auth.api_key import ApiKeyAuth, ApiKeyLocation
+from persistence_kit.restclient.auth.base import NoAuth
+from persistence_kit.restclient.auth.basic import BasicAuth
+from persistence_kit.restclient.auth.bearer import BearerAuth
+from persistence_kit.restclient.auth.login import LoginTokenAuth
+from persistence_kit.restclient.auth.oauth2 import OAuth2ClientCredentials
+
+__all__ = [
+    "NoAuth",
+    "ApiKeyAuth",
+    "ApiKeyLocation",
+    "BearerAuth",
+    "BasicAuth",
+    "OAuth2ClientCredentials",
+    "LoginTokenAuth",
+]

persistence_kit-3.5.0/persistence_kit/restclient/auth/api_key.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from persistence_kit.restclient.contracts import RestRequest, RestResponse
+
+ApiKeyLocation = Literal["header", "query"]
+
+
+class ApiKeyAuth:
+    """Injects an API key either as a request header or a query parameter."""
+
+    def __init__(
+        self,
+        name: str,
+        value: str,
+        *,
+        location: ApiKeyLocation = "header",
+    ) -> None:
+        if location not in ("header", "query"):
+            raise ValueError("location debe ser 'header' o 'query'.")
+        self._name = name
+        self._value = value
+        self._location = location
+
+    async def apply(self, request: RestRequest) -> RestRequest:
+        if self._location == "header":
+            request.headers[self._name] = self._value
+        else:
+            request.params[self._name] = self._value
+        return request
+
+    async def on_unauthorized(self, response: RestResponse) -> bool:
+        return False

persistence_kit-3.5.0/persistence_kit/restclient/auth/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from persistence_kit.restclient.contracts import RestRequest, RestResponse
+
+
+class NoAuth:
+    """Authenticator for public APIs that require no credentials."""
+
+    async def apply(self, request: RestRequest) -> RestRequest:
+        return request
+
+    async def on_unauthorized(self, response: RestResponse) -> bool:
+        return False

persistence_kit-3.5.0/persistence_kit/restclient/auth/basic.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import base64
+
+from persistence_kit.restclient.contracts import RestRequest, RestResponse
+
+
+class BasicAuth:
+    """HTTP Basic authentication."""
+
+    def __init__(self, username: str, password: str) -> None:
+        raw = f"{username}:{password}".encode("utf-8")
+        self._value = "Basic " + base64.b64encode(raw).decode("ascii")
+
+    async def apply(self, request: RestRequest) -> RestRequest:
+        request.headers["Authorization"] = self._value
+        return request
+
+    async def on_unauthorized(self, response: RestResponse) -> bool:
+        return False

persistence_kit-3.5.0/persistence_kit/restclient/auth/bearer.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from persistence_kit.restclient.contracts import RestRequest, RestResponse
+
+
+class BearerAuth:
+    """Injects a static bearer (or custom scheme) token in a header."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        scheme: str = "Bearer",
+        header: str = "Authorization",
+    ) -> None:
+        self._token = token
+        self._scheme = scheme
+        self._header = header
+
+    async def apply(self, request: RestRequest) -> RestRequest:
+        prefix = f"{self._scheme} " if self._scheme else ""
+        request.headers[self._header] = f"{prefix}{self._token}"
+        return request
+
+    async def on_unauthorized(self, response: RestResponse) -> bool:
+        return False

persistence_kit-3.5.0/persistence_kit/restclient/auth/login.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Mapping
+
+from persistence_kit.restclient.contracts import RestRequest, RestResponse
+from persistence_kit.restclient.errors import RestAuthError
+
+
+def _dig(data: Any, path: str) -> Any:
+    current = data
+    for part in path.split("."):
+        if isinstance(current, dict):
+            current = current.get(part)
+        else:
+            current = getattr(current, part, None)
+    return current
+
+
+class LoginTokenAuth:
+    """Logs in with username/password at a login endpoint and sends the returned
+    token as a bearer. The token is cached until shortly before expiry and
+    re-fetched automatically after a 401.
+
+    ``send_as`` picks the request body ("json" or "form"). ``token_field`` and
+    ``expires_field`` are dotted paths into the login response.
+    """
+
+    def __init__(
+        self,
+        *,
+        login_url: str,
+        username: str,
+        password: str,
+        username_field: str = "username",
+        password_field: str = "password",
+        send_as: str = "json",
+        token_field: str = "access_token",
+        expires_field: str | None = "expires_in",
+        default_ttl_seconds: float = 3600.0,
+        extra_fields: Mapping[str, Any] | None = None,
+        header: str = "Authorization",
+        scheme: str = "Bearer",
+        leeway_seconds: float = 30.0,
+        timeout_seconds: float = 10.0,
+        verify_tls: bool = True,
+    ) -> None:
+        if send_as not in ("json", "form"):
+            raise ValueError("send_as debe ser 'json' o 'form'.")
+        self._login_url = login_url
+        self._username = username
+        self._password = password
+        self._username_field = username_field
+        self._password_field = password_field
+        self._send_as = send_as
+        self._token_field = token_field
+        self._expires_field = expires_field
+        self._default_ttl = default_ttl_seconds
+        self._extra_fields = dict(extra_fields or {})
+        self._header = header
+        self._scheme = scheme
+        self._leeway = leeway_seconds
+        self._timeout = timeout_seconds
+        self._verify_tls = verify_tls
+        self._token: str | None = None
+        self._expires_at = 0.0
+
+    async def apply(self, request: RestRequest) -> RestRequest:
+        token = await self._ensure_token()
+        prefix = f"{self._scheme} " if self._scheme else ""
+        request.headers[self._header] = f"{prefix}{token}"
+        return request
+
+    async def on_unauthorized(self, response: RestResponse) -> bool:
+        self._token = None
+        self._expires_at = 0.0
+        return True
+
+    async def _ensure_token(self) -> str:
+        if self._token and time.monotonic() < self._expires_at - self._leeway:
+            return self._token
+        await self._login()
+        assert self._token is not None
+        return self._token
+
+    async def _login(self) -> None:
+        import httpx
+
+        payload: dict[str, Any] = {
+            self._username_field: self._username,
+            self._password_field: self._password,
+        }
+        payload.update(self._extra_fields)
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=self._timeout, verify=self._verify_tls
+            ) as client:
+                if self._send_as == "json":
+                    response = await client.post(self._login_url, json=payload)
+                else:
+                    response = await client.post(self._login_url, data=payload)
+        except httpx.HTTPError as exc:
+            raise RestAuthError(
+                f"No se pudo contactar el login endpoint '{self._login_url}': {exc}"
+            ) from exc
+
+        if response.status_code >= 400:
+            raise RestAuthError(
+                f"El login endpoint respondio {response.status_code} al autenticar."
+            )
+
+        data = response.json()
+        token = _dig(data, self._token_field)
+        if not token:
+            raise RestAuthError(
+                f"La respuesta del login no incluye el campo '{self._token_field}'."
+            )
+
+        self._token = str(token)
+        expires = _dig(data, self._expires_field) if self._expires_field else None
+        self._expires_at = time.monotonic() + (
+            float(expires) if expires else self._default_ttl
+        )