pulp-engine 0.85.0__py3-none-any.whl

pulp_engine/__init__.py

@@ -0,0 +1,48 @@
+"""Pulp Engine Python SDK — typed client for the Pulp Engine document generation API.
+
+Example::
+
+    from pulp_engine import PulpEngineClient
+
+    with PulpEngineClient(
+        base_url="https://pulp-engine.example.com", api_key="dk_admin_..."
+    ) as client:
+        result = client.render.pdf("invoice", {"amount": 100})
+        result.save("invoice.pdf")
+"""
+
+from .client import PulpEngineClient
+from .errors import PulpEngineError, PulpEngineTimeoutError, ValidationIssue
+from .pagination import PaginatedResult, paginate
+from .resources.render import BinaryResult, DryRunFormat, PptxResult
+from .types import (
+    DryRunExpressionError,
+    DryRunExpressionLocation,
+    DryRunExpressionsSection,
+    DryRunExpressionSuggestion,
+    DryRunResult,
+    DryRunValidationError,
+    DryRunValidationSection,
+)
+
+__version__ = "0.60.0"
+
+__all__ = [
+    "PulpEngineClient",
+    "PulpEngineError",
+    "PulpEngineTimeoutError",
+    "ValidationIssue",
+    "PaginatedResult",
+    "paginate",
+    "BinaryResult",
+    "PptxResult",
+    "DryRunFormat",
+    "DryRunResult",
+    "DryRunExpressionError",
+    "DryRunExpressionLocation",
+    "DryRunExpressionSuggestion",
+    "DryRunValidationError",
+    "DryRunValidationSection",
+    "DryRunExpressionsSection",
+    "__version__",
+]

pulp_engine/_http.py

@@ -0,0 +1,230 @@
+"""Internal HTTP wrapper around httpx with auth header injection and error mapping."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import build_error
+
+
+class HttpClient:
+    """Thin wrapper around ``httpx.Client`` that handles auth headers and error mapping.
+
+    Used internally by all resource classes. Not part of the public API.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        editor_token: str | None = None,
+        timeout: float = 60.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._headers: dict[str, str] = {}
+        if api_key:
+            self._headers["X-Api-Key"] = api_key
+        elif editor_token:
+            self._headers["X-Editor-Token"] = editor_token
+
+        client_kwargs: dict[str, Any] = {
+            "base_url": self._base_url,
+            "headers": self._headers,
+            "timeout": timeout,
+        }
+        if transport is not None:
+            client_kwargs["transport"] = transport
+
+        self._client = httpx.Client(**client_kwargs)
+
+    def set_api_key(self, api_key: str) -> None:
+        """Switch to API key authentication at runtime."""
+        self._headers.pop("X-Editor-Token", None)
+        self._headers["X-Api-Key"] = api_key
+        self._client.headers["X-Api-Key"] = api_key
+        self._client.headers.pop("X-Editor-Token", None)
+
+    def set_editor_token(self, token: str) -> None:
+        """Switch to editor token authentication at runtime."""
+        self._headers.pop("X-Api-Key", None)
+        self._headers["X-Editor-Token"] = token
+        self._client.headers["X-Editor-Token"] = token
+        self._client.headers.pop("X-Api-Key", None)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        self.close()
+
+    # ── Request helpers ───────────────────────────────────────────────────
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Issue an HTTP request and parse the response as JSON.
+
+        Raises ``PulpEngineError`` on non-2xx responses.
+        """
+        response = self._client.request(
+            method,
+            path,
+            params=_clean_params(params),
+            json=json,
+            headers=headers,
+        )
+        if not response.is_success:
+            raise build_error(response.status_code, _parse_error_body(response))
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> tuple[bytes, httpx.Headers]:
+        """Issue an HTTP request and return the raw response body as bytes.
+
+        Returns ``(body, response_headers)`` so callers can read headers like
+        ``Content-Disposition`` or ``X-Render-Warnings``.
+        """
+        response = self._client.request(
+            method,
+            path,
+            params=_clean_params(params),
+            json=json,
+        )
+        if not response.is_success:
+            raise build_error(response.status_code, _parse_error_body(response))
+        return response.content, response.headers
+
+    def request_text(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> str:
+        """Issue an HTTP request and return the response body as a string."""
+        response = self._client.request(
+            method,
+            path,
+            params=_clean_params(params),
+            json=json,
+        )
+        if not response.is_success:
+            raise build_error(response.status_code, _parse_error_body(response))
+        return response.text
+
+    def stream_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Issue an HTTP request and return a context manager yielding the raw
+        streaming response.
+
+        The caller iterates ``response.iter_bytes()`` (or ``iter_lines()``)
+        inside the ``with`` block. Used by streaming endpoints so large bodies
+        are not buffered in memory.
+
+        Error responses are decoded eagerly and raised before the caller
+        receives the context manager; the stream is only entered on 2xx.
+
+        The optional ``headers`` argument merges per-request headers on top of
+        the client's base auth headers — used by NDJSON streaming endpoints to
+        pass ``Accept: application/x-ndjson``.
+        """
+        response = self._client.stream(
+            method,
+            path,
+            params=_clean_params(params),
+            json=json,
+            headers=headers,
+        )
+        # httpx.Client.stream returns a context manager; we need to enter it,
+        # check for a non-2xx, and either re-raise or hand the live stream back
+        # to the caller. Because closing the context aborts the request, we
+        # return a thin wrapper that closes only on __exit__.
+        return _StreamContext(response, self)
+
+    def request_multipart(
+        self,
+        method: str,
+        path: str,
+        *,
+        files: dict[str, Any],
+    ) -> Any:
+        """Issue a multipart/form-data request and parse the JSON response."""
+        response = self._client.request(method, path, files=files)
+        if not response.is_success:
+            raise build_error(response.status_code, _parse_error_body(response))
+        return response.json()
+
+
+class _StreamContext:
+    """Context manager returned by :meth:`HttpClient.stream_bytes`.
+
+    On ``__enter__`` the underlying httpx streaming request is opened and the
+    status code is checked. Non-2xx responses raise ``PulpEngineError`` eagerly
+    (the error body is read in full). On success, ``iter_bytes()`` /
+    ``iter_raw()`` on the returned ``httpx.Response`` yield chunks as they
+    arrive. ``__exit__`` closes the underlying connection — always call from a
+    ``with`` block or ``close()`` explicitly, otherwise the connection leaks.
+    """
+
+    def __init__(self, cm: Any, http: HttpClient) -> None:
+        self._cm = cm
+        self._http = http
+        self._response: Any = None
+
+    def __enter__(self) -> Any:
+        response = self._cm.__enter__()
+        if not response.is_success:
+            # Read the error body before exiting the stream context.
+            response.read()
+            error = build_error(response.status_code, _parse_error_body(response))
+            self._cm.__exit__(None, None, None)
+            raise error
+        self._response = response
+        return response
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self._cm.__exit__(exc_type, exc, tb)
+
+
+def _clean_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Strip ``None`` values from query params so they aren't sent as ``?key=None``."""
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _parse_error_body(response: httpx.Response) -> Any:
+    """Try to parse the error response body as JSON, falling back to text."""
+    try:
+        return response.json()
+    except Exception:
+        return response.text or None

pulp_engine/client.py

@@ -0,0 +1,96 @@
+"""PulpEngineClient — main entry point for the Pulp Engine Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._http import HttpClient
+from .resources import (
+    AdminResource,
+    AssetsResource,
+    AuditEventsResource,
+    AuthResource,
+    BatchResource,
+    HealthResource,
+    PdfTransformResource,
+    RenderResource,
+    SchedulesResource,
+    TemplatesResource,
+)
+
+
+class PulpEngineClient:
+    """Typed Python client for the Pulp Engine API.
+
+    Mirrors the resource layout of the TypeScript SDK 1:1, with snake_case
+    method names. Supports both API key auth (``X-Api-Key`` header) and
+    editor session token auth (``X-Editor-Token`` header).
+
+    Example::
+
+        from pulp_engine import PulpEngineClient
+
+        with PulpEngineClient(
+            base_url="https://pulp-engine.example.com", api_key="dk_admin_..."
+        ) as client:
+            templates = client.templates.list()
+            result = client.render.pdf("invoice", {"amount": 100})
+            result.save("invoice.pdf")
+
+    Args:
+        base_url: Base URL of the Pulp Engine API.
+        api_key: Scoped API key. Sent as ``X-Api-Key`` header.
+        editor_token: Editor session token. Mutually exclusive with ``api_key``.
+        timeout: Per-request timeout in seconds. Defaults to 60s.
+        transport: Optional custom httpx transport (useful for testing with
+            ``httpx.MockTransport``).
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        editor_token: str | None = None,
+        timeout: float = 60.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._http = HttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            editor_token=editor_token,
+            timeout=timeout,
+            transport=transport,
+        )
+
+        self.templates = TemplatesResource(self._http)
+        self.render = RenderResource(self._http)
+        self.batch = BatchResource(self._http)
+        self.pdf_transform = PdfTransformResource(self._http)
+        self.assets = AssetsResource(self._http)
+        self.audit_events = AuditEventsResource(self._http)
+        self.admin = AdminResource(self._http)
+        self.auth = AuthResource(self._http)
+        self.health = HealthResource(self._http)
+        self.schedules = SchedulesResource(self._http)
+
+    def set_api_key(self, api_key: str) -> None:
+        """Switch to API key authentication at runtime."""
+        self._http.set_api_key(api_key)
+
+    def set_editor_token(self, token: str) -> None:
+        """Switch to editor token authentication at runtime (e.g. after calling
+        ``client.auth.editor_token()``)."""
+        self._http.set_editor_token(token)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release connections."""
+        self._http.close()
+
+    def __enter__(self) -> PulpEngineClient:
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        self.close()

pulp_engine/errors.py

@@ -0,0 +1,142 @@
+"""Structured error raised by all SDK methods on non-2xx responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    """A single field-level validation issue from a 400/422 response."""
+
+    path: str
+    message: str
+    code: str | None = None
+
+
+class PulpEngineError(Exception):
+    """Base error raised by all SDK methods when the API returns a non-2xx response.
+
+    Mirrors the TypeScript SDK's ``PulpEngineError``. Preserves the full error
+    shape from the API, including the ``code`` discriminant from
+    render/validation errors and the ``request_id`` (v0.78.0+) for correlating
+    client errors with server log entries.
+
+    Consumers can catch all SDK errors (including subclasses like
+    :class:`PulpEngineTimeoutError`) with a single ``except PulpEngineError:``.
+
+    Attributes:
+        status: HTTP status code (e.g. 400, 401, 404, 422). ``0`` for client-side
+            errors like timeouts where no HTTP response was received.
+        error: API error type string (e.g. ``"RenderError"``, ``"ValidationError"``).
+        code: Machine-readable error code from the canonical registry (e.g.
+            ``"template_expression_error"``, ``"render_timeout"``,
+            ``"asset_blocked"``, ``"not_found"``). Required on every
+            v0.78.0+ envelope; ``None`` only for unstructured bodies (e.g.
+            upstream LB intercept) or pre-v0.78.0 servers.
+        request_id: Server-generated request id (UUID). Mirrors the
+            ``X-Request-ID`` response header — pass this when filing a
+            support ticket and the server log entry can be located. ``None``
+            for unstructured bodies and pre-v0.78.0 servers.
+        issues: Field-level validation issues. ``None`` for non-validation errors.
+    """
+
+    status: int
+    error: str
+    code: str | None
+    request_id: str | None
+    issues: list[ValidationIssue] | None
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        error: str,
+        message: str,
+        code: str | None = None,
+        request_id: str | None = None,
+        issues: list[ValidationIssue] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.error = error
+        self.code = code
+        self.request_id = request_id
+        self.issues = issues
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status={self.status}, error={self.error!r}, "
+            f"code={self.code!r}, request_id={self.request_id!r}, "
+            f"message={str(self)!r})"
+        )
+
+
+class PulpEngineTimeoutError(PulpEngineError):
+    """Raised when a client-side wait operation exceeds its timeout.
+
+    Currently raised by :meth:`BatchResource.wait_for_job` when an async batch
+    job does not reach a terminal state within the configured timeout. This is
+    a client-side timeout — the server may still complete the job after this
+    error is raised.
+
+    Subclass of :class:`PulpEngineError` so consumers can catch all SDK errors
+    with a single ``except PulpEngineError:``.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            status=0,
+            error="ClientTimeout",
+            message=message,
+            code="client_timeout",
+        )
+
+
+def build_error(status: int, body: Any) -> PulpEngineError:
+    """Build a ``PulpEngineError`` from an HTTP status and parsed JSON body.
+
+    Handles all four API error shapes (ErrorResponse, ValidationErrorResponse,
+    RateLimitErrorResponse, RenderErrorResponse) and falls back to a generic
+    shape for unstructured bodies. The v0.78.0+ ``code`` and ``requestId``
+    fields are surfaced as ``code`` and ``request_id`` respectively (Python
+    snake_case convention; the wire field stays ``requestId``).
+    """
+    if isinstance(body, dict):
+        error_str = body.get("error") if isinstance(body.get("error"), str) else "UnknownError"
+        message = body.get("message") if isinstance(body.get("message"), str) else f"HTTP {status}"
+        code = body.get("code") if isinstance(body.get("code"), str) else None
+        request_id = body.get("requestId") if isinstance(body.get("requestId"), str) else None
+
+        issues_raw = body.get("issues")
+        issues: list[ValidationIssue] | None = None
+        if isinstance(issues_raw, list):
+            issues = []
+            for item in issues_raw:
+                if isinstance(item, dict):
+                    issues.append(
+                        ValidationIssue(
+                            path=str(item.get("path", "")),
+                            message=str(item.get("message", "")),
+                            code=item.get("code") if isinstance(item.get("code"), str) else None,
+                        )
+                    )
+
+        return PulpEngineError(
+            status=status,
+            error=error_str or "UnknownError",
+            message=message or f"HTTP {status}",
+            code=code,
+            request_id=request_id,
+            issues=issues,
+        )
+
+    return PulpEngineError(
+        status=status,
+        error="UnknownError",
+        message=f"HTTP {status}",
+        code=None,
+        request_id=None,
+        issues=None,
+    )

pulp_engine/pagination.py

@@ -0,0 +1,51 @@
+"""Pagination helpers mirroring the TS SDK's PaginatedResult envelope."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class PaginatedResult(Generic[T]):
+    """Standard paginated envelope returned by all list endpoints."""
+
+    items: list[T]
+    total: int
+    limit: int
+    offset: int
+
+
+def paginate(
+    fetch_page: Callable[[int, int], PaginatedResult[T]],
+    *,
+    limit: int = 50,
+) -> Iterator[T]:
+    """Auto-paginate through all pages of a list endpoint.
+
+    Yields individual items, fetching the next page when the current one is
+    exhausted.
+
+    The ``fetch_page`` callback receives ``(limit, offset)`` in that order, so
+    SDK list methods (which take ``limit, offset`` as keyword args) can be
+    passed directly without re-routing.
+
+    Example::
+
+        from pulp_engine import paginate
+
+        for template in paginate(
+            lambda limit, offset: client.templates.list(limit=limit, offset=offset),
+        ):
+            print(template.key)
+    """
+    offset = 0
+    while True:
+        page = fetch_page(limit, offset)
+        yield from page.items
+        offset += limit
+        if offset >= page.total:
+            break

pulp_engine/resources/__init__.py

@@ -0,0 +1,25 @@
+"""Resource modules — one per API surface area, mirroring the TypeScript SDK 1:1."""
+
+from .admin import AdminResource
+from .assets import AssetsResource
+from .audit_events import AuditEventsResource
+from .auth import AuthResource
+from .batch import BatchResource
+from .health import HealthResource
+from .pdf_transform import PdfTransformResource
+from .render import RenderResource
+from .schedules import SchedulesResource
+from .templates import TemplatesResource
+
+__all__ = [
+    "AdminResource",
+    "AssetsResource",
+    "AuditEventsResource",
+    "AuthResource",
+    "BatchResource",
+    "HealthResource",
+    "PdfTransformResource",
+    "RenderResource",
+    "SchedulesResource",
+    "TemplatesResource",
+]

pulp_engine/resources/admin.py

@@ -0,0 +1,71 @@
+"""Admin resource — named user management."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from .._http import HttpClient
+from ..types import UserRecord
+
+
+class AdminResource:
+    """Admin operations for named user management."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list_users(self) -> list[UserRecord]:
+        """List all named users. Admin only."""
+        body = self._http.request_json("GET", "/admin/users/")
+        return [UserRecord.model_validate(u) for u in body["users"]]
+
+    def create_user(
+        self,
+        *,
+        id: str,
+        display_name: str,
+        key: str,
+        role: Literal["editor", "admin"],
+    ) -> UserRecord:
+        """Create a new named user. Admin only."""
+        body = self._http.request_json(
+            "POST",
+            "/admin/users/",
+            json={"id": id, "displayName": display_name, "key": key, "role": role},
+        )
+        return UserRecord.model_validate(body)
+
+    def update_user(
+        self,
+        id: str,
+        *,
+        display_name: str | None = None,
+        key: str | None = None,
+        role: Literal["editor", "admin"] | None = None,
+    ) -> UserRecord:
+        """Update an existing named user. Admin only."""
+        updates: dict[str, str] = {}
+        if display_name is not None:
+            updates["displayName"] = display_name
+        if key is not None:
+            updates["key"] = key
+        if role is not None:
+            updates["role"] = role
+        body = self._http.request_json("PUT", f"/admin/users/{id}", json=updates)
+        return UserRecord.model_validate(body)
+
+    def delete_user(self, id: str) -> dict[str, int | bool]:
+        """Delete a named user. Admin only.
+
+        Returns ``{"deleted": bool, "registrySize": int}``.
+        """
+        body = self._http.request_json("DELETE", f"/admin/users/{id}")
+        return body  # type: ignore[no-any-return]
+
+    def reload_users(self) -> dict[str, int | bool]:
+        """Reload the user registry from the file source. Admin only.
+
+        Returns ``{"reloaded": bool, "count": int}``.
+        """
+        body = self._http.request_json("POST", "/admin/users/reload")
+        return body  # type: ignore[no-any-return]