Metadata-Version: 2.4
Name: gotenberg-client
Version: 1.0.0
Summary: A Python client for interfacing with the Gotenberg API
Project-URL: Changelog, https://github.com/stumpylog/gotenberg-client/blob/main/CHANGELOG.md
Project-URL: Documentation, https://stumpylog.github.io/gotenberg-client/
Project-URL: Issues, https://github.com/stumpylog/gotenberg-client/issues
Project-URL: Source, https://github.com/stumpylog/gotenberg-client/
Author-email: Trenton H <rda0128ou@mozmail.com>
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: api,api-client,document-conversion,gotenberg,html,html-to-pdf,pdf,pdf-generation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: typing-extensions; python_version < '3.11'
Provides-Extra: httpx
Requires-Dist: httpx[http2]>=0.27; extra == 'httpx'
Provides-Extra: magic
Requires-Dist: python-magic; extra == 'magic'
Provides-Extra: niquests
Requires-Dist: niquests>=3; extra == 'niquests'
Provides-Extra: requests
Requires-Dist: requests>=2; extra == 'requests'
Description-Content-Type: text/markdown

# Gotenberg API Client

A modern, fully-typed Python client for the [Gotenberg](https://gotenberg.dev/) PDF generation API, with sync and async support.

[![PyPI - Version](https://img.shields.io/pypi/v/gotenberg-client.svg)](https://pypi.org/project/gotenberg-client)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/gotenberg-client.svg)](https://pypi.org/project/gotenberg-client)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/gotenberg-client)](https://pypi.org/project/gotenberg-client)
[![codecov](https://codecov.io/gh/stumpylog/gotenberg-client/graph/badge.svg?token=PH25G91Q6J)](https://codecov.io/gh/stumpylog/gotenberg-client)

---

## Quick Start

```console
pip install "gotenberg-client[httpx]"
```

```python
from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))
```

Four lines (excluding imports) to convert HTML to PDF.

## Why gotenberg-client?

[Gotenberg](https://gotenberg.dev/) is a powerful, Docker-based API for PDF generation and manipulation using
Chromium and LibreOffice under the hood. This client gives you a clean, Pythonic interface to all of its
capabilities, so you can skip the multipart form-data boilerplate and focus on your documents.

### Features

- **Fully typed** with concrete return types and full `py.typed` support
- **Sync and async** APIs with identical interfaces
- **Pluggable HTTP backends** -- [httpx](https://github.com/encode/httpx) (with HTTP/2), [niquests](https://github.com/jawah/niquests), or [requests](https://github.com/psf/requests) — install whichever you prefer
- **Pathlib-native** -- pass `Path` objects directly, no manual file handling
- **Thoroughly tested** against a real Gotenberg server across multiple Python versions
- **Broad route coverage** including Chromium, LibreOffice, PDF merge/convert/split, health checks, and more
    - If there's a route you need, just [ask](https://github.com/stumpylog/gotenberg-client/discussions/categories/ideas)!

## Installation

An HTTP backend is required. Pick the one that suits your project:

```console
pip install "gotenberg-client[httpx]"      # recommended — HTTP/2 and async support
pip install "gotenberg-client[niquests]"   # alternative — HTTP/2 and async support
pip install "gotenberg-client[requests]"   # sync-only
```

If you need MIME-type detection for automatic content-type headers, add the `magic` extra:

```console
pip install "gotenberg-client[httpx,magic]"
```

## Examples

### HTML to PDF

```python
from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))
```

### Async support

```python
from gotenberg_client import AsyncGotenbergClient
from pathlib import Path

async with AsyncGotenbergClient("http://localhost:3000") as client:
    async with client.chromium.html_to_pdf() as route:
        response = await route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))
```

### HTML with additional resources

```python
from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("my-index.html"))
            .resource("image.png")
            .resource("style.css")
            .run()
        )
        response.to_file(Path("my-index.pdf"))
```

### URL to PDF in landscape

```python
from gotenberg_client import GotenbergClient
from gotenberg_client.options import PageOrientation

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.url_to_pdf() as route:
        response = route.url("https://hello.world").orient(PageOrientation.Landscape).run()
        response.to_file(Path("my-world.pdf"))
```

### PDF/A output format

```python
from gotenberg_client import GotenbergClient
from gotenberg_client.options import PdfAFormat
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("my-index.html"))
            .resources(["image.png", "style.css"])
            .pdf_format(PdfAFormat.A2b)
            .run()
        )
        response.to_file(Path("my-index.pdf"))
```

### PDF metadata

```python
from gotenberg_client import GotenbergClient
from datetime import datetime

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index("my-index.html")
            .metadata(
                title="My Document",
                author="John Doe",
                subject="Example PDF",
                keywords=["sample", "document", "test"],
                creation_date=datetime.now(),
            )
            .run()
        )
        response.to_file(Path("my-index.pdf"))
```

### Choosing an HTTP backend

Install the backend you want, then select it explicitly (or rely on auto-detection):

```python
from gotenberg_client import GotenbergClient

# httpx — pip install "gotenberg-client[httpx]"
with GotenbergClient("http://localhost:3000", backend="httpx") as client:
    ...

# niquests — pip install "gotenberg-client[niquests]"
with GotenbergClient("http://localhost:3000", backend="niquests") as client:
    ...

# requests (sync-only) — pip install "gotenberg-client[requests]"
with GotenbergClient("http://localhost:3000", backend="requests") as client:
    ...

# auto — tries httpx first, then niquests (default)
with GotenbergClient("http://localhost:3000") as client:
    ...
```

### Basic authentication

```python
from gotenberg_client import GotenbergClient

with GotenbergClient("http://localhost:3000", auth=("user", "secret")) as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))
```

## How It Works

All routes follow the same pattern:

1. Add the file(s) you want to process
2. Configure options the route supports
3. Call `.run()` and receive your result

Responses are either a `SingleFileResponse` or `ZipFileResponse`, each providing:

- `to_file(path)` -- write the result to disk
- `extract_to(directory)` -- extract a ZIP result into a directory (ZipFileResponse only)
- Access to `headers`, `status_code`, and `content` from the underlying response

### Resource cleanup

Both the client and routes should be used as context managers for proper cleanup.
If that isn't possible, call `.close()` explicitly:

```python
from gotenberg_client import GotenbergClient
from pathlib import Path

client = GotenbergClient("http://localhost:3000")
try:
    route = client.merge.merge()
    try:
        response = route.merge([Path("myfile.pdf"), Path("otherfile.pdf")]).run()
        response.to_file(Path("merged.pdf"))
    finally:
        route.close()
finally:
    client.close()
```

## Documentation

For the full API reference and more examples, see the [documentation](https://stumpylog.github.io/gotenberg-client/latest/).

## License

`gotenberg-client` is distributed under the terms of the [MPL 2.0](https://spdx.org/licenses/MPL-2.0.html) license.
