brokkr-client 0.3.0__tar.gz

brokkr_client-0.3.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: brokkr-client
+Version: 0.3.0
+Summary: Ergonomic Python wrapper around the auto-generated brokkr-client-generated low-level client
+Requires-Dist: brokkr-client-generated
+Requires-Dist: httpx>=0.23.0,<0.29.0
+Requires-Dist: pytest>=8 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23 ; extra == 'test'
+Requires-Dist: respx>=0.21 ; extra == 'test'
+Requires-Python: >=3.10
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# brokkr-client
+
+Ergonomic Python client for the Brokkr broker API.
+
+The import name remains `brokkr` (`from brokkr import BrokkrClient`); the
+PyPI distribution name is `brokkr-client`.
+
+This is a thin wrapper around the auto-generated `brokkr-client-generated`
+package (produced by `openapi-python-client` from the broker's OpenAPI
+spec). The wrapper adds:
+
+- A single-credential constructor that injects the `Authorization` header
+  on every request. The three security schemes the spec declares
+  (`admin_pak` / `agent_pak` / `generator_pak`) all map to the same header
+  and the broker disambiguates at runtime — the wrapper hides that detail.
+- `BrokkrError`, a single exception type that wraps the generated typed
+  `ErrorResponse` and exposes `.code` for stable pattern-matching.
+- An opt-in `retry(...)` helper with exponential backoff for transient
+  transport / 5xx failures. Retry is per-call so callers decide which
+  operations (typically idempotent GETs) are safe.
+
+Pagination iterators are intentionally absent: the v1 broker API returns
+full collections without cursor tokens. `Stream`-style adapters belong
+here when the API adds pagination.
+
+The wrapper is intentionally small. Most of the surface is the generated
+client; reach for it via `client.api` when the wrapper doesn't cover what
+you need.

brokkr_client-0.3.0/README.md

@@ -0,0 +1,28 @@
+# brokkr-client
+
+Ergonomic Python client for the Brokkr broker API.
+
+The import name remains `brokkr` (`from brokkr import BrokkrClient`); the
+PyPI distribution name is `brokkr-client`.
+
+This is a thin wrapper around the auto-generated `brokkr-client-generated`
+package (produced by `openapi-python-client` from the broker's OpenAPI
+spec). The wrapper adds:
+
+- A single-credential constructor that injects the `Authorization` header
+  on every request. The three security schemes the spec declares
+  (`admin_pak` / `agent_pak` / `generator_pak`) all map to the same header
+  and the broker disambiguates at runtime — the wrapper hides that detail.
+- `BrokkrError`, a single exception type that wraps the generated typed
+  `ErrorResponse` and exposes `.code` for stable pattern-matching.
+- An opt-in `retry(...)` helper with exponential backoff for transient
+  transport / 5xx failures. Retry is per-call so callers decide which
+  operations (typically idempotent GETs) are safe.
+
+Pagination iterators are intentionally absent: the v1 broker API returns
+full collections without cursor tokens. `Stream`-style adapters belong
+here when the API adds pagination.
+
+The wrapper is intentionally small. Most of the surface is the generated
+client; reach for it via `client.api` when the wrapper doesn't cover what
+you need.

brokkr_client-0.3.0/brokkr/__init__.py

@@ -0,0 +1,16 @@
+"""Ergonomic Python wrapper around brokkr-broker-client."""
+
+from brokkr.client import BrokkrClient
+from brokkr.errors import BrokkrError
+
+# Re-export the typed ErrorResponse model so consumers don't need to dig into
+# the generated package layout.
+from brokkr_broker_client.models import ErrorResponse
+
+# The generated `Generator` model clashes with `typing.Generator` and produces
+# mypy false positives when imported into PEP 604 unions. Re-export under a
+# clearer name; the original is still reachable as
+# `brokkr_broker_client.models.Generator`.
+from brokkr_broker_client.models import Generator as TemplateGenerator
+
+__all__ = ["BrokkrClient", "BrokkrError", "ErrorResponse", "TemplateGenerator"]

brokkr_client-0.3.0/brokkr/client.py

@@ -0,0 +1,109 @@
+"""High-level Brokkr client wrapping the generated low-level client."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, TypeVar
+
+import httpx
+
+from brokkr_broker_client import AuthenticatedClient, Client
+from brokkr_broker_client.models import ErrorResponse
+
+from brokkr.errors import BrokkrError
+
+T = TypeVar("T")
+
+# Default timeouts mirror the Rust wrapper.
+_DEFAULT_REQUEST_TIMEOUT = 30.0  # seconds
+_DEFAULT_CONNECT_TIMEOUT = 10.0  # seconds
+_DEFAULT_MAX_RETRIES = 3
+_DEFAULT_INITIAL_BACKOFF = 0.2  # seconds
+_MAX_BACKOFF = 10.0
+
+
+class BrokkrClient:
+    """Ergonomic Brokkr broker client.
+
+    Construct with a base URL and (optionally) a PAK token. The wrapper
+    holds the generated `AuthenticatedClient` (or `Client`, when no token
+    is supplied) plus a retry policy. Access the generated API surface via
+    `client.api`; reach for the raw httpx session via `client.api.get_httpx_client()`.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str | None = None,
+        request_timeout: float = _DEFAULT_REQUEST_TIMEOUT,
+        connect_timeout: float = _DEFAULT_CONNECT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        initial_backoff: float = _DEFAULT_INITIAL_BACKOFF,
+    ) -> None:
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+        if initial_backoff <= 0:
+            raise ValueError("initial_backoff must be > 0")
+
+        timeout = httpx.Timeout(request_timeout, connect=connect_timeout)
+        self._max_retries = max_retries
+        self._initial_backoff = initial_backoff
+
+        if token is not None:
+            self.api: AuthenticatedClient = AuthenticatedClient(
+                base_url=base_url,
+                token=token,
+                timeout=timeout,
+            )
+        else:
+            # mypy: AuthenticatedClient and Client share most of their surface
+            # but are technically distinct types. Users who construct without
+            # a token can only call endpoints that don't require auth.
+            self.api = Client(base_url=base_url, timeout=timeout)  # type: ignore[assignment]
+
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries
+
+    @property
+    def initial_backoff(self) -> float:
+        return self._initial_backoff
+
+    async def retry(self, op: Callable[[Any], Awaitable[T]]) -> T:
+        """Run ``op(client)`` with exponential backoff on retryable failures.
+
+        ``op`` is an async callable that takes the generated client
+        (``self.api``) and returns the operation's result. The closure form
+        keeps the wrapper free of per-endpoint glue while letting callers
+        decide which operations are safe to retry. Non-idempotent POSTs
+        should generally **not** be wrapped.
+
+        Retry classification matches the Rust wrapper: transport errors
+        and HTTP 408/429/502/503/504 qualify. Other 4xx/5xx responses
+        return immediately on the first failure.
+        """
+        attempt = 0
+        while True:
+            try:
+                result = await op(self.api)
+            except httpx.HTTPError as exc:
+                err = BrokkrError.from_transport(exc)
+                if not err.is_retryable() or attempt >= self._max_retries:
+                    raise err from exc
+            else:
+                if isinstance(result, ErrorResponse):
+                    # The generator folds documented errors into return
+                    # unions; we surface them as raises here. We don't know
+                    # the status code in this codepath — the *_detailed
+                    # variants carry it. Callers wanting status-aware retry
+                    # should use those and convert manually.
+                    err = BrokkrError.from_response(result, status=500)
+                    if not err.is_retryable() or attempt >= self._max_retries:
+                        raise err
+                else:
+                    return result
+
+            backoff = min(self._initial_backoff * (2**attempt), _MAX_BACKOFF)
+            await asyncio.sleep(backoff)
+            attempt += 1

brokkr_client-0.3.0/brokkr/errors.py

@@ -0,0 +1,62 @@
+"""Typed error wrapper for the Brokkr SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from brokkr_broker_client.models import ErrorResponse
+
+# HTTP status codes worth retrying — transient failures only. Mirrors the
+# Rust wrapper's `is_retryable_status` set.
+_RETRYABLE_STATUSES: frozenset[int] = frozenset({408, 429, 502, 503, 504})
+
+
+@dataclass
+class BrokkrError(Exception):
+    """Single exception type surfaced by the wrapper.
+
+    Carries the typed `ErrorResponse` body when the broker returned a
+    documented 4xx/5xx, and a status code when one is known. Callers
+    pattern-match on `code` (machine-readable, stable across versions)
+    rather than `message` (human-readable, not stable).
+    """
+
+    message: str
+    code: Optional[str] = None
+    status: Optional[int] = None
+    response: Optional[ErrorResponse] = None
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def __str__(self) -> str:  # pragma: no cover - dataclass repr is fine
+        if self.status is not None and self.code is not None:
+            return f"{self.status} {self.code}: {self.message}"
+        if self.code is not None:
+            return f"{self.code}: {self.message}"
+        return self.message
+
+    def is_retryable(self) -> bool:
+        """Whether this error qualifies for the wrapper's retry helper."""
+        if self.status is None:
+            # Transport / unknown errors are retryable by default.
+            return True
+        return self.status in _RETRYABLE_STATUSES
+
+    @classmethod
+    def from_response(cls, body: ErrorResponse, status: int) -> "BrokkrError":
+        """Build from a generated `ErrorResponse` returned in an operation
+        union (rather than raised). The generator folds documented errors
+        into the return type union; the wrapper converts them to raises."""
+        return cls(
+            message=body.message,
+            code=body.code,
+            status=status,
+            response=body,
+        )
+
+    @classmethod
+    def from_transport(cls, exc: BaseException) -> "BrokkrError":
+        """Wrap an httpx / network exception."""
+        return cls(message=str(exc), code=None, status=None, response=None)

brokkr_client-0.3.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "brokkr-client"
+version = "0.3.0"
+description = "Ergonomic Python wrapper around the auto-generated brokkr-client-generated low-level client"
+authors = []
+requires-python = ">=3.10"
+readme = "README.md"
+dependencies = [
+    # Low-level generated client. Local path dep in-tree; resolved from PyPI
+    # for installed releases.
+    "brokkr-client-generated",
+    "httpx>=0.23.0,<0.29.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[tool.uv.sources]
+brokkr-client-generated = { path = "../brokkr-client" }
+
+[tool.uv.build-backend]
+module-name = "brokkr"
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"