formatjet 0.1.0__py3-none-any.whl

formatjet/__init__.py

@@ -0,0 +1,53 @@
+"""FormatJet: convert documents, images, data and PDFs with the FormatJet API.
+
+from formatjet import FormatJet
+
+formatjet = FormatJet()  # reads FORMATJET_API_KEY
+result = formatjet.convert("report.docx", conversion="word-to-pdf")
+result.file.save("report.pdf")
+"""
+
+from ._client import (
+    DEFAULT_BASE_URL,
+    ConvertResult,
+    FileInput,
+    FormatJet,
+    JobPage,
+    Jobs,
+    OutputFile,
+    filename_from,
+)
+from ._errors import FormatJetError
+from ._webhooks import (
+    DEFAULT_TOLERANCE_SECONDS,
+    SIGNATURE_HEADER,
+    WebhookSignatureError,
+    WebhookVerification,
+    parse_webhook,
+    verify_webhook,
+)
+from .openapi.models import Job, JobSummary, Upload
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "SIGNATURE_HEADER",
+    "ConvertResult",
+    "FileInput",
+    "FormatJet",
+    "FormatJetError",
+    "Job",
+    "JobPage",
+    "JobSummary",
+    "Jobs",
+    "OutputFile",
+    "Upload",
+    "WebhookSignatureError",
+    "WebhookVerification",
+    "__version__",
+    "filename_from",
+    "parse_webhook",
+    "verify_webhook",
+]

formatjet/_client.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import uuid
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO, Any, Self, TypeAlias
+from urllib.parse import unquote
+
+import httpx
+
+from ._errors import FormatJetError, error_from_response
+from ._transport import RetryTransport
+from ._webhooks import parse_webhook, verify_webhook
+from .openapi import AuthenticatedClient
+from .openapi.models import Job, JobOutputsItem, JobSummary, Upload
+
+DEFAULT_BASE_URL = "https://api.formatjet.com"
+TERMINAL = frozenset({"completed", "failed", "canceled"})
+DEFAULT_WAIT_SECONDS = 15 * 60.0
+DOWNLOADS_AT_ONCE = 4
+
+#: A file: a path, its bytes, a binary file object, or ``(filename, any of those)`` to name it.
+FileInput: TypeAlias = str | os.PathLike[str] | bytes | bytearray | memoryview | IO[bytes] | tuple[str, Any]
+
+
+@dataclass(frozen=True)
+class OutputFile:
+    #: The file's name, from the input's and the conversion's.
+    filename: str | None
+    mime: str
+    data: bytes
+
+    def save(self, path: str | os.PathLike[str] | None = None) -> Path:
+        """Writes the file to ``path``, or under its own name in the current folder."""
+        target = Path(path) if path is not None else Path(Path(self.filename or "output").name)
+        target.write_bytes(self.data)
+        return target
+
+
+@dataclass(frozen=True)
+class ConvertResult:
+    job_id: str
+    #: Every converted file in order: several for Split PDF, a PDF's pages as images and the like.
+    files: list[OutputFile]
+    #: Credits charged: none with a test key.
+    credits: float
+    #: The engine and its version, such as ``office libreoffice-25.8+runner-7``.
+    engine: str | None
+    #: The job, when the API answered with it (several files, or a wait past 30 seconds).
+    job: Job | None
+
+    @property
+    def file(self) -> OutputFile:
+        """The first (usually the only) converted file."""
+        return self.files[0]
+
+
+@dataclass(frozen=True)
+class JobPage:
+    data: list[JobSummary]
+    #: Pass it back as ``cursor`` for the next page; ``None`` on the last.
+    next_cursor: str | None
+
+
+@dataclass
+class _Prepared:
+    filename: str | None
+    size: int
+    open: Callable[[], bytes | IO[bytes]]
+
+
+def _prepare(file: FileInput, filename: str | None = None) -> _Prepared:
+    if isinstance(file, tuple):
+        name, data = file
+        return _prepare(data, filename or name)
+    if isinstance(file, (bytes, bytearray, memoryview)):
+        data = bytes(file)
+        return _Prepared(filename, len(data), lambda: data)
+    if isinstance(file, (str, os.PathLike)):
+        path = Path(file)
+        return _Prepared(filename or path.name, path.stat().st_size, lambda: path.open("rb"))
+    if hasattr(file, "read"):
+        data = file.read()
+        own = getattr(file, "name", None)
+        name = filename or (Path(own).name if isinstance(own, str) else None)
+        return _Prepared(name, len(data), lambda: data)
+    raise TypeError("A file is a path, bytes, a binary file object, or (filename, one of those).")
+
+
+def _step(
+    conversion: str | None,
+    to: str | None,
+    from_: str | None,
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    if not conversion and not to:
+        raise ValueError("Name the conversion, or the format to make (`to`).")
+    step: dict[str, Any] = {"op": "convert"}
+    if conversion:
+        step["conversion"] = conversion
+    if from_:
+        step["from"] = from_
+    if to:
+        step["to"] = to
+    if options:
+        step["options"] = dict(options)
+    return step
+
+
+def filename_from(header: str | None) -> str | None:
+    """The name in a ``Content-Disposition`` header (``filename*`` first, as RFC 6266 says)."""
+    if not header:
+        return None
+    extended = re.search(r"filename\*\s*=\s*UTF-8''([^;]+)", header, re.IGNORECASE)
+    if extended:
+        return unquote(extended.group(1).strip(), errors="strict") or None
+    plain = re.search(r'filename\s*=\s*"((?:[^"\\]|\\.)*)"|filename\s*=\s*([^;]+)', header, re.IGNORECASE)
+    if not plain:
+        return None
+    if plain.group(1) is not None:
+        return re.sub(r"\\(.)", r"\1", plain.group(1)) or None
+    return plain.group(2).strip() or None
+
+
+def _close(content: bytes | IO[bytes]) -> None:
+    if not isinstance(content, bytes):
+        content.close()
+
+
+class Jobs:
+    """Jobs: make, read, list, wait for, cancel and delete them."""
+
+    def __init__(self, http: httpx.Client, sleep: Callable[[float], None]) -> None:
+        self._http = http
+        self._sleep = sleep
+
+    def _json(self, method: str, url: str, **kwargs: Any) -> Any:
+        response = self._http.request(method, url, **kwargs)
+        if not response.is_success:
+            raise error_from_response(response)
+        return response.json()
+
+    def create(self, request: Mapping[str, Any], *, idempotency_key: str | None = None) -> Job:
+        """Makes a job (``POST /v1/jobs``) from a request as the API reference describes it. It
+        starts at once; wait for it with ``wait()``."""
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return Job.from_dict(self._json("POST", "/v1/jobs", json=dict(request), headers=headers))
+
+    def get(self, job_id: str) -> Job:
+        return Job.from_dict(self._json("GET", f"/v1/jobs/{job_id}"))
+
+    def list(self, *, limit: int | None = None, cursor: str | None = None) -> JobPage:
+        """One page of jobs, newest first."""
+        params = {key: value for key, value in (("limit", limit), ("cursor", cursor)) if value is not None}
+        page = self._json("GET", "/v1/jobs", params=params)
+        return JobPage([JobSummary.from_dict(item) for item in page["data"]], page["next_cursor"])
+
+    def iterate(self, *, limit: int | None = None) -> Iterator[JobSummary]:
+        """Every job of the last 30 days, newest first, a page at a time."""
+        cursor: str | None = None
+        while True:
+            page = self.list(limit=limit, cursor=cursor)
+            yield from page.data
+            if not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    def cancel(self, job_id: str) -> Job:
+        """Cancels a job that hasn't finished."""
+        return Job.from_dict(self._json("POST", f"/v1/jobs/{job_id}/cancel"))
+
+    def delete(self, job_id: str) -> dict[str, Any]:
+        """Deletes a job's files now and returns the signed deletion receipt."""
+        receipt: dict[str, Any] = self._json("DELETE", f"/v1/jobs/{job_id}")["receipt"]
+        return receipt
+
+    def wait(
+        self,
+        job_id: str,
+        *,
+        timeout: float = DEFAULT_WAIT_SECONDS,
+        on_progress: Callable[[Job], None] | None = None,
+    ) -> Job:
+        """Reads the job until it has ended (completed, failed or canceled) and returns it,
+        whatever the outcome. Raises ``FormatJetError`` with code ``timeout`` after ``timeout``
+        seconds; the job carries on."""
+        until = time.monotonic() + timeout
+        pause = 0.5
+        while True:
+            job = self.get(job_id)
+            if job.status in TERMINAL:
+                return job
+            if on_progress:
+                on_progress(job)
+            if time.monotonic() + pause > until:
+                raise FormatJetError(
+                    "timeout",
+                    f"Job {job_id} was still {job.status} when the wait ran out; it carries on.",
+                    job_id=job_id,
+                )
+            self._sleep(pause)
+            pause = min(pause * 1.5, 5.0)
+
+
+class FormatJet:
+    """The FormatJet API.
+
+    ``convert()`` sends a file and gets the result in one request (up to 25 MB);
+    ``upload_and_convert()`` uploads it first, for files up to the plan's limit. ``jobs`` manages
+    jobs, ``verify_webhook()`` checks deliveries, and ``api`` is the generated client for every
+    endpoint (``formatjet.openapi.api``).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        max_retries: int = 2,
+        timeout: float = 300.0,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        """``api_key`` defaults to the ``FORMATJET_API_KEY`` environment variable. Requests that
+        get a 429, a 5xx answer or a network error are retried ``max_retries`` times; each takes
+        up to ``timeout`` seconds. ``transport`` replaces httpx's (tests)."""
+        key = api_key or os.environ.get("FORMATJET_API_KEY")
+        if not key:
+            raise ValueError("No API key: pass api_key or set FORMATJET_API_KEY.")
+        self.base_url = (base_url or os.environ.get("FORMATJET_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        retrying = RetryTransport(transport or httpx.HTTPTransport(), max_retries, sleep)
+        limits = httpx.Timeout(timeout)
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {key}"},
+            transport=retrying,
+            timeout=limits,
+        )
+        # Never send the key with a file: upload and download URLs are signed, and may be
+        # our storage's rather than the API's.
+        self._files = httpx.Client(transport=retrying, timeout=limits)
+        self._sleep = sleep
+        self.jobs = Jobs(self._http, sleep)
+        #: The generated client: pass it as ``client=`` to ``formatjet.openapi.api`` functions.
+        self.api = AuthenticatedClient(base_url=self.base_url, token=key).set_httpx_client(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+        self._files.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    verify_webhook = staticmethod(verify_webhook)
+    parse_webhook = staticmethod(parse_webhook)
+
+    def convert(
+        self,
+        file: FileInput | Sequence[FileInput],
+        *,
+        conversion: str | None = None,
+        to: str | None = None,
+        from_: str | None = None,
+        options: Mapping[str, Any] | None = None,
+        filename: str | None = None,
+        output_filename: str | None = None,
+        ttl: int | None = None,
+        idempotency_key: str | None = None,
+        timeout: float = DEFAULT_WAIT_SECONDS,
+    ) -> ConvertResult:
+        """Converts one file (or the files a joining conversion takes, as a list) in one
+        request, up to 25 MB in all, and returns the converted files. A job that runs past 30
+        seconds is waited for, up to ``timeout`` seconds."""
+        files = [_prepare(item) for item in file] if isinstance(file, list) else [_prepare(file, filename)]
+        step = _step(conversion, to, from_, options)
+        params: dict[str, str] = {key: step[key] for key in ("conversion", "from", "to") if key in step}
+        if "options" in step:
+            params["options"] = json.dumps(step["options"], separators=(",", ":"))
+        if output_filename:
+            params["output_filename"] = output_filename
+        if ttl is not None:
+            params["ttl"] = str(ttl)
+        contents = [prepared.open() for prepared in files]
+        try:
+            parts = [
+                ("file", (prepared.filename or "file", content, "application/octet-stream"))
+                for prepared, content in zip(files, contents, strict=True)
+            ]
+            response = self._http.post(
+                "/v1/convert",
+                params=params,
+                files=parts,
+                headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+            )
+        finally:
+            for content in contents:
+                _close(content)
+        if not response.is_success:
+            raise error_from_response(response)
+        mime = response.headers.get("Content-Type", "")
+        if "application/json" in mime:
+            # Several files, or still converting after 30 s: the job, which lists them or carries on.
+            job = Job.from_dict(response.json())
+            if job.status not in TERMINAL:
+                job = self.jobs.wait(job.id, timeout=timeout)
+            return self._result(job)
+        output = OutputFile(
+            filename_from(response.headers.get("Content-Disposition")),
+            mime or "application/octet-stream",
+            response.content,
+        )
+        return ConvertResult(
+            job_id=response.headers.get("FormatJet-Job-Id", ""),
+            files=[output],
+            credits=float(response.headers.get("FormatJet-Credits", "0")),
+            engine=response.headers.get("FormatJet-Engine"),
+            job=None,
+        )
+
+    def upload_and_convert(
+        self,
+        file: FileInput | Sequence[FileInput],
+        *,
+        conversion: str | None = None,
+        to: str | None = None,
+        from_: str | None = None,
+        options: Mapping[str, Any] | None = None,
+        filename: str | None = None,
+        output_filename: str | None = None,
+        ttl: int | None = None,
+        metadata: Mapping[str, str] | None = None,
+        webhook: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float = DEFAULT_WAIT_SECONDS,
+        on_progress: Callable[[Job], None] | None = None,
+    ) -> ConvertResult:
+        """Uploads the file (or the files to join, as a list), makes a job, waits for it and
+        downloads what it made. For files larger than ``convert()`` takes."""
+        files = [_prepare(item) for item in file] if isinstance(file, list) else [_prepare(file, filename)]
+        step = _step(conversion, to, from_, options)
+        refs = [{"upload_id": self._upload(prepared).id} for prepared in files]
+        request: dict[str, Any] = {"steps": [step]}
+        if len(refs) == 1:
+            request["input"] = refs[0]
+        else:
+            request["inputs"] = refs
+        output: dict[str, Any] = {}
+        if ttl is not None:
+            output["ttl"] = ttl
+        if output_filename:
+            output["filename"] = output_filename
+        if output:
+            request["output"] = output
+        if metadata:
+            request["metadata"] = dict(metadata)
+        if webhook:
+            request["webhook"] = webhook
+        created = self.jobs.create(request, idempotency_key=idempotency_key)
+        return self._result(self.jobs.wait(created.id, timeout=timeout, on_progress=on_progress))
+
+    def upload(self, file: FileInput, *, filename: str | None = None) -> Upload:
+        """Makes an upload and PUTs the file to it. Name it in a job's ``input``
+        (``{"upload_id": upload.id}``) within the hour."""
+        return self._upload(_prepare(file, filename))
+
+    def download(self, output: JobOutputsItem) -> OutputFile:
+        """Downloads one of a job's outputs. Its URL needs no key and works until ``expires_at``."""
+        if not output.url:
+            raise FormatJetError("not_found", f"Output {output.id} has been deleted.")
+        response = self._files.get(output.url)
+        if not response.is_success:
+            raise error_from_response(response)
+        return OutputFile(output.filename, output.mime, response.content)
+
+    def _upload(self, prepared: _Prepared) -> Upload:
+        body: dict[str, Any] = {"size": prepared.size}
+        if prepared.filename:
+            body["filename"] = prepared.filename
+        response = self._http.post("/v1/uploads", json=body)
+        if not response.is_success:
+            raise error_from_response(response)
+        upload = Upload.from_dict(response.json())
+        content = prepared.open()
+        try:
+            headers = {**upload.headers.additional_properties, "Content-Length": str(prepared.size)}
+            put = self._files.request(str(upload.method), upload.url, content=content, headers=headers)
+        finally:
+            _close(content)
+        if not put.is_success:
+            raise error_from_response(put)
+        return upload
+
+    def _result(self, job: Job) -> ConvertResult:
+        if job.status == "failed":
+            error = job.error
+            raise FormatJetError(
+                error.code if error else "engine_failed",
+                error.detail if error else "The conversion failed.",
+                job_id=job.id,
+            )
+        if job.status == "canceled":
+            raise FormatJetError("canceled", f"Job {job.id} was canceled.", job_id=job.id)
+        if not job.outputs:
+            raise FormatJetError("not_found", f"Job {job.id} has no outputs.", job_id=job.id)
+        with ThreadPoolExecutor(max_workers=DOWNLOADS_AT_ONCE) as pool:
+            files = list(pool.map(self.download, job.outputs))
+        engine = f"{job.engine} {job.engine_version or ''}".strip() if job.engine else None
+        return ConvertResult(job_id=job.id, files=files, credits=job.credits_, engine=engine, job=job)

formatjet/_errors.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+
+class FormatJetError(Exception):
+    """An error from the API (its problem document), a job that failed, or a wait that ran out.
+
+    Branch on ``code``: it's stable across versions (https://formatjet.com/docs/errors), while
+    the message is written for people. Besides the API's codes, ``timeout`` means the SDK stopped
+    waiting for a job (the job carries on) and ``canceled`` a job canceled while it waited.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        detail: str,
+        *,
+        status: int | None = None,
+        request_id: str | None = None,
+        job_id: str | None = None,
+        retry_after: int | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(f"{code}: {detail}")
+        self.code = code
+        self.detail = detail
+        #: The HTTP status, when the API answered with an error.
+        self.status = status
+        #: ``FormatJet-Request-Id``: quote it when you contact us.
+        self.request_id = request_id
+        #: The job the error belongs to, when there is one.
+        self.job_id = job_id
+        #: Seconds to wait before trying again (``Retry-After``).
+        self.retry_after = retry_after
+        #: The whole problem document, with ``errors`` for each field that failed validation.
+        self.problem = problem
+
+
+def retry_after_seconds(response: httpx.Response) -> int | None:
+    value = response.headers.get("Retry-After", "").strip()
+    return int(value) if value.isdigit() else None
+
+
+def error_from_response(response: httpx.Response) -> FormatJetError:
+    """The error for an answer that wasn't a success."""
+    response.read()
+    request_id = response.headers.get("FormatJet-Request-Id")
+    retry_after = retry_after_seconds(response)
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        body = None
+    if isinstance(body, dict) and isinstance(body.get("code"), str) and isinstance(body.get("status"), int):
+        return FormatJetError(
+            body["code"],
+            str(body.get("detail") or body.get("title") or ""),
+            status=response.status_code,
+            request_id=body.get("request_id") or request_id,
+            job_id=body.get("job_id"),
+            retry_after=retry_after,
+            problem=body,
+        )
+    # Not one of ours: a proxy's page, or an answer cut short.
+    code = {401: "unauthorized", 404: "not_found", 429: "rate_limited"}.get(response.status_code, "internal_error")
+    return FormatJetError(
+        code,
+        f"The API answered {response.status_code} {response.reason_phrase}".strip(),
+        status=response.status_code,
+        request_id=request_id,
+        retry_after=retry_after,
+    )

formatjet/_transport.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import random
+import time
+import uuid
+from collections.abc import Callable
+
+import httpx
+
+from ._errors import retry_after_seconds
+
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+#: A longer ``Retry-After`` is answered as an error rather than slept through.
+MAX_RETRY_AFTER_SECONDS = 60
+#: Bodies up to this size are kept in memory so a retry can send them again; larger ones
+#: (an upload from a file) are sent once.
+MAX_RETRIED_BODY = 64 * 1024 * 1024
+
+
+def backoff(attempt: int) -> float:
+    """Half a second, doubling, with up to a quarter of a second's jitter."""
+    return 0.5 * 2**attempt + random.random() * 0.25
+
+
+class RetryTransport(httpx.BaseTransport):
+    """Retries 429s, 5xx answers and network errors, and gives each POST an Idempotency-Key
+    (the same on every retry), so a retry never makes a second job."""
+
+    def __init__(
+        self,
+        inner: httpx.BaseTransport,
+        max_retries: int,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._inner = inner
+        self._max_retries = max_retries
+        self._sleep = sleep
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and "Idempotency-Key" not in request.headers:
+            request.headers["Idempotency-Key"] = str(uuid.uuid4())
+        length = int(request.headers.get("Content-Length") or 0)
+        retries = self._max_retries if length <= MAX_RETRIED_BODY else 0
+        if retries:
+            request.read()
+        attempt = 0
+        while True:
+            try:
+                response = self._inner.handle_request(request)
+            except httpx.TransportError:
+                if attempt >= retries:
+                    raise
+                self._sleep(backoff(attempt))
+                attempt += 1
+                continue
+            if response.status_code not in RETRY_STATUSES or attempt >= retries:
+                return response
+            wait = retry_after_seconds(response)
+            if wait is not None and wait > MAX_RETRY_AFTER_SECONDS:
+                return response
+            response.close()
+            self._sleep(backoff(attempt) if wait is None else wait)
+            attempt += 1
+
+    def close(self) -> None:
+        self._inner.close()