pulp-engine 0.85.0__py3-none-any.whl

pulp_engine/resources/render.py

@@ -0,0 +1,309 @@
+"""Render resource — PDF, HTML, CSV, XLSX, DOCX, PPTX."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from .._http import HttpClient
+from ..types import DryRunResult
+
+# Format selector for RenderResource.dry_run() — selects which per-format
+# route to hit. The result shape is identical regardless of format; the
+# selector only affects which route is queried (matters when different
+# formats have different rate limits or feature gates server-side).
+DryRunFormat = Literal["pdf", "html", "csv", "xlsx", "docx", "pptx"]
+
+_DRY_RUN_PATHS: dict[str, str] = {
+    "pdf": "/render/pdf",
+    "html": "/render/html",
+    "csv": "/render/csv",
+    "xlsx": "/render/xlsx",
+    "docx": "/render/docx",
+    "pptx": "/render/pptx",
+}
+
+
+@dataclass
+class BinaryResult:
+    """Raw binary render result with response metadata.
+
+    Provides a ``save()`` convenience method for writing the bytes to a file.
+    """
+
+    data: bytes
+    content_type: str | None
+    content_disposition: str | None
+
+    def save(self, path: str | Path) -> Path:
+        """Write the binary data to ``path`` and return the resolved path."""
+        out = Path(path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_bytes(self.data)
+        return out
+
+
+@dataclass
+class PptxResult(BinaryResult):
+    """PPTX render result with structured warning count.
+
+    ``warning_count`` is parsed from the ``X-Render-Warnings: count=N`` header.
+    Common warning sources: known-dimension overflow, mixed-mark bullet collapse
+    in richText, totalPages marker drop in header/footer.
+    """
+
+    warning_count: int = 0
+
+
+def _build_render_body(
+    template: str,
+    data: dict[str, Any],
+    *,
+    version: str | None,
+    options: dict[str, Any] | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"template": template, "data": data}
+    if version is not None:
+        body["version"] = version
+    if options is not None:
+        body["options"] = options
+    return body
+
+
+def _parse_warning_count(header_value: str | None) -> int:
+    if not header_value:
+        return 0
+    match = re.search(r"count=(\d+)", header_value)
+    if not match:
+        return 0
+    try:
+        return int(match.group(1))
+    except ValueError:
+        return 0
+
+
+class RenderResource:
+    """Render templates to various output formats."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def pdf(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> BinaryResult:
+        """Render a template to PDF. Returns raw binary."""
+        body = _build_render_body(template, data, version=version, options=options)
+        content, headers = self._http.request_bytes("POST", "/render/pdf", json=body)
+        return BinaryResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+        )
+
+    def pdf_stream(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+        stream: Literal["auto", "force", "off"] = "auto",
+    ) -> Any:
+        """Render a template to PDF and stream the response body.
+
+        Returns a context manager yielding an ``httpx.Response``; iterate
+        ``response.iter_bytes()`` inside the ``with`` block to consume chunks
+        as they arrive.
+
+        ``stream="force"`` passes ``?stream=true`` so incompatible post-render
+        hook registrations surface as a 400 error up front instead of silently
+        falling back to buffered. ``stream="off"`` passes ``?stream=false`` to
+        force a buffered response (useful behind proxies that mangle chunked
+        encoding). ``stream="auto"`` (default) lets the server choose based on
+        whether hooks are registered.
+
+        Error contract: the streamed body may be truncated on mid-stream
+        failure. ``httpx`` raises a transport error when that happens; clients
+        must treat the bytes received before the error as possibly-incomplete
+        rather than relying on PDF EOF-sniffing.
+
+        Example::
+
+            with client.render.pdf_stream("big-report", data) as response:
+                with open("out.pdf", "wb") as f:
+                    for chunk in response.iter_bytes():
+                        f.write(chunk)
+        """
+        body = _build_render_body(template, data, version=version, options=options)
+        params: dict[str, Any] = {}
+        if stream == "force":
+            params["stream"] = "true"
+        elif stream == "off":
+            params["stream"] = "false"
+        return self._http.stream_bytes("POST", "/render/pdf", json=body, params=params or None)
+
+    def html(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> str:
+        """Render a template to HTML. Returns the HTML string."""
+        body = _build_render_body(template, data, version=version, options=options)
+        return self._http.request_text("POST", "/render/html", json=body)
+
+    def csv(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> BinaryResult:
+        """Render a template to CSV. Returns raw binary."""
+        body = _build_render_body(template, data, version=version, options=options)
+        content, headers = self._http.request_bytes("POST", "/render/csv", json=body)
+        return BinaryResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+        )
+
+    def xlsx(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> BinaryResult:
+        """Render a template to XLSX. Returns raw binary."""
+        body = _build_render_body(template, data, version=version, options=options)
+        content, headers = self._http.request_bytes("POST", "/render/xlsx", json=body)
+        return BinaryResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+        )
+
+    def docx(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> BinaryResult:
+        """Render a template to DOCX. Returns raw binary."""
+        body = _build_render_body(template, data, version=version, options=options)
+        content, headers = self._http.request_bytes("POST", "/render/docx", json=body)
+        return BinaryResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+        )
+
+    def pptx(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> PptxResult:
+        """Render a template to PPTX. Returns raw binary plus warning count.
+
+        Beta in v0.60.0. The route is gated server-side by ``PPTX_ENABLED`` —
+        when disabled, calls return 404.
+        """
+        body = _build_render_body(template, data, version=version, options=options)
+        content, headers = self._http.request_bytes("POST", "/render/pptx", json=body)
+        return PptxResult(
+            data=content,
+            content_type=headers.get("content-type"),
+            content_disposition=headers.get("content-disposition"),
+            warning_count=_parse_warning_count(headers.get("x-render-warnings")),
+        )
+
+    def dry_run(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        format: DryRunFormat = "pdf",
+        version: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> DryRunResult:
+        """Dry-run a render: validate input data and exercise all template
+        expressions via a trial HTML render, then return structured results
+        without producing any binary output. Skips Chromium / DOCX / PPTX
+        entirely. Useful for CI/CD pre-flight checks.
+
+        Hits the same per-format route as the normal render method
+        (``/render/``, ``/render/html``, etc.) with ``dryRun: true`` in the
+        body. The route returns JSON regardless of its normal content type.
+
+        Unlike the normal render methods, this method does NOT raise on
+        template author errors (validation failures, undefined variables,
+        etc.) — those are surfaced in the result so callers can display them
+        to users. The only way this method raises is if the request itself
+        is malformed (network error, 4xx auth error, etc.) — in which case
+        :class:`PulpEngineError` is raised as usual.
+
+        Args:
+            template: Template key to dry-run.
+            data: Input data payload.
+            format: Which format route to hit. Defaults to ``"pdf"``. The
+                resulting :class:`DryRunResult` shape is identical regardless
+                of format — the format selector only affects which route is
+                queried (matters when different formats have different rate
+                limits or feature gates server-side).
+            version: Optional exact saved template version to dry-run.
+            options: Optional render options (paperSize, orientation).
+
+        Returns:
+            A :class:`DryRunResult` with ``valid``, ``validation``,
+            ``expressions``, ``field_mappings_applied``, and
+            ``data_sources_resolved`` fields.
+
+        Example::
+
+            result = client.render.dry_run("invoice", {"amount": 100})
+            if not result.valid:
+                for err in result.expressions.errors:
+                    print(err.message, err.location.node_path if err.location else "")
+        """
+        path = _DRY_RUN_PATHS[format]
+        body: dict[str, Any] = {"template": template, "data": data, "dryRun": True}
+        if version is not None:
+            body["version"] = version
+        if options is not None:
+            body["options"] = options
+        response = self._http.request_json("POST", path, json=body)
+        return DryRunResult.model_validate(response)
+
+    def validate(
+        self,
+        template: str,
+        data: dict[str, Any],
+        *,
+        version: str | None = None,
+    ) -> dict[str, Any]:
+        """Validate a template for publication readiness.
+
+        Returns a dict with ``valid: bool`` and ``issues: list``.
+        """
+        body: dict[str, Any] = {"template": template, "data": data}
+        if version is not None:
+            body["version"] = version
+        result = self._http.request_json("POST", "/render/validate", json=body)
+        return result  # type: ignore[no-any-return]

pulp_engine/resources/schedules.py

@@ -0,0 +1,95 @@
+"""Schedules resource — scheduled render jobs and execution history."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import HttpClient
+from ..pagination import PaginatedResult
+from ..types import Schedule, ScheduleExecution
+
+
+class SchedulesResource:
+    """Scheduled render jobs and execution history."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        enabled: bool | None = None,
+    ) -> PaginatedResult[Schedule]:
+        """List schedule definitions (paginated). Admin only."""
+        body = self._http.request_json(
+            "GET",
+            "/schedules/",
+            params={
+                "limit": limit,
+                "offset": offset,
+                "enabled": "true" if enabled is True else "false" if enabled is False else None,
+            },
+        )
+        return PaginatedResult(
+            items=[Schedule.model_validate(item) for item in body["items"]],
+            total=body["total"],
+            limit=body["limit"],
+            offset=body["offset"],
+        )
+
+    def get(self, id: str) -> Schedule:
+        """Get a schedule by ID. Admin only."""
+        body = self._http.request_json("GET", f"/schedules/{id}")
+        return Schedule.model_validate(body)
+
+    def create(self, schedule: dict[str, Any]) -> Schedule:
+        """Create a new schedule. Admin only."""
+        body = self._http.request_json("POST", "/schedules/", json=schedule)
+        return Schedule.model_validate(body)
+
+    def update(self, id: str, schedule: dict[str, Any]) -> Schedule:
+        """Full-replace a schedule (PUT). Admin only."""
+        body = self._http.request_json("PUT", f"/schedules/{id}", json=schedule)
+        return Schedule.model_validate(body)
+
+    def patch(self, id: str, patch: dict[str, Any]) -> Schedule:
+        """Partially update a schedule (PATCH). Admin only."""
+        body = self._http.request_json("PATCH", f"/schedules/{id}", json=patch)
+        return Schedule.model_validate(body)
+
+    def delete(self, id: str) -> None:
+        """Delete a schedule. Admin only."""
+        self._http.request_json("DELETE", f"/schedules/{id}")
+
+    def trigger(self, id: str) -> ScheduleExecution:
+        """Manually trigger a schedule execution. Admin only."""
+        body = self._http.request_json("POST", f"/schedules/{id}/trigger")
+        return ScheduleExecution.model_validate(body)
+
+    def list_executions(
+        self,
+        id: str,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        status: str | None = None,
+    ) -> PaginatedResult[ScheduleExecution]:
+        """List execution history for a schedule (paginated). Admin only."""
+        body = self._http.request_json(
+            "GET",
+            f"/schedules/{id}/executions",
+            params={"limit": limit, "offset": offset, "status": status},
+        )
+        return PaginatedResult(
+            items=[ScheduleExecution.model_validate(item) for item in body["items"]],
+            total=body["total"],
+            limit=body["limit"],
+            offset=body["offset"],
+        )
+
+    def get_execution(self, id: str, exec_id: str) -> ScheduleExecution:
+        """Get a specific execution. Admin only."""
+        body = self._http.request_json("GET", f"/schedules/{id}/executions/{exec_id}")
+        return ScheduleExecution.model_validate(body)

pulp_engine/resources/templates.py

@@ -0,0 +1,161 @@
+"""Templates resource — CRUD, versioning, schema, validation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import HttpClient
+from ..pagination import PaginatedResult
+from ..types import (
+    TemplateDiff,
+    TemplateSummary,
+    TemplateWithDefinition,
+    ValidationResult,
+    VersionSummary,
+)
+
+
+class TemplatesResource:
+    """Template CRUD and version management."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> PaginatedResult[TemplateSummary]:
+        """List templates (paginated)."""
+        body = self._http.request_json(
+            "GET",
+            "/templates/",
+            params={"limit": limit, "offset": offset},
+        )
+        return PaginatedResult(
+            items=[TemplateSummary.model_validate(item) for item in body["items"]],
+            total=body["total"],
+            limit=body["limit"],
+            offset=body["offset"],
+        )
+
+    def get(self, key: str) -> TemplateWithDefinition:
+        """Get a template with its full definition."""
+        body = self._http.request_json("GET", f"/templates/{key}")
+        return TemplateWithDefinition.model_validate(body)
+
+    def create(self, definition: dict[str, Any]) -> TemplateSummary:
+        """Create a new template."""
+        body = self._http.request_json("POST", "/templates/", json=definition)
+        return TemplateSummary.model_validate(body)
+
+    def update(
+        self,
+        key: str,
+        version: str,
+        definition: dict[str, Any],
+    ) -> TemplateWithDefinition:
+        """Update a template.
+
+        Requires the current version for optimistic concurrency (sent as
+        ``If-Match`` header). The server returns 412 Precondition Failed if
+        another writer has updated the template since the version was fetched.
+        """
+        body = self._http.request_json(
+            "PUT",
+            f"/templates/{key}",
+            json=definition,
+            headers={"If-Match": f'"{version}"'},
+        )
+        return TemplateWithDefinition.model_validate(body)
+
+    def delete(self, key: str, version: str) -> None:
+        """Delete a template (admin only). Requires the current version."""
+        self._http.request_json(
+            "DELETE",
+            f"/templates/{key}",
+            headers={"If-Match": f'"{version}"'},
+        )
+
+    def schema(self, key: str) -> dict[str, Any]:
+        """Get the JSON Schema describing the template's expected input data."""
+        body = self._http.request_json("GET", f"/templates/{key}/schema")
+        return body  # type: ignore[no-any-return]
+
+    def sample(self, key: str) -> dict[str, Any]:
+        """Get auto-generated sample data for a template."""
+        body = self._http.request_json("GET", f"/templates/{key}/sample")
+        return body  # type: ignore[no-any-return]
+
+    def validate(self, key: str, input_data: dict[str, Any]) -> ValidationResult:
+        """Validate input data against the template's schema."""
+        body = self._http.request_json(
+            "POST",
+            f"/templates/{key}/validate",
+            json=input_data,
+        )
+        return ValidationResult.model_validate(body)
+
+    def versions(
+        self,
+        key: str,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> PaginatedResult[VersionSummary]:
+        """List version history (paginated)."""
+        body = self._http.request_json(
+            "GET",
+            f"/templates/{key}/versions",
+            params={"limit": limit, "offset": offset},
+        )
+        return PaginatedResult(
+            items=[VersionSummary.model_validate(item) for item in body["items"]],
+            total=body["total"],
+            limit=body["limit"],
+            offset=body["offset"],
+        )
+
+    def get_version(self, key: str, version: str) -> TemplateWithDefinition:
+        """Get a specific historical version."""
+        body = self._http.request_json("GET", f"/templates/{key}/versions/{version}")
+        return TemplateWithDefinition.model_validate(body)
+
+    def restore(
+        self,
+        key: str,
+        version: str,
+        current_version: str,
+    ) -> TemplateWithDefinition:
+        """Restore a historical version as the current version (admin only)."""
+        body = self._http.request_json(
+            "POST",
+            f"/templates/{key}/versions/{version}/restore",
+            headers={"If-Match": f'"{current_version}"'},
+        )
+        return TemplateWithDefinition.model_validate(body)
+
+    def diff(
+        self,
+        key: str,
+        *,
+        before_version: str,
+        after_version: str,
+    ) -> TemplateDiff:
+        """Diff two stored versions of the same template key.
+
+        Returns the raw ``TemplateDiff`` envelope from
+        ``@pulp-engine/template-diff``. Both versions must exist in the
+        resolved tenant; otherwise the server returns 404 (raised as
+        :class:`PulpEngineError`).
+        """
+        body = self._http.request_json(
+            "POST",
+            f"/templates/{key}/diff",
+            json={
+                "beforeVersion": before_version,
+                "afterVersion": after_version,
+            },
+        )
+        return TemplateDiff.model_validate(body)