typefold-client 0.2.1__py3-none-any.whl

typefold/_client.py

@@ -0,0 +1,679 @@
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import itertools
+import json
+import time
+from collections.abc import Generator, Sequence
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta, timezone
+from decimal import Decimal
+from email.utils import parsedate_to_datetime
+from enum import Enum
+from typing import Any, TypeVar
+from urllib.parse import quote
+from uuid import UUID
+
+import httpx
+
+from ._errors import TypefoldError
+from .models import (
+    ApiError,
+    DirectRenderRequest,
+    Render,
+    RenderBatch,
+    RenderReportRequest,
+    RenderRequest,
+    RenderState,
+    RenderStringRequest,
+    ReportSummary,
+    TemplateRef,
+)
+
+MAX_WAIT_MS = 10_000
+FIRST_POLL_INTERVAL = 1.0
+MAX_POLL_INTERVAL = 5.0
+DEFAULT_WAIT_TIMEOUT = 120.0
+DEFAULT_BATCH_WAIT_TIMEOUT = 600.0
+DEFAULT_HTTP_TIMEOUT = 120.0
+FIRST_RETRY_DELAY = 1.0
+MAX_RETRY_DELAY = 30.0
+_UNFINISHED = (RenderState.QUEUED, RenderState.PROCESSING)
+
+T = TypeVar("T")
+
+
+@dataclass
+class _Http:
+    """Asks the driver to send one HTTP request with these ``httpx`` arguments."""
+
+    request: dict[str, Any]
+
+
+@dataclass
+class _Sleep:
+    """Asks the driver to wait."""
+
+    seconds: float
+
+
+# The client's logic is written once as generators that yield what to do; the blocking and the
+# asyncio client each run them with their own I/O.
+_Plan = Generator[_Http | _Sleep, Any, T]
+
+
+class _Base:
+    _http: httpx.Client | httpx.AsyncClient
+
+    def __init__(self, base_url: str, api_key: str, max_rate_limit_retries: int) -> None:
+        if not base_url:
+            raise ValueError("base_url is required.")
+
+        if not api_key:
+            raise ValueError("api_key is required.")
+
+        # A trailing slash keeps a base path such as /pdf when paths are appended.
+        self._base_url = base_url.rstrip("/") + "/"
+        self._api_key = api_key
+        self.max_rate_limit_retries = max_rate_limit_retries
+        """
+        How many times a request the API refused with ``429 RATE_LIMITED`` is sent again, after its
+        ``Retry-After`` (else 1, 2, 4… seconds, at most 30). A refused request did no work, so any
+        request can be retried. Defaults to 3; 0 raises the first refusal.
+        """
+
+    def _render_report(self, request: RenderReportRequest, idempotency_key: str | None) -> _Plan[bytes]:
+        response = yield from self._send("POST", "v1/reports/render", _dump(request), idempotency_key)
+
+        return response.content
+
+    def _render_string(self, request: RenderStringRequest) -> _Plan[str]:
+        response = yield from self._send("POST", "v1/renders/string", _dump(request))
+
+        return str(response.json()["content"])
+
+    def _list_reports(self) -> _Plan[list[ReportSummary]]:
+        response = yield from self._send("GET", "v1/reports")
+
+        return [ReportSummary.from_json(item) for item in response.json()["items"]]
+
+    def _get_report_data_schema(self, format: str, template: TemplateRef) -> _Plan[dict[str, Any]]:
+        response = yield from self._send("GET", _data_schema_path(format, template))
+        schema: dict[str, Any] = response.json()
+
+        return schema
+
+    def _create_render(self, request: RenderRequest, idempotency_key: str | None) -> _Plan[Render]:
+        response = yield from self._send("POST", "v1/renders", _dump(_with_margins(request)), idempotency_key)
+
+        return Render.from_json(response.json())
+
+    def _get_render(self, id: str, deadline: float | None = None) -> _Plan[Render]:
+        response = yield from self._send("GET", "v1/renders/" + quote(id, safe=""), deadline=deadline)
+
+        return Render.from_json(response.json())
+
+    def _cancel_render(self, id: str) -> _Plan[None]:
+        yield from self._send("POST", f"v1/renders/{quote(id, safe='')}/cancel")
+
+    def _wait_for_render(self, render: Render, timeout: float | None) -> _Plan[Render]:
+        deadline = time.monotonic() + (DEFAULT_WAIT_TIMEOUT if timeout is None else timeout)
+        interval = FIRST_POLL_INTERVAL
+
+        while render.state in _UNFINISHED:
+            remaining = deadline - time.monotonic()
+
+            if remaining <= 0:
+                raise _timeout_error(render)
+
+            yield _Sleep(min(remaining, interval))
+            interval = min(interval * 2, MAX_POLL_INTERVAL)
+
+            try:
+                # Each poll ends by the deadline, rate-limit retries included.
+                render = yield from self._get_render(render.id, deadline)
+            except TypefoldError as error:
+                # Such as RATE_LIMITED; poll again.
+                if not error.retryable:
+                    raise
+            except httpx.TransportError:
+                # A dropped connection, or a poll cut off at the deadline; poll again.
+                pass
+
+        return render
+
+    def _create_batch(self, items: Sequence[RenderRequest], idempotency_key: str | None) -> _Plan[RenderBatch]:
+        # Batches never wait, so wait_ms is not sent; set on copies so the caller's requests are unchanged.
+        body = {"items": [_dump(_with_margins(dataclasses.replace(item, wait_ms=None))) for item in items]}
+        response = yield from self._send("POST", "v1/renders/batch", body, idempotency_key)
+
+        return RenderBatch.from_json(response.json())
+
+    def _get_batch(self, id: str, deadline: float | None = None) -> _Plan[RenderBatch]:
+        response = yield from self._send("GET", "v1/renders/batch/" + quote(id, safe=""), deadline=deadline)
+
+        return RenderBatch.from_json(response.json())
+
+    def _wait_for_batch(self, batch: RenderBatch, timeout: float | None) -> _Plan[RenderBatch]:
+        deadline = time.monotonic() + (DEFAULT_BATCH_WAIT_TIMEOUT if timeout is None else timeout)
+        interval = FIRST_POLL_INTERVAL
+
+        while batch.counts.queued + batch.counts.processing > 0:
+            remaining = deadline - time.monotonic()
+
+            if remaining <= 0:
+                raise _batch_timeout_error(batch)
+
+            yield _Sleep(min(remaining, interval))
+            interval = min(interval * 2, MAX_POLL_INTERVAL)
+
+            try:
+                # Each poll ends by the deadline, rate-limit retries included.
+                batch = yield from self._get_batch(batch.id, deadline)
+            except TypefoldError as error:
+                # Such as RATE_LIMITED; poll again.
+                if not error.retryable:
+                    raise
+            except httpx.TransportError:
+                # A dropped connection, or a poll cut off at the deadline; poll again.
+                pass
+
+        return batch
+
+    def _download_batch(self, id: str) -> _Plan[bytes]:
+        response = yield from self._send("GET", f"v1/renders/batch/{quote(id, safe='')}/pdf")
+
+        return response.content
+
+    def _download(self, render: Render) -> _Plan[bytes]:
+        if _url_expiring(render):
+            render = yield from self._get_render(render.id)
+
+        if render.result is None:
+            raise ValueError(f"Render {render.id} is {render.state} and has no PDF.")
+
+        # The signed URL may point at object storage, so the API key is not sent.
+        response = yield _Http({"method": "GET", "url": render.result.download_url})
+
+        return _ensure_success(response).content
+
+    def _render(self, request: RenderRequest, idempotency_key: str | None, timeout: float | None) -> _Plan[bytes]:
+        # The API holds creation up to 10 s; set on a copy so the caller's request is unchanged.
+        if request.wait_ms is None:
+            request = dataclasses.replace(request, wait_ms=MAX_WAIT_MS)
+
+        created = yield from self._create_render(request, idempotency_key)
+        render = yield from self._wait_for_render(created, timeout)
+
+        if render.state != RenderState.SUCCEEDED:
+            raise _failed_error(render)
+
+        return (yield from self._download(render))
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        idempotency_key: str | None = None,
+        deadline: float | None = None,
+    ) -> _Plan[httpx.Response]:
+        """Sends a request, retrying rate limits; with a ``deadline``, it and its retries end by then."""
+        request = self._request(method, path, body, idempotency_key)
+        delay = FIRST_RETRY_DELAY
+
+        for attempt in itertools.count():
+            if deadline is not None:
+                request["timeout"] = self._timeout_until(deadline)
+
+            response = yield _Http(request)
+            wait = self._retry_delay(response, attempt, delay)
+
+            if wait is None or (deadline is not None and time.monotonic() + wait >= deadline):
+                return _ensure_success(response)
+
+            yield _Sleep(wait)
+            delay = min(delay * 2, MAX_RETRY_DELAY)
+
+        raise AssertionError("unreachable")
+
+    def _request(self, method: str, path: str, body: Any, idempotency_key: str | None) -> dict[str, Any]:
+        # The key goes on each request rather than the httpx client, which callers may share.
+        headers = {"x-api-key": self._api_key}
+
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        request: dict[str, Any] = {"method": method, "url": self._base_url + path, "headers": headers}
+
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            request["content"] = _json(body)
+
+        return request
+
+    def _timeout_until(self, deadline: float) -> httpx.Timeout:
+        """The httpx client's timeout, shortened to end at ``deadline``."""
+        remaining = max(deadline - time.monotonic(), 0.001)
+        own = self._http.timeout
+
+        def shorter(value: float | None) -> float:
+            return remaining if value is None else min(value, remaining)
+
+        return httpx.Timeout(
+            connect=shorter(own.connect), read=shorter(own.read), write=shorter(own.write), pool=shorter(own.pool)
+        )
+
+    def _retry_delay(self, response: httpx.Response, attempt: int, delay: float) -> float | None:
+        """Seconds to wait before sending a refused request again, or None to return the response."""
+        if response.status_code != 429 or attempt >= self.max_rate_limit_retries:
+            return None
+
+        wait = _retry_after(response)
+
+        return min(delay if wait is None else wait, MAX_RETRY_DELAY)
+
+
+class TypefoldClient(_Base):
+    """Client for the Typefold API, authenticated with an organization API key.
+
+    Create one per API key and reuse it; close it, or use it as a context manager, when done.
+    """
+
+    _http: httpx.Client
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        http_client: httpx.Client | None = None,
+        max_rate_limit_retries: int = 3,
+    ) -> None:
+        """
+        :param base_url: The API's address, such as ``https://pdf.example.com``.
+        :param api_key: An organization API key; report renders need ``render:create``,
+            ``render:read`` and ``template:read``.
+        :param http_client: A shared ``httpx.Client``. Report PDFs can take up to 95 seconds, so give
+            it a timeout above that; the default client waits 120 seconds. It is not closed with this
+            client.
+        """
+        super().__init__(base_url, api_key, max_rate_limit_retries)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=DEFAULT_HTTP_TIMEOUT)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> TypefoldClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def render_report(self, request: RenderReportRequest, *, idempotency_key: str | None = None) -> bytes:
+        """Renders a published report or template and returns the PDF or XLSX bytes.
+
+        :param idempotency_key: Retrying a PDF render with the same key returns the render the key
+            first created.
+        """
+        return self._run(self._render_report(request, idempotency_key))
+
+    def render_string(self, request: RenderStringRequest) -> str:
+        """Renders a template string with data, synchronously and without a PDF, and returns the text
+        or HTML; for email bodies, subjects, SMS and push messages."""
+        return self._run(self._render_string(request))
+
+    def list_reports(self) -> list[ReportSummary]:
+        """Lists templates and the formats each renders; render them by name, ID or jsreport shortid."""
+        return self._run(self._list_reports())
+
+    def get_report_data_schema(self, format: str, template: TemplateRef) -> dict[str, Any]:
+        """Returns the JSON Schema of the data a published report renders.
+
+        :param format: ``ReportFormat.PDF`` or ``ReportFormat.XLSX``.
+        """
+        return self._run(self._get_report_data_schema(format, template))
+
+    def create_render(self, request: RenderRequest, *, idempotency_key: str | None = None) -> Render:
+        """Creates a render; it may still be queued or processing when this returns."""
+        return self._run(self._create_render(request, idempotency_key))
+
+    def get_render(self, id: str) -> Render:
+        return self._run(self._get_render(id))
+
+    def cancel_render(self, id: str) -> None:
+        self._run(self._cancel_render(id))
+
+    def wait_for_render(self, render: Render, *, timeout: float | None = None) -> Render:
+        """Polls until the render finishes, backing off from 1 to 5 seconds; raises
+        ``RENDER_TIMEOUT`` after ``timeout`` seconds (2 minutes). Dropped connections and retryable
+        API errors are polled through."""
+        return self._run(self._wait_for_render(render, timeout))
+
+    def download(self, render: Render) -> bytes:
+        """Downloads a succeeded render's PDF, re-reading the render first if its signed URL has
+        expired."""
+        return self._run(self._download(render))
+
+    def render(
+        self,
+        request: RenderRequest,
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> bytes:
+        """Creates a render, waits for it and returns the PDF; a failed or cancelled render raises."""
+        return self._run(self._render(request, idempotency_key, timeout))
+
+    def create_batch(self, items: Sequence[RenderRequest], *, idempotency_key: str | None = None) -> RenderBatch:
+        """Creates up to 100 renders in one request and returns the batch; if any item is invalid,
+        none is created. Items are ``DirectRenderRequest`` or ``TemplateVersionRenderRequest``;
+        their ``wait_ms`` is not sent, as batches never wait."""
+        return self._run(self._create_batch(items, idempotency_key))
+
+    def get_batch(self, id: str) -> RenderBatch:
+        return self._run(self._get_batch(id))
+
+    def wait_for_batch(self, batch: RenderBatch, *, timeout: float | None = None) -> RenderBatch:
+        """Polls until no item is queued or processing, backing off from 1 to 5 seconds; raises
+        ``RENDER_TIMEOUT`` after ``timeout`` seconds (10 minutes). Failed items do not stop the
+        others."""
+        return self._run(self._wait_for_batch(batch, timeout))
+
+    def download_batch(self, id: str) -> bytes:
+        """Downloads one PDF of every item in order; every item must have succeeded."""
+        return self._run(self._download_batch(id))
+
+    def _run(self, plan: _Plan[T]) -> T:
+        sent: Any = None
+        error: Exception | None = None
+
+        while True:
+            try:
+                step = plan.throw(error) if error is not None else plan.send(sent)
+            except StopIteration as stop:
+                result: T = stop.value
+
+                return result
+
+            sent, error = None, None
+
+            if isinstance(step, _Sleep):
+                time.sleep(step.seconds)
+                continue
+
+            try:
+                sent = self._http.request(**step.request)
+            except httpx.TransportError as failure:
+                error = failure
+
+
+class AsyncTypefoldClient(_Base):
+    """The asyncio counterpart of ``TypefoldClient``, with the same methods as coroutines."""
+
+    _http: httpx.AsyncClient
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        max_rate_limit_retries: int = 3,
+    ) -> None:
+        super().__init__(base_url, api_key, max_rate_limit_retries)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=DEFAULT_HTTP_TIMEOUT)
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncTypefoldClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    async def render_report(self, request: RenderReportRequest, *, idempotency_key: str | None = None) -> bytes:
+        return await self._run(self._render_report(request, idempotency_key))
+
+    async def render_string(self, request: RenderStringRequest) -> str:
+        return await self._run(self._render_string(request))
+
+    async def list_reports(self) -> list[ReportSummary]:
+        return await self._run(self._list_reports())
+
+    async def get_report_data_schema(self, format: str, template: TemplateRef) -> dict[str, Any]:
+        return await self._run(self._get_report_data_schema(format, template))
+
+    async def create_render(self, request: RenderRequest, *, idempotency_key: str | None = None) -> Render:
+        return await self._run(self._create_render(request, idempotency_key))
+
+    async def get_render(self, id: str) -> Render:
+        return await self._run(self._get_render(id))
+
+    async def cancel_render(self, id: str) -> None:
+        await self._run(self._cancel_render(id))
+
+    async def wait_for_render(self, render: Render, *, timeout: float | None = None) -> Render:
+        return await self._run(self._wait_for_render(render, timeout))
+
+    async def download(self, render: Render) -> bytes:
+        return await self._run(self._download(render))
+
+    async def render(
+        self,
+        request: RenderRequest,
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> bytes:
+        return await self._run(self._render(request, idempotency_key, timeout))
+
+    async def create_batch(self, items: Sequence[RenderRequest], *, idempotency_key: str | None = None) -> RenderBatch:
+        return await self._run(self._create_batch(items, idempotency_key))
+
+    async def get_batch(self, id: str) -> RenderBatch:
+        return await self._run(self._get_batch(id))
+
+    async def wait_for_batch(self, batch: RenderBatch, *, timeout: float | None = None) -> RenderBatch:
+        return await self._run(self._wait_for_batch(batch, timeout))
+
+    async def download_batch(self, id: str) -> bytes:
+        return await self._run(self._download_batch(id))
+
+    async def _run(self, plan: _Plan[T]) -> T:
+        sent: Any = None
+        error: Exception | None = None
+
+        while True:
+            try:
+                step = plan.throw(error) if error is not None else plan.send(sent)
+            except StopIteration as stop:
+                result: T = stop.value
+
+                return result
+
+            sent, error = None, None
+
+            if isinstance(step, _Sleep):
+                await asyncio.sleep(step.seconds)
+                continue
+
+            try:
+                sent = await self._http.request(**step.request)
+            except httpx.TransportError as failure:
+                error = failure
+
+
+def _dump(value: Any) -> Any:
+    """A request model as the API's JSON: camelCase names, None fields left out, data as written."""
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        body: dict[str, Any] = {}
+
+        for item in dataclasses.fields(value):
+            field_value = getattr(value, item.name)
+            data = item.metadata.get("data")
+
+            if data is not None:
+                if field_value is not None:
+                    body[item.name] = field_value
+                elif data == "empty":
+                    body[item.name] = {}
+
+                continue
+
+            if field_value is not None:
+                body[_camel(item.name)] = _dump(field_value)
+
+        return body
+
+    if isinstance(value, (list, tuple)):
+        return [_dump(item) for item in value]
+
+    return value
+
+
+def _with_margins(request: RenderRequest) -> RenderRequest:
+    """A copy of a direct render with the margins it left out at 10 mm, as the API needs all four."""
+    if not isinstance(request, DirectRenderRequest):
+        return request
+
+    margins = request.settings.margins
+    sides = {name: 10.0 for name in ("top_mm", "right_mm", "bottom_mm", "left_mm") if getattr(margins, name) is None}
+
+    if not sides:
+        return request
+
+    settings = dataclasses.replace(request.settings, margins=dataclasses.replace(margins, **sides))
+
+    return dataclasses.replace(request, settings=settings)
+
+
+def _json(body: Any) -> bytes:
+    # NaN and Infinity are not JSON; json would write them anyway.
+    return json.dumps(body, default=_json_default, separators=(",", ":"), allow_nan=False).encode()
+
+
+def _camel(name: str) -> str:
+    head, *rest = name.split("_")
+
+    return head + "".join(part.capitalize() for part in rest)
+
+
+def _json_default(value: Any) -> Any:
+    """Writes the values json cannot, as they commonly appear in template data."""
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError(f"JSON has no {value}; send it as a string or null.")
+
+        return int(value) if value == value.to_integral_value() else float(value)
+
+    if isinstance(value, UUID):
+        return str(value)
+
+    if isinstance(value, Enum):
+        return value.value
+
+    if isinstance(value, (set, frozenset)):
+        return list(value)
+
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return dataclasses.asdict(value)
+
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def _data_schema_path(format: str, template: TemplateRef) -> str:
+    if template.id is not None:
+        selector = "id=" + quote(template.id, safe="")
+    elif template.shortid is not None:
+        selector = "shortid=" + quote(template.shortid, safe="")
+    else:
+        selector = "name=" + quote(template.name or "", safe="")
+
+    return f"v1/reports/data-schema?format={quote(format, safe='')}&{selector}"
+
+
+def _url_expiring(render: Render) -> bool:
+    return render.result is not None and render.result.expires_at <= datetime.now(timezone.utc) + timedelta(seconds=30)
+
+
+def _timeout_error(render: Render) -> TypefoldError:
+    return TypefoldError(
+        None,
+        ApiError(
+            code="RENDER_TIMEOUT",
+            message=f"Render {render.id} is still {render.state}.",
+            retryable=True,
+            render_id=render.id,
+        ),
+    )
+
+
+def _batch_timeout_error(batch: RenderBatch) -> TypefoldError:
+    return TypefoldError(
+        None,
+        ApiError(code="RENDER_TIMEOUT", message=f"Batch {batch.id} still has unfinished items.", retryable=True),
+    )
+
+
+def _failed_error(render: Render) -> TypefoldError:
+    error = render.error or ApiError(code="RENDER_FAILED", message=f"Render {render.id} was {render.state}.")
+
+    return TypefoldError(None, dataclasses.replace(error, render_id=render.id))
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    header = response.headers.get("retry-after", "").strip()
+
+    if not header:
+        return None
+
+    if header.isdigit():
+        return float(header)
+
+    try:
+        when = parsedate_to_datetime(header)
+    except (TypeError, ValueError):
+        return None
+
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+
+    return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
+
+
+def _ensure_success(response: httpx.Response) -> httpx.Response:
+    if response.is_success:
+        return response
+
+    status = response.status_code
+    text = response.text
+    error: ApiError | None = None
+
+    try:
+        envelope = json.loads(text)
+
+        if isinstance(envelope, dict) and isinstance(envelope.get("error"), dict):
+            error = ApiError.from_json(envelope["error"])
+    except ValueError:
+        # Not the API's envelope, e.g. a proxy's error page.
+        pass
+
+    raise TypefoldError(
+        status,
+        error
+        or ApiError(
+            code="HTTP_ERROR",
+            message=f"HTTP {status}: {text[:200]}",
+            retryable=status == 429 or status >= 500,
+        ),
+    )

typefold/_errors.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .models import ApiError
+
+
+class TypefoldError(Exception):
+    """An API error response, or a render that failed or was cancelled."""
+
+    def __init__(self, status_code: int | None, error: ApiError) -> None:
+        super().__init__(f"{error.code}: {error.message}")
+        self.status_code = status_code
+        """The HTTP status, or ``None`` when a render failed after it was accepted."""
+        self.error = error
+
+    @property
+    def code(self) -> str:
+        """The API's code, such as ``NOT_FOUND``, ``RATE_LIMITED`` or ``RENDER_TIMEOUT``."""
+        return self.error.code
+
+    @property
+    def retryable(self) -> bool:
+        """Whether a retry can help."""
+        return self.error.retryable