galley-render 0.1.0__py3-none-any.whl

galley_render/__init__.py

@@ -0,0 +1,57 @@
+"""galley-render — JSON in, PDF out.
+
+::
+
+    from galley_render import Galley
+
+    galley = Galley(api_key=os.environ["GALLEY_API_KEY"])
+    render = galley.render("invoice@1", format="pdf", data={"invoice_number": "INV-1042"})
+    galley.download(render, to_file="invoice.pdf")
+
+With no key at all, :func:`start_trial` mints a 50-render account through the
+MCP server and hands back a key that works everywhere in this package.
+"""
+
+from ._client import DEFAULT_BASE_URL, AsyncGalley, Galley, __version__
+from ._errors import (
+    FieldError,
+    GalleyConnectionError,
+    GalleyError,
+    GalleyTimeoutError,
+)
+from ._models import (
+    Account,
+    Batch,
+    DeletedTemplate,
+    Render,
+    Template,
+    TemplateVersion,
+    Usage,
+    Validation,
+    WebhookSecret,
+)
+from ._trial import DEFAULT_MCP_URL, Trial, async_start_trial, start_trial
+
+__all__ = [
+    "Galley",
+    "AsyncGalley",
+    "start_trial",
+    "async_start_trial",
+    "Trial",
+    "GalleyError",
+    "GalleyConnectionError",
+    "GalleyTimeoutError",
+    "FieldError",
+    "Render",
+    "Batch",
+    "Template",
+    "TemplateVersion",
+    "Validation",
+    "Usage",
+    "Account",
+    "WebhookSecret",
+    "DeletedTemplate",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MCP_URL",
+    "__version__",
+]

galley_render/_client.py

@@ -0,0 +1,494 @@
+"""The clients.
+
+``Galley`` and ``AsyncGalley`` expose the same surface, named the same way, so
+moving a script from one to the other is a matter of adding ``await``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+import httpx
+
+from ._errors import GalleyError, GalleyTimeoutError
+from ._models import (
+    Account,
+    Batch,
+    DeletedTemplate,
+    Render,
+    Template,
+    TemplateVersion,
+    Usage,
+    Validation,
+    WebhookSecret,
+)
+from ._transport import DEFAULT_BASE_URL, AsyncTransport, SyncTransport
+
+__version__ = "0.1.0"
+
+__all__ = ["Galley", "AsyncGalley", "DEFAULT_BASE_URL", "__version__"]
+
+_USER_AGENT = f"galley-render-python/{__version__}"
+
+
+def _render_body(
+    template: str,
+    *,
+    version: Optional[Union[int, str]] = None,
+    data: Any = None,
+    format: Optional[str] = None,
+    options: Optional[Mapping[str, Any]] = None,
+    webhook_url: Optional[str] = None,
+    async_: bool = False,
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {"template": template}
+    if version is not None:
+        body["version"] = version
+    if data is not None:
+        body["data"] = data
+    if format is not None:
+        body["format"] = format
+    if options:
+        body["options"] = dict(options)
+    if webhook_url:
+        body["webhook_url"] = webhook_url
+    if async_:
+        body["async"] = True
+    return body
+
+
+def _template_body(
+    *,
+    source: str,
+    engine: Optional[str] = None,
+    schema: Optional[Mapping[str, Any]] = None,
+    options: Optional[Mapping[str, Any]] = None,
+    example: Any = None,
+    description: Optional[str] = None,
+    message: Optional[str] = None,
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {"source": source}
+    if engine is not None:
+        body["engine"] = engine
+    if schema is not None:
+        body["schema"] = dict(schema)
+    if options is not None:
+        body["options"] = dict(options)
+    if example is not None:
+        body["example"] = example
+    if description is not None:
+        body["description"] = description
+    if message is not None:
+        body["message"] = message
+    return body
+
+
+def _require_url(render: Render) -> str:
+    if render.url:
+        return render.url
+    if render.status == "failed":
+        raise GalleyError(
+            f"Render {render.id} failed, so there is nothing to download. See `render.error`.",
+            type="render_failed",
+            status=500,
+            body=render.raw,
+        )
+    raise GalleyError(
+        f"Render {render.id} is {render.status} and has no file yet. Wait for it with `renders.wait()`.",
+        type="not_found",
+        status=404,
+        body=render.raw,
+    )
+
+
+def _failed_render_error(render: Render) -> GalleyError:
+    detail = render.error if isinstance(render.error, dict) else {}
+    return GalleyError(
+        detail.get("message") or f"Render {render.id} failed.",
+        type=detail.get("type") or "render_failed",
+        status=500,
+        body=render.raw,
+    )
+
+
+def _settings(
+    api_key: Optional[str],
+    base_url: Optional[str],
+) -> Dict[str, Any]:
+    return {
+        "api_key": api_key if api_key is not None else (os.environ.get("GALLEY_API_KEY") or None),
+        "base_url": base_url or os.environ.get("GALLEY_BASE_URL") or DEFAULT_BASE_URL,
+    }
+
+
+# --------------------------------------------------------------------------
+# sync
+# --------------------------------------------------------------------------
+
+
+class Galley:
+    """Synchronous client.
+
+    ::
+
+        galley = Galley(api_key=os.environ["GALLEY_API_KEY"])
+        render = galley.render("invoice@1", data={"invoice_number": "INV-1042"}, format="pdf")
+        galley.download(render, to_file="invoice.pdf")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 3,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        resolved = _settings(api_key, base_url)
+        self._t = SyncTransport(
+            client=http_client,
+            api_key=resolved["api_key"],
+            base_url=resolved["base_url"],
+            timeout=timeout,
+            max_retries=max_retries,
+            headers=headers,
+            user_agent=_USER_AGENT,
+        )
+        self.renders = Renders(self._t)
+        self.templates = Templates(self._t)
+
+    @property
+    def base_url(self) -> str:
+        return self._t.base_url
+
+    def close(self) -> None:
+        self._t.close()
+
+    def __enter__(self) -> "Galley":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def render(self, template: str, **kwargs: Any) -> Render:
+        """``POST /v1/render``. The one call most programs make."""
+        return self.renders.create(template, **kwargs)
+
+    def usage(self) -> Usage:
+        """``GET /v1/usage`` — this period's spend, what is left, the trial balance."""
+        return Usage.from_api(self._t.request("GET", "/v1/usage"))
+
+    def account(self) -> Account:
+        """``GET /v1/account`` — the account, and the webhook signing secret.
+
+        ``webhook_secret`` has a value only on the **first** call that has one
+        to give; every call after that returns ``None`` and only the prefix.
+        Store it when you get it.
+        """
+        return Account.from_api(self._t.request("GET", "/v1/account"))
+
+    def rotate_webhook_secret(self) -> WebhookSecret:
+        """``POST /v1/account/webhook-secret`` — mint a new secret, shown once.
+
+        The previous secret stops verifying deliveries immediately, so update
+        your handler in the same change.
+        """
+        return WebhookSecret.from_api(self._t.request("POST", "/v1/account/webhook-secret"))
+
+    def render_and_wait(
+        self,
+        template: str,
+        *,
+        poll_interval: float = 1.0,
+        wait_timeout: float = 120.0,
+        **kwargs: Any,
+    ) -> Render:
+        """Render and wait, whichever path the API took."""
+        render = self.renders.create(template, **kwargs)
+        if render.succeeded:
+            return render
+        return self.renders.wait(render.id, poll_interval=poll_interval, timeout=wait_timeout)
+
+    def download(self, target: Union[Render, str], *, to_file: Optional[str] = None) -> bytes:
+        """Fetch the bytes behind a render's signed URL.
+
+        Accepts a render, a render id or a URL. A signed URL that has expired —
+        they are short-lived by design — is re-signed by re-reading the render
+        rather than failing.
+        """
+        url = self._resolve_url(target)
+        try:
+            body = self._t.get_bytes(url)
+        except GalleyError as err:
+            if err.status not in (401, 403) or isinstance(target, str):
+                raise
+            body = self._t.get_bytes(_require_url(self.renders.get(target.id)))
+        if to_file:
+            with open(to_file, "wb") as handle:
+                handle.write(body)
+        return body
+
+    def _resolve_url(self, target: Union[Render, str]) -> str:
+        if isinstance(target, str):
+            if target.startswith("http://") or target.startswith("https://"):
+                return target
+            return _require_url(self.renders.get(target))
+        return target.url or _require_url(self.renders.get(target.id))
+
+
+class Renders:
+    def __init__(self, transport: SyncTransport) -> None:
+        self._t = transport
+
+    def create(self, template: str, **kwargs: Any) -> Render:
+        """``POST /v1/render``. Returns ``succeeded`` inline, or ``queued`` to poll."""
+        return Render.from_api(self._t.request("POST", "/v1/render", json=_render_body(template, **kwargs)))
+
+    def batch(self, renders: List[Mapping[str, Any]], *, webhook_url: Optional[str] = None) -> Batch:
+        """``POST /v1/render/batch``. Up to 50; a bad item fails alone, inline."""
+        body: Dict[str, Any] = {
+            "renders": [_render_body(r["template"], **{k: v for k, v in r.items() if k != "template"}) for r in renders]
+        }
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        return Batch.from_api(self._t.request("POST", "/v1/render/batch", json=body))
+
+    def get(self, render_id: str) -> Render:
+        """``GET /v1/renders/:id``. The ``url`` is signed fresh on every read."""
+        return Render.from_api(self._t.request("GET", f"/v1/renders/{render_id}"))
+
+    def list(self, *, limit: Optional[int] = None) -> List[Render]:
+        """``GET /v1/renders``, newest first."""
+        body = self._t.request("GET", "/v1/renders", params={"limit": limit})
+        return [Render.from_api(r) for r in body.get("data", [])]
+
+    def wait(self, render_id: str, *, poll_interval: float = 1.0, timeout: float = 120.0) -> Render:
+        """Poll until the render leaves ``queued``/``processing``.
+
+        A failed render raises, with the API's own error attached — the same
+        thing a synchronous render would have done.
+        """
+        started = time.monotonic()
+        interval = poll_interval
+        while True:
+            render = self.get(render_id)
+            if render.succeeded:
+                return render
+            if render.status == "failed":
+                raise _failed_render_error(render)
+            waited = time.monotonic() - started
+            if waited >= timeout:
+                raise GalleyTimeoutError(render_id, waited)
+            time.sleep(interval)
+            interval = min(interval * 2, 5.0)
+
+
+class Templates:
+    def __init__(self, transport: SyncTransport) -> None:
+        self._t = transport
+
+    def list(self) -> List[Template]:
+        """``GET /v1/templates``."""
+        body = self._t.request("GET", "/v1/templates")
+        return [Template.from_api(t) for t in body.get("data", [])]
+
+    def get(self, ref: str) -> Template:
+        """``GET /v1/templates/:ref`` — ``invoice`` for the latest, ``invoice@3`` to pin."""
+        return Template.from_api(self._t.request("GET", f"/v1/templates/{ref}"))
+
+    def create(self, name: str, *, source: str, **kwargs: Any) -> Template:
+        """``POST /v1/templates`` — creates it at version 1."""
+        body = {"name": name, **_template_body(source=source, **kwargs)}
+        return Template.from_api(self._t.request("POST", "/v1/templates", json=body))
+
+    def publish(self, name: str, *, source: str, **kwargs: Any) -> Template:
+        """``POST /v1/templates/:name/versions`` — a new immutable version.
+
+        Earlier versions keep rendering, and anything pinned to one is
+        unaffected.
+        """
+        return Template.from_api(
+            self._t.request("POST", f"/v1/templates/{name}/versions", json=_template_body(source=source, **kwargs))
+        )
+
+    def versions(self, name: str) -> List[TemplateVersion]:
+        """``GET /v1/templates/:name/versions``."""
+        body = self._t.request("GET", f"/v1/templates/{name}/versions")
+        return [TemplateVersion.from_api(v) for v in body.get("data", [])]
+
+    def validate(self, ref: str, data: Any) -> Validation:
+        """``POST /v1/templates/:ref/validate`` — free, renders nothing."""
+        return Validation.from_api(self._t.request("POST", f"/v1/templates/{ref}/validate", json={"data": data}))
+
+    def delete(self, name: str) -> DeletedTemplate:
+        """``DELETE /v1/templates/:name`` — soft delete; renders keep working."""
+        return DeletedTemplate.from_api(self._t.request("DELETE", f"/v1/templates/{name}"))
+
+
+# --------------------------------------------------------------------------
+# async
+# --------------------------------------------------------------------------
+
+
+class AsyncGalley:
+    """Asynchronous client. Same surface as :class:`Galley`, with ``await``."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 3,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        resolved = _settings(api_key, base_url)
+        self._t = AsyncTransport(
+            client=http_client,
+            api_key=resolved["api_key"],
+            base_url=resolved["base_url"],
+            timeout=timeout,
+            max_retries=max_retries,
+            headers=headers,
+            user_agent=_USER_AGENT,
+        )
+        self.renders = AsyncRenders(self._t)
+        self.templates = AsyncTemplates(self._t)
+
+    @property
+    def base_url(self) -> str:
+        return self._t.base_url
+
+    async def aclose(self) -> None:
+        await self._t.aclose()
+
+    async def __aenter__(self) -> "AsyncGalley":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def render(self, template: str, **kwargs: Any) -> Render:
+        return await self.renders.create(template, **kwargs)
+
+    async def usage(self) -> Usage:
+        return Usage.from_api(await self._t.request("GET", "/v1/usage"))
+
+    async def account(self) -> Account:
+        return Account.from_api(await self._t.request("GET", "/v1/account"))
+
+    async def rotate_webhook_secret(self) -> WebhookSecret:
+        return WebhookSecret.from_api(await self._t.request("POST", "/v1/account/webhook-secret"))
+
+    async def render_and_wait(
+        self,
+        template: str,
+        *,
+        poll_interval: float = 1.0,
+        wait_timeout: float = 120.0,
+        **kwargs: Any,
+    ) -> Render:
+        render = await self.renders.create(template, **kwargs)
+        if render.succeeded:
+            return render
+        return await self.renders.wait(render.id, poll_interval=poll_interval, timeout=wait_timeout)
+
+    async def download(self, target: Union[Render, str], *, to_file: Optional[str] = None) -> bytes:
+        url = await self._resolve_url(target)
+        try:
+            body = await self._t.get_bytes(url)
+        except GalleyError as err:
+            if err.status not in (401, 403) or isinstance(target, str):
+                raise
+            fresh = await self.renders.get(target.id)
+            body = await self._t.get_bytes(_require_url(fresh))
+        if to_file:
+            with open(to_file, "wb") as handle:
+                handle.write(body)
+        return body
+
+    async def _resolve_url(self, target: Union[Render, str]) -> str:
+        if isinstance(target, str):
+            if target.startswith("http://") or target.startswith("https://"):
+                return target
+            return _require_url(await self.renders.get(target))
+        if target.url:
+            return target.url
+        return _require_url(await self.renders.get(target.id))
+
+
+class AsyncRenders:
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._t = transport
+
+    async def create(self, template: str, **kwargs: Any) -> Render:
+        return Render.from_api(await self._t.request("POST", "/v1/render", json=_render_body(template, **kwargs)))
+
+    async def batch(self, renders: List[Mapping[str, Any]], *, webhook_url: Optional[str] = None) -> Batch:
+        body: Dict[str, Any] = {
+            "renders": [_render_body(r["template"], **{k: v for k, v in r.items() if k != "template"}) for r in renders]
+        }
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        return Batch.from_api(await self._t.request("POST", "/v1/render/batch", json=body))
+
+    async def get(self, render_id: str) -> Render:
+        return Render.from_api(await self._t.request("GET", f"/v1/renders/{render_id}"))
+
+    async def list(self, *, limit: Optional[int] = None) -> List[Render]:
+        body = await self._t.request("GET", "/v1/renders", params={"limit": limit})
+        return [Render.from_api(r) for r in body.get("data", [])]
+
+    async def wait(self, render_id: str, *, poll_interval: float = 1.0, timeout: float = 120.0) -> Render:
+        started = time.monotonic()
+        interval = poll_interval
+        while True:
+            render = await self.get(render_id)
+            if render.succeeded:
+                return render
+            if render.status == "failed":
+                raise _failed_render_error(render)
+            waited = time.monotonic() - started
+            if waited >= timeout:
+                raise GalleyTimeoutError(render_id, waited)
+            await asyncio.sleep(interval)
+            interval = min(interval * 2, 5.0)
+
+
+class AsyncTemplates:
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._t = transport
+
+    async def list(self) -> List[Template]:
+        body = await self._t.request("GET", "/v1/templates")
+        return [Template.from_api(t) for t in body.get("data", [])]
+
+    async def get(self, ref: str) -> Template:
+        return Template.from_api(await self._t.request("GET", f"/v1/templates/{ref}"))
+
+    async def create(self, name: str, *, source: str, **kwargs: Any) -> Template:
+        body = {"name": name, **_template_body(source=source, **kwargs)}
+        return Template.from_api(await self._t.request("POST", "/v1/templates", json=body))
+
+    async def publish(self, name: str, *, source: str, **kwargs: Any) -> Template:
+        return Template.from_api(
+            await self._t.request(
+                "POST", f"/v1/templates/{name}/versions", json=_template_body(source=source, **kwargs)
+            )
+        )
+
+    async def versions(self, name: str) -> List[TemplateVersion]:
+        body = await self._t.request("GET", f"/v1/templates/{name}/versions")
+        return [TemplateVersion.from_api(v) for v in body.get("data", [])]
+
+    async def validate(self, ref: str, data: Any) -> Validation:
+        return Validation.from_api(await self._t.request("POST", f"/v1/templates/{ref}/validate", json={"data": data}))
+
+    async def delete(self, name: str) -> DeletedTemplate:
+        return DeletedTemplate.from_api(await self._t.request("DELETE", f"/v1/templates/{name}"))