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>.
