uvpdftool 0.1.0__tar.gz

uvpdftool-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,51 @@
+# 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/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uvpdftool"
+version = "0.1.0"
+description = "The UV pdfTool API from Python: compress, convert, OCR and check PDFs on UV pdfTool's servers."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "UV ResearchLabs" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["pdf", "compress", "ocr", "convert", "pdfa", "api", "uvpdftool"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://uvpdftool.com/developers"
+Documentation = "https://uvpdftool.com/developers/sdks"
+
+[tool.setuptools]
+packages = ["uvpdftool"]

uvpdftool-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uvpdftool-0.1.0/tests/test_client.py

@@ -0,0 +1,262 @@
+"""The client against a stand-in API: the whole flow, the refusals, the webhook check."""
+
+import hashlib
+import hmac
+import json
+import os
+import sys
+import tempfile
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from uvpdftool import ApiError, Client, JobFailedError, verify_webhook  # noqa: E402
+
+
+class State:
+    def __init__(self):
+        self.jobs = {}
+        self.uploads = {}
+        self.requests = []
+        self.reads_until_done = 2
+        self.fail_next_upload = 0
+        self.rate_limit_once = False
+        self.origin = ""
+
+
+STATE = State()
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_args):
+        pass
+
+    def _send(self, status, body=None, headers=None):
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        for key, value in (headers or {}).items():
+            self.send_header(key, value)
+        payload = json.dumps(body).encode() if body is not None else b""
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _refuse(self, status, code, message):
+        self._send(status, {"error": {"code": code, "message": message}})
+
+    def _handle(self, method):
+        length = int(self.headers.get("Content-Length") or 0)
+        body = self.rfile.read(length) if length else b""
+        STATE.requests.append((method, self.path, self.headers.get("Authorization"), body))
+        if self.path.startswith("/upload/"):
+            if STATE.fail_next_upload > 0:
+                STATE.fail_next_upload -= 1
+                self._send(503)
+                return
+            STATE.uploads[self.path[len("/upload/"):]] = body
+            self._send(200)
+            return
+        if self.path.startswith("/download/"):
+            self.send_response(200)
+            self.send_header("Content-Type", "application/pdf")
+            self.send_header("Content-Length", "15")
+            self.end_headers()
+            self.wfile.write(b"%PDF-1.7 result")
+            return
+        if self.path == "/api/v1/tools":
+            self._send(200, {"tools": [{"id": "compress"}]})
+            return
+        auth = self.headers.get("Authorization") or ""
+        if not auth.startswith("Bearer uvp_"):
+            self._refuse(401, "API_KEY_MISSING", "Send your API key as a Bearer token.")
+            return
+        if STATE.rate_limit_once:
+            STATE.rate_limit_once = False
+            self._send(429, {"error": {"code": "TOO_MANY_REQUESTS", "message": "slow down"}}, {"Retry-After": "1"})
+            return
+        if self.path == "/api/v1/account":
+            self._send(200, {"key": {"name": "Test", "mode": "test", "prefix": "uvp_test_abcd", "scopes": ["jobs:read"]}, "tasks": 3, "test": {"left": 49, "perDay": 50}})
+            return
+        if self.path == "/api/v1/jobs" and method == "POST":
+            parsed = json.loads(body)
+            if parsed["tool"] == "nope":
+                self._refuse(503, "TOOL_UNAVAILABLE", "This tool is not available right now.")
+                return
+            job_id = f"job-{len(STATE.jobs) + 1}"
+            job = {
+                "id": job_id,
+                "tool": parsed["tool"],
+                "mode": "test",
+                "state": "created",
+                "progress": None,
+                "error": None,
+                "outputs": [],
+                "createdAt": "2026-10-28T10:15:00.000Z",
+                "expiresAt": "2026-10-28T10:35:00.000Z",
+            }
+            STATE.jobs[job_id] = job
+            uploads = [
+                {"name": f["name"], "method": "PUT", "url": f"{STATE.origin}/upload/{job_id}-{i}", "headers": {"Content-Type": f["contentType"]}}
+                for i, f in enumerate(parsed["files"])
+            ]
+            self._send(201, {"job": job, "uploads": uploads})
+            return
+        parts = self.path.split("/")
+        if len(parts) >= 5 and parts[3] == "jobs":
+            job = STATE.jobs.get(parts[4])
+            if job is None:
+                self._refuse(404, "NOT_FOUND", "No such job.")
+                return
+            if len(parts) == 6 and parts[5] == "start" and method == "POST":
+                if not any(key.startswith(job["id"]) for key in STATE.uploads):
+                    self._refuse(400, "UPLOAD_INCOMPLETE", "A file has not finished uploading.")
+                    return
+                job["state"] = "queued"
+                self._send(200, {"job": job})
+                return
+            if method == "DELETE":
+                job["state"] = "cancelled"
+                self._send(200, {"job": job})
+                return
+            if method == "GET":
+                if job["state"] in ("queued", "running"):
+                    STATE.reads_until_done -= 1
+                    if STATE.reads_until_done > 0:
+                        job["state"] = "running"
+                        job["progress"] = 0.5
+                    elif job["tool"] == "fails":
+                        job["state"] = "failed"
+                        job["error"] = {"code": "CORRUPT_PDF", "message": "The PDF is too damaged to read."}
+                    else:
+                        job["state"] = "done"
+                        job["progress"] = 1
+                        job["outputs"] = [{"name": "report.pdf", "size": 15, "contentType": "application/pdf", "url": f"{STATE.origin}/download/{job['id']}"}]
+                self._send(200, {"job": job})
+                return
+        self._refuse(405, "METHOD", "no")
+
+    def do_GET(self):
+        self._handle("GET")
+
+    def do_POST(self):
+        self._handle("POST")
+
+    def do_PUT(self):
+        self._handle("PUT")
+
+    def do_DELETE(self):
+        self._handle("DELETE")
+
+
+class ClientTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), Handler)
+        STATE.origin = f"http://127.0.0.1:{cls.server.server_port}"
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        cls.client = Client("uvp_test_key", base_url=f"{STATE.origin}/api/v1", timeout=5)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        STATE.requests.clear()
+        STATE.jobs.clear()
+        STATE.uploads.clear()
+        STATE.reads_until_done = 2
+        STATE.fail_next_upload = 0
+        STATE.rate_limit_once = False
+
+    def test_needs_a_key(self):
+        with self.assertRaises(TypeError):
+            Client("")
+
+    def test_reads(self):
+        self.assertEqual(self.client.tools()[0]["id"], "compress")
+        self.assertEqual(self.client.account()["tasks"], 3)
+        self.assertEqual(STATE.requests[-1][2], "Bearer uvp_test_key")
+
+    def test_runs_a_job_from_a_path_and_downloads(self):
+        seen = []
+        with tempfile.TemporaryDirectory() as folder:
+            path = os.path.join(folder, "report.pdf")
+            with open(path, "wb") as handle:
+                handle.write(b"%PDF-1.7 input")
+            job = self.client.run(
+                "compress", [path], options={"method": "ghostscript"}, retention_hours=5,
+                on_progress=lambda fraction, _job: seen.append(fraction),
+            )
+            self.assertEqual(job.state, "done")
+            self.assertEqual(seen, [0.5, 1])
+            methods = [(m, p) for m, p, _a, _b in STATE.requests]
+            self.assertEqual(methods, [
+                ("POST", "/api/v1/jobs"),
+                ("PUT", "/upload/job-1-0"),
+                ("POST", "/api/v1/jobs/job-1/start"),
+                ("GET", "/api/v1/jobs/job-1"),
+                ("GET", "/api/v1/jobs/job-1"),
+            ])
+            created = json.loads(STATE.requests[0][3])
+            self.assertEqual(created, {
+                "tool": "compress",
+                "files": [{"name": "report.pdf", "size": 14, "contentType": "application/pdf"}],
+                "options": {"method": "ghostscript"},
+                "retentionHours": 5,
+            })
+            self.assertEqual(STATE.uploads["job-1-0"], b"%PDF-1.7 input")
+            out = os.path.join(folder, "out.pdf")
+            self.client.download(job.outputs[0], out)
+            with open(out, "rb") as handle:
+                self.assertEqual(handle.read(), b"%PDF-1.7 result")
+        self.assertEqual(self.client.download(job.outputs[0]), b"%PDF-1.7 result")
+
+    def test_bytes_and_failures(self):
+        with self.assertRaises(JobFailedError) as failed:
+            self.client.run("fails", [("a.pdf", b"123", "application/pdf")])
+        self.assertEqual(failed.exception.job.error["code"], "CORRUPT_PDF")
+        with self.assertRaises(ApiError) as refused:
+            self.client.run("nope", [("a.pdf", b"1", "application/pdf")])
+        self.assertEqual((refused.exception.status, refused.exception.code), (503, "TOOL_UNAVAILABLE"))
+
+    def test_upload_retry_and_cancel(self):
+        STATE.fail_next_upload = 1
+        job = self.client.run("compress", [("b.pdf", b"9", "application/pdf")])
+        self.assertEqual(job.state, "done")
+        self.assertEqual(len([r for r in STATE.requests if r[0] == "PUT"]), 2)
+        STATE.fail_next_upload = 3
+        STATE.requests.clear()
+        with self.assertRaises(ApiError) as failed:
+            self.client.run("compress", [("c.pdf", b"9", "application/pdf")])
+        self.assertEqual(failed.exception.code, "UPLOAD_FAILED")
+        self.assertEqual(STATE.requests[-1][0], "DELETE")
+
+    def test_rate_limit_waited_out_once(self):
+        STATE.rate_limit_once = True
+        self.assertEqual(self.client.account()["tasks"], 3)
+        self.assertEqual(len(STATE.requests), 2)
+
+
+class WebhookTests(unittest.TestCase):
+    def test_verify(self):
+        secret = "whsec_test"
+        body = b'{"id":"1","type":"ping"}'
+        t = 1761646572
+
+        def sign(at):
+            digest = hmac.new(secret.encode(), f"{at}.".encode() + body, hashlib.sha256).hexdigest()
+            return f"t={at},v1={digest}"
+
+        now = float(t)
+        self.assertTrue(verify_webhook(body, sign(t), secret, now=now))
+        self.assertFalse(verify_webhook(body + b" ", sign(t), secret, now=now))
+        self.assertFalse(verify_webhook(body, sign(t), "other", now=now))
+        self.assertFalse(verify_webhook(body, sign(t - 1000), secret, now=now))
+        self.assertFalse(verify_webhook(body, "nonsense", secret, now=now))
+
+
+if __name__ == "__main__":
+    unittest.main()

uvpdftool-0.1.0/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-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/uvpdftool.egg-info/PKG-INFO

@@ -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/uvpdftool.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_client.py
+uvpdftool/__init__.py
+uvpdftool/client.py
+uvpdftool.egg-info/PKG-INFO
+uvpdftool.egg-info/SOURCES.txt
+uvpdftool.egg-info/dependency_links.txt
+uvpdftool.egg-info/top_level.txt

uvpdftool-0.1.0/uvpdftool.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

uvpdftool-0.1.0/uvpdftool.egg-info/top_level.txt

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