uvpdftool 0.1.0__py3-none-any.whl

uvpdftool/__init__.py

@@ -0,0 +1,26 @@
+"""The UV pdfTool API from Python: https://uvpdftool.com/developers"""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    ApiError,
+    Client,
+    CreatedJob,
+    Job,
+    JobFailedError,
+    Output,
+    Upload,
+    verify_webhook,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "ApiError",
+    "Client",
+    "CreatedJob",
+    "Job",
+    "JobFailedError",
+    "Output",
+    "Upload",
+    "verify_webhook",
+]
+__version__ = "0.1.0"

uvpdftool/client.py

@@ -0,0 +1,360 @@
+"""
+The UV pdfTool API from Python 3.9 and later, with the standard library only: create a job,
+upload the files, start it, wait for it, download the result, or do all of that with one
+call. Documentation: https://uvpdftool.com/developers
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import io
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, Callable, Dict, List, Optional, Sequence, Tuple, Union
+
+DEFAULT_BASE_URL = "https://uvpdftool.com/api/v1"
+__version__ = "0.1.0"
+
+ENDED = ("done", "failed", "cancelled")
+
+FileArg = Union[str, "os.PathLike[str]", Tuple[str, bytes, str], Tuple[str, BinaryIO, str, int]]
+"""A file to send: a path, or (name, bytes, content_type), or (name, file object, content_type, size)."""
+
+
+class ApiError(Exception):
+    """A refused request: the status, the code to switch on, the message to show."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        self.retry_after = retry_after
+
+
+@dataclass
+class Output:
+    name: str
+    size: int
+    content_type: str
+    url: Optional[str] = None
+
+
+@dataclass
+class Job:
+    id: str
+    tool: str
+    mode: str
+    state: str
+    progress: Optional[float]
+    error: Optional[Dict[str, Any]]
+    outputs: List[Output]
+    created_at: str
+    expires_at: str
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @staticmethod
+    def from_json(data: Dict[str, Any]) -> "Job":
+        return Job(
+            id=data["id"],
+            tool=data["tool"],
+            mode=data["mode"],
+            state=data["state"],
+            progress=data.get("progress"),
+            error=data.get("error"),
+            outputs=[
+                Output(o["name"], o["size"], o["contentType"], o.get("url"))
+                for o in data.get("outputs", [])
+            ],
+            created_at=data["createdAt"],
+            expires_at=data["expiresAt"],
+            raw=data,
+        )
+
+
+@dataclass
+class Upload:
+    name: str
+    method: str
+    url: str
+    headers: Dict[str, str]
+
+
+@dataclass
+class CreatedJob:
+    job: Job
+    uploads: List[Upload]
+
+
+class JobFailedError(Exception):
+    """A job that ended failed or cancelled; `job.error` says why."""
+
+    def __init__(self, job: Job) -> None:
+        if job.error:
+            super().__init__(f"{job.error.get('code')}: {job.error.get('message')}")
+        else:
+            super().__init__(f"The job ended {job.state} without a result.")
+        self.job = job
+
+
+def _normalise(file: FileArg) -> Tuple[str, Union[bytes, BinaryIO], str, int]:
+    if isinstance(file, (str, os.PathLike)):
+        path = os.fspath(file)
+        name = os.path.basename(path)
+        return name, open(path, "rb"), _content_type(name), os.path.getsize(path)
+    if len(file) == 3:
+        name, data, content_type = file  # type: ignore[misc]
+        if not isinstance(data, (bytes, bytearray)):
+            raise TypeError(f"{name}: give bytes, or a file object with its size.")
+        return name, bytes(data), content_type, len(data)
+    name, handle, content_type, size = file  # type: ignore[misc]
+    return name, handle, content_type, int(size)
+
+
+_TYPES = {
+    ".pdf": "application/pdf",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".doc": "application/msword",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".xls": "application/vnd.ms-excel",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".odt": "application/vnd.oasis.opendocument.text",
+    ".ods": "application/vnd.oasis.opendocument.spreadsheet",
+    ".odp": "application/vnd.oasis.opendocument.presentation",
+    ".rtf": "application/rtf",
+    ".txt": "text/plain",
+    ".csv": "text/csv",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".md": "text/markdown",
+    ".epub": "application/epub+zip",
+}
+
+
+def _content_type(name: str) -> str:
+    return _TYPES.get(os.path.splitext(name)[1].lower(), "application/octet-stream")
+
+
+class Client:
+    """The API client. `api_key` is uvp_live_… or uvp_test_…."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        if not api_key:
+            raise TypeError("An API key is needed: uvp_live_… or uvp_test_…")
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.user_agent = f"uvpdftool-python/{__version__}" + (f" {user_agent}" if user_agent else "")
+
+    # ------------------------------------------------------------------ reads
+
+    def tools(self) -> List[Dict[str, Any]]:
+        """The tools the API offers, with their limits and options."""
+        return self._request("GET", "/tools")["tools"]
+
+    def account(self) -> Dict[str, Any]:
+        """The key in use, the API tasks left, and today's test jobs."""
+        return self._request("GET", "/account")
+
+    # ------------------------------------------------------------------ jobs
+
+    def create_job(
+        self,
+        tool: str,
+        files: Sequence[FileArg],
+        options: Optional[Dict[str, Any]] = None,
+        retention_hours: Optional[int] = None,
+    ) -> CreatedJob:
+        """POST /jobs with the files declared; the answer holds an upload link per file."""
+        declared = []
+        for file in files:
+            name, data, content_type, size = _normalise(file)
+            if isinstance(data, io.IOBase) and isinstance(file, (str, os.PathLike)):
+                data.close()
+            declared.append({"name": name, "size": size, "contentType": content_type})
+        body: Dict[str, Any] = {"tool": tool, "files": declared}
+        if options is not None:
+            body["options"] = options
+        if retention_hours is not None:
+            body["retentionHours"] = retention_hours
+        data = self._request("POST", "/jobs", body)
+        return CreatedJob(
+            job=Job.from_json(data["job"]),
+            uploads=[Upload(u["name"], u["method"], u["url"], u["headers"]) for u in data["uploads"]],
+        )
+
+    def upload(self, upload: Upload, data: Union[bytes, BinaryIO, str, "os.PathLike[str]"]) -> None:
+        """PUTs the bytes (or a file's) to one upload link, as they are."""
+        if isinstance(data, (str, os.PathLike)):
+            with open(data, "rb") as handle:
+                payload: Union[bytes, BinaryIO] = handle.read()
+        else:
+            payload = data
+        if not isinstance(payload, (bytes, bytearray)):
+            payload = payload.read()
+        for attempt in range(1, 4):
+            request = urllib.request.Request(upload.url, data=bytes(payload), method=upload.method)
+            for key, value in upload.headers.items():
+                request.add_header(key, value)
+            request.add_header("Content-Length", str(len(payload)))
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout * 10):
+                    return
+            except urllib.error.HTTPError as error:
+                if error.code < 500 or attempt == 3:
+                    raise ApiError(error.code, "UPLOAD_FAILED", f"The upload of {upload.name} answered {error.code}.")
+            except urllib.error.URLError:
+                if attempt == 3:
+                    raise
+            time.sleep(0.5 * attempt)
+
+    def start_job(self, job_id: str) -> Job:
+        return Job.from_json(self._request("POST", f"/jobs/{job_id}/start")["job"])
+
+    def get_job(self, job_id: str) -> Job:
+        return Job.from_json(self._request("GET", f"/jobs/{job_id}")["job"])
+
+    def cancel_job(self, job_id: str) -> Job:
+        return Job.from_json(self._request("DELETE", f"/jobs/{job_id}")["job"])
+
+    def wait(
+        self,
+        job_id: str,
+        interval: float = 2.0,
+        timeout: Optional[float] = None,
+        on_progress: Optional[Callable[[float, Job], None]] = None,
+    ) -> Job:
+        """Reads the job until it ends; returns it done, or raises JobFailedError."""
+        started = time.monotonic()
+        last = -1.0
+        while True:
+            job = self.get_job(job_id)
+            if job.progress is not None and job.progress != last and on_progress:
+                last = job.progress
+                on_progress(job.progress, job)
+            if job.state == "done":
+                return job
+            if job.state in ENDED:
+                raise JobFailedError(job)
+            waited = time.monotonic() - started
+            if timeout is not None and waited > timeout:
+                raise TimeoutError(f"Still {job.state} after {int(waited)} s.")
+            time.sleep(interval if waited < 60 or interval != 2.0 else 5.0)
+
+    def run(
+        self,
+        tool: str,
+        files: Sequence[FileArg],
+        options: Optional[Dict[str, Any]] = None,
+        retention_hours: Optional[int] = None,
+        timeout: Optional[float] = None,
+        on_progress: Optional[Callable[[float, Job], None]] = None,
+    ) -> Job:
+        """Creates the job, uploads every file, starts it and waits for it."""
+        created = self.create_job(tool, files, options, retention_hours)
+        try:
+            for upload, file in zip(created.uploads, files):
+                name, data, _content_type, _size = _normalise(file)
+                try:
+                    self.upload(upload, data)
+                finally:
+                    if isinstance(data, io.IOBase) and isinstance(file, (str, os.PathLike)):
+                        data.close()
+            self.start_job(created.job.id)
+        except Exception:
+            # A job without its files would wait twenty minutes for them; end it now.
+            try:
+                self.cancel_job(created.job.id)
+            except Exception:
+                pass
+            raise
+        return self.wait(created.job.id, timeout=timeout, on_progress=on_progress)
+
+    def download(self, output: Output, path: Optional[Union[str, "os.PathLike[str]"]] = None) -> Optional[bytes]:
+        """The bytes of one output of a finished job, or written to `path`."""
+        if not output.url:
+            raise TypeError(f"{output.name} has no download link yet.")
+        request = urllib.request.Request(output.url, headers={"User-Agent": self.user_agent})
+        with urllib.request.urlopen(request, timeout=self.timeout * 10) as response:
+            data = response.read()
+        if path is None:
+            return data
+        with open(path, "wb") as handle:
+            handle.write(data)
+        return None
+
+    # ------------------------------------------------------------------ plumbing
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        for attempt in range(1, 3):
+            payload = json.dumps(body).encode() if body is not None else None
+            request = urllib.request.Request(self.base_url + path, data=payload, method=method)
+            request.add_header("Authorization", f"Bearer {self.api_key}")
+            request.add_header("Accept", "application/json")
+            request.add_header("User-Agent", self.user_agent)
+            if payload is not None:
+                request.add_header("Content-Type", "application/json")
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    text = response.read()
+                    return json.loads(text) if text else None
+            except urllib.error.HTTPError as error:
+                text = error.read()
+                try:
+                    problem = json.loads(text).get("error") or {}
+                except (ValueError, AttributeError):
+                    problem = {}
+                retry_after = error.headers.get("Retry-After")
+                seconds = int(retry_after) if retry_after and retry_after.isdigit() else None
+                failure = ApiError(
+                    error.code,
+                    problem.get("code", "HTTP_ERROR"),
+                    problem.get("message", f"The API answered {error.code}."),
+                    problem.get("details") or {},
+                    seconds,
+                )
+                # One minute's worth of requests spent: wait what the API asks, once.
+                if failure.code == "TOO_MANY_REQUESTS" and attempt == 1 and seconds:
+                    time.sleep(min(seconds, 60))
+                    continue
+                raise failure from None
+        raise AssertionError("unreachable")
+
+
+def verify_webhook(raw_body: bytes, signature_header: str, secret: str, tolerance: int = 300, now: Optional[float] = None) -> bool:
+    """True when a webhook body came from UV pdfTool, unchanged, within `tolerance` seconds of now."""
+    parts: Dict[str, str] = {}
+    for part in signature_header.split(","):
+        if "=" in part:
+            key, value = part.split("=", 1)
+            parts[key.strip()] = value.strip()
+    try:
+        t = int(parts["t"])
+    except (KeyError, ValueError):
+        return False
+    if abs((now if now is not None else time.time()) - t) > tolerance:
+        return False
+    if isinstance(raw_body, str):
+        raw_body = raw_body.encode("utf-8")
+    expected = hmac.new(secret.encode("utf-8"), f"{t}.".encode("utf-8") + raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, parts.get("v1", ""))

uvpdftool-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: uvpdftool
+Version: 0.1.0
+Summary: The UV pdfTool API from Python: compress, convert, OCR and check PDFs on UV pdfTool's servers.
+Author: UV ResearchLabs
+License-Expression: MIT
+Project-URL: Homepage, https://uvpdftool.com/developers
+Project-URL: Documentation, https://uvpdftool.com/developers/sdks
+Keywords: pdf,compress,ocr,convert,pdfa,api,uvpdftool
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# uvpdftool
+
+The [UV pdfTool API](https://uvpdftool.com/developers) from Python 3.9 and later: compress,
+convert, OCR and check PDFs on UV pdfTool's servers. The standard library only; type hints
+included.
+
+```sh
+pip install uvpdftool
+```
+
+```python
+import os
+
+from uvpdftool import Client, JobFailedError
+
+client = Client(api_key=os.environ["UVPDF_KEY"])
+
+# Creates the job, uploads the file, starts it and waits for it.
+job = client.run(
+    "compress",
+    files=["report.pdf"],
+    options={"method": "ghostscript", "preset": "ebook"},
+)
+
+for output in job.outputs:
+    client.download(output, output.name)
+```
+
+Make a key on the [API keys page](https://uvpdftool.com/developers/keys); a test key is free
+and marks its results. Keep the key on your server, never in a browser or an app.
+
+## What it does
+
+| Call                                                                                          | Does                                                                              |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `Client(api_key, base_url=None, timeout=60)`                                                  | The client.                                                                       |
+| `client.run(tool, files, options=None, retention_hours=None, timeout=None, on_progress=None)` | Create, upload, start, wait; returns the finished job or raises `JobFailedError`. |
+| `client.download(output, path=None)`                                                          | The bytes of one output, or written to `path`.                                    |
+| `client.create_job(tool, files, options=None, retention_hours=None)`                          | `POST /jobs`; `.job` and `.uploads`.                                              |
+| `client.upload(upload, data)`                                                                 | `PUT` the bytes (or a path's) to one link.                                        |
+| `client.start_job(id)`, `client.get_job(id)`, `client.cancel_job(id)`                         | The three job calls.                                                              |
+| `client.wait(id, interval=2.0, timeout=None, on_progress=None)`                               | Polls until the job ends.                                                         |
+| `client.tools()`, `client.account()`                                                          | `GET /tools`, `GET /account`.                                                     |
+| `verify_webhook(raw_body, signature_header, secret, tolerance=300)`                           | True when a webhook delivery is genuine and fresh.                                |
+
+A file is a path, or `(name, bytes, content_type)`, or `(name, file_object, content_type, size)`.
+A refused request raises `ApiError` (`status`, `code`, `message`, `details`, `retry_after`);
+a job that fails or is cancelled raises `JobFailedError` (`.job`, with `job.error`).
+
+The tools, their options and the errors are documented at
+<https://uvpdftool.com/developers>.

uvpdftool-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+uvpdftool/__init__.py,sha256=zFxZaOZjdJtZTCz3V4VmD7j7wuPtsA1h2HXwqEULACo,425
+uvpdftool/client.py,sha256=B2uRFkJbksxZd3GY9XBoet09dUzNxhbXT07vdhanDJY,13894
+uvpdftool-0.1.0.dist-info/licenses/LICENSE,sha256=xTZ84sfkh-WhOZ4GQbFM4nzuALxAS-2iDQMF9lrmyUc,1072
+uvpdftool-0.1.0.dist-info/METADATA,sha256=JViiwN1HmrDdOoBNsMHwIgJsanHTPf_QMKi9kPoCt_8,3931
+uvpdftool-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+uvpdftool-0.1.0.dist-info/top_level.txt,sha256=r7rAaOPa3-cCIXiKEJt3x9dEm67GEKoemJf-Lkyd4fc,10
+uvpdftool-0.1.0.dist-info/RECORD,,

uvpdftool-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

uvpdftool-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UV ResearchLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uvpdftool-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+uvpdftool