pulp-engine 0.85.0__py3-none-any.whl

pulp_engine/resources/assets.py

@@ -0,0 +1,68 @@
+"""Assets resource — upload, list, delete image assets."""
+
+from __future__ import annotations
+
+from .._http import HttpClient
+from ..pagination import PaginatedResult
+from ..types import AssetRecord
+
+
+class AssetsResource:
+    """Image asset management."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        q: str | None = None,
+        mime_type: str | None = None,
+        legacy_svg: bool | None = None,
+    ) -> PaginatedResult[AssetRecord]:
+        """List assets (paginated, with optional filters)."""
+        body = self._http.request_json(
+            "GET",
+            "/assets/",
+            params={
+                "limit": limit,
+                "offset": offset,
+                "q": q,
+                "mimeType": mime_type,
+                "legacySvg": legacy_svg,
+            },
+        )
+        return PaginatedResult(
+            items=[AssetRecord.model_validate(item) for item in body["items"]],
+            total=body["total"],
+            limit=body["limit"],
+            offset=body["offset"],
+        )
+
+    def upload(
+        self,
+        file: bytes,
+        filename: str,
+        *,
+        content_type: str = "application/octet-stream",
+    ) -> AssetRecord:
+        """Upload an image asset.
+
+        Args:
+            file: The raw file bytes.
+            filename: Original filename — used for extension detection and storage.
+            content_type: MIME type. Defaults to ``application/octet-stream``;
+                pass the actual type (e.g. ``"image/png"``) when known.
+        """
+        body = self._http.request_multipart(
+            "POST",
+            "/assets/upload",
+            files={"file": (filename, file, content_type)},
+        )
+        return AssetRecord.model_validate(body)
+
+    def delete(self, id: str) -> None:
+        """Delete an asset by ID."""
+        self._http.request_json("DELETE", f"/assets/{id}")

pulp_engine/resources/audit_events.py

@@ -0,0 +1,62 @@
+"""Audit events resource — query and purge audit history."""
+
+from __future__ import annotations
+
+from .._http import HttpClient
+from ..pagination import PaginatedResult
+from ..types import AuditEvent
+
+
+class AuditEventsResource:
+    """Query and purge audit event history."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        event: str | None = None,
+        operation: str | None = None,
+        actor: str | None = None,
+        resource_type: str | None = None,
+        resource_id: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> PaginatedResult[AuditEvent]:
+        """List audit events (paginated, with optional filters). Admin only."""
+        body = self._http.request_json(
+            "GET",
+            "/audit-events/",
+            params={
+                "limit": limit,
+                "offset": offset,
+                "event": event,
+                "operation": operation,
+                "actor": actor,
+                "resourceType": resource_type,
+                "resourceId": resource_id,
+                "since": since,
+                "until": until,
+            },
+        )
+        return PaginatedResult(
+            items=[AuditEvent.model_validate(item) for item in body["items"]],
+            total=body["total"],
+            limit=body["limit"],
+            offset=body["offset"],
+        )
+
+    def purge(self, before: str) -> dict[str, int]:
+        """Purge audit events older than the given ISO-8601 timestamp. Admin only.
+
+        Returns ``{"deleted": int}``.
+        """
+        body = self._http.request_json(
+            "DELETE",
+            "/audit-events/",
+            params={"before": before},
+        )
+        return body  # type: ignore[no-any-return]

pulp_engine/resources/auth.py

@@ -0,0 +1,26 @@
+"""Auth resource — auth status and editor token exchange."""
+
+from __future__ import annotations
+
+from .._http import HttpClient
+from ..types import AuthStatus, EditorTokenResponse
+
+
+class AuthResource:
+    """Authentication status and editor token exchange."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def status(self) -> AuthStatus:
+        """Check authentication status and capabilities (public, no auth required)."""
+        body = self._http.request_json("GET", "/auth/status")
+        return AuthStatus.model_validate(body)
+
+    def editor_token(self, key: str, *, actor: str | None = None) -> EditorTokenResponse:
+        """Exchange an API key for a short-lived editor session token (public endpoint)."""
+        request_body: dict[str, str] = {"key": key}
+        if actor is not None:
+            request_body["actor"] = actor
+        body = self._http.request_json("POST", "/auth/editor-token", json=request_body)
+        return EditorTokenResponse.model_validate(body)

pulp_engine/resources/batch.py

@@ -0,0 +1,146 @@
+"""Batch render resource — sync and async batch jobs."""
+
+from __future__ import annotations
+
+import json as _json
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from .._http import HttpClient
+from ..errors import PulpEngineTimeoutError
+from ..types import AsyncJobAccepted, AsyncJobStatus, BatchResult
+
+
+class BatchResource:
+    """Synchronous and asynchronous batch rendering."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def pdf(self, items: list[dict[str, Any]]) -> BatchResult:
+        """Synchronous batch render to PDF."""
+        body = self._http.request_json("POST", "/render/batch", json={"items": items})
+        return BatchResult.model_validate(body)
+
+    @contextmanager
+    def pdf_stream(self, items: list[dict[str, Any]]) -> Iterator[Iterator[dict[str, Any]]]:
+        """Synchronous batch render to PDF, streamed as NDJSON.
+
+        Yields an iterator of parsed NDJSON lines. ``result`` lines arrive in
+        **completion order** (fastest items first, regardless of input order —
+        use ``line["index"]`` to map back). The iteration ends with a single
+        ``summary`` line carrying authoritative totals.
+
+        Error contract: 4xx/5xx responses are decoded eagerly and raised as
+        :class:`PulpEngineError` before the context manager enters. Mid-stream
+        transport failures raise ``httpx.StreamError`` during iteration. A
+        truncated stream (no final ``summary`` line) signals the batch was
+        interrupted.
+
+        Example::
+
+            with client.batch.pdf_stream(items) as lines:
+                for line in lines:
+                    if line["type"] == "result" and line["success"]:
+                        save_to_disk(line["index"], line["pdf"])
+                    elif line["type"] == "summary":
+                        print(f"{line['succeeded']}/{line['total']} succeeded")
+        """
+        cm = self._http.stream_bytes(
+            "POST",
+            "/render/batch",
+            json={"items": items},
+            headers={"Accept": "application/x-ndjson"},
+        )
+        with cm as response:
+            saw_summary = [False]  # boxed so the inner generator can mutate
+
+            def _iter_lines() -> Iterator[dict[str, Any]]:
+                for raw_line in response.iter_lines():
+                    if not raw_line:
+                        continue
+                    parsed = _json.loads(raw_line)
+                    if isinstance(parsed, dict) and parsed.get("type") == "summary":
+                        saw_summary[0] = True
+                    yield parsed
+                # End-of-stream guard. Server contract is: always emit a
+                # trailing `summary` line before closing. Missing summary
+                # signals the batch was interrupted — either by proxy
+                # truncation on a line boundary, server crash, or transport
+                # failure between the last result and the summary. Raise
+                # so consumers cannot mistake a partial stream for a
+                # complete one.
+                if not saw_summary[0]:
+                    raise RuntimeError(
+                        "pdf_stream: stream ended without a summary line — batch was interrupted"
+                    )
+
+            yield _iter_lines()
+
+    def docx(self, items: list[dict[str, Any]]) -> BatchResult:
+        """Synchronous batch render to DOCX."""
+        body = self._http.request_json("POST", "/render/batch/docx", json={"items": items})
+        return BatchResult.model_validate(body)
+
+    def submit_async(
+        self,
+        items: list[dict[str, Any]],
+        webhook_url: str,
+        webhook_secret: str,
+    ) -> AsyncJobAccepted:
+        """Submit an async PDF batch render with webhook callback. Returns 202 with job metadata."""
+        body = self._http.request_json(
+            "POST",
+            "/render/batch/async",
+            json={
+                "items": items,
+                "webhookUrl": webhook_url,
+                "webhookSecret": webhook_secret,
+            },
+        )
+        return AsyncJobAccepted.model_validate(body)
+
+    def submit_async_docx(
+        self,
+        items: list[dict[str, Any]],
+        webhook_url: str,
+        webhook_secret: str,
+    ) -> AsyncJobAccepted:
+        """Submit an async DOCX batch render with webhook callback. Returns 202."""
+        body = self._http.request_json(
+            "POST",
+            "/render/batch/async/docx",
+            json={
+                "items": items,
+                "webhookUrl": webhook_url,
+                "webhookSecret": webhook_secret,
+            },
+        )
+        return AsyncJobAccepted.model_validate(body)
+
+    def poll_job(self, job_id: str) -> AsyncJobStatus:
+        """Poll the status of an async batch job."""
+        body = self._http.request_json("GET", f"/render/batch/jobs/{job_id}")
+        return AsyncJobStatus.model_validate(body)
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval_s: float = 2.0,
+        timeout_s: float = 300.0,
+    ) -> AsyncJobStatus:
+        """Wait for an async batch job to complete, polling at a fixed interval.
+
+        Returns when the job reaches ``completed`` or ``failed`` status.
+        Raises :class:`PulpEngineTimeoutError` if the timeout is exceeded.
+        """
+        start = time.monotonic()
+        while time.monotonic() - start < timeout_s:
+            job = self.poll_job(job_id)
+            if job.status in ("completed", "failed"):
+                return job
+            time.sleep(poll_interval_s)
+        raise PulpEngineTimeoutError(f"Batch job {job_id} timed out after {timeout_s}s")

pulp_engine/resources/health.py

@@ -0,0 +1,23 @@
+"""Health resource — liveness and readiness probes."""
+
+from __future__ import annotations
+
+from .._http import HttpClient
+from ..types import HealthResponse, ReadinessResponse
+
+
+class HealthResource:
+    """Liveness and readiness probes."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def liveness(self) -> HealthResponse:
+        """Liveness probe — always 200 if the process is up."""
+        body = self._http.request_json("GET", "/health")
+        return HealthResponse.model_validate(body)
+
+    def readiness(self) -> ReadinessResponse:
+        """Readiness probe — 503 if storage is unreachable."""
+        body = self._http.request_json("GET", "/health/ready")
+        return ReadinessResponse.model_validate(body)

pulp_engine/resources/pdf_transform.py

@@ -0,0 +1,89 @@
+"""PDF transform resource — merge, watermark, insert."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import HttpClient
+from .render import BinaryResult
+
+
+class PdfTransformResource:
+    """PDF post-processing operations: merge, watermark, insert pages.
+
+    All methods return :class:`BinaryResult` so callers can use the same
+    ``.save(path)`` helper as the render endpoints.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def merge(
+        self,
+        sources: list[dict[str, str]],
+        *,
+        metadata: dict[str, str] | None = None,
+    ) -> BinaryResult:
+        """Merge multiple PDFs into one.
+
+        Args:
+            sources: List of ``{"data": <base64-encoded PDF>}`` dicts.
+            metadata: Optional ``{"title", "author", "subject"}`` for the output PDF.
+        """
+        body: dict[str, Any] = {"sources": sources}
+        if metadata is not None:
+            body["metadata"] = metadata
+        content, headers = self._http.request_bytes("POST", "/render/pdf/merge", json=body)
+        return BinaryResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+        )
+
+    def watermark(
+        self,
+        pdf: str,
+        watermark: dict[str, Any],
+        *,
+        page_range: dict[str, int] | None = None,
+    ) -> BinaryResult:
+        """Apply a text or image watermark to a PDF.
+
+        Args:
+            pdf: Base64-encoded source PDF.
+            watermark: Watermark spec — see API docs for the full shape.
+            page_range: Optional ``{"start": int, "end": int}`` to limit pages.
+        """
+        body: dict[str, Any] = {"pdf": pdf, "watermark": watermark}
+        if page_range is not None:
+            body["pageRange"] = page_range
+        content, headers = self._http.request_bytes("POST", "/render/pdf/watermark", json=body)
+        return BinaryResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+        )
+
+    def insert(
+        self,
+        target: str,
+        insert: str,
+        position: dict[str, Any],
+    ) -> BinaryResult:
+        """Insert pages from one PDF into another.
+
+        Args:
+            target: Base64-encoded target PDF.
+            insert: Base64-encoded PDF to insert.
+            position: ``{"at": "start"|"end"|"before"|"after", "page": int}``.
+        """
+        content, headers = self._http.request_bytes(
+            "POST",
+            "/render/pdf/insert",
+            json={"target": target, "insert": insert, "position": position},
+        )
+        return BinaryResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+        )