Gotenberg API Client

https://github.com/stumpylog/gotenberg-client
Admin
A Python client for interfacing with the Gotenberg API, providing a powerful and modern way to...
Tokens:21,245
Snippets:122
Trust Score:7.4
License:MPL-2.0
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Development Tools with uv

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/contributing.md

Installs 'hatch' and 'pre-commit' using the 'uv' package manager. These tools are essential for project management, testing, and code formatting.

```bash
uv tool install hatch pre-commit
```

--------------------------------

### Install Gotenberg Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/usage.md

Installs the Gotenberg client library using pip. This is the first step to using the library in your Python project.

```console
pip install gotenberg-client
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/contributing.md

Installs the 'uv' package manager using a curl script. uv is used for independent tool installations within the project.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
```

--------------------------------

### Convert Markdown to PDF with Gotenberg Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/usage.md

An example of converting a Markdown file to PDF using the Gotenberg client. It demonstrates chaining route configurations like setting page size and including resources.

```python
from gotenberg_client import GotenbergClient
from gotenberg_client.constants import A4

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.markdown_to_pdf() as route:
        response = (
            route.index("main.html")
            .markdown_file("readme.md")
            .size(A4)
            .resource("styles.css")
            .fail_on_exceptions()
            .run()
        )

```

--------------------------------

### Convert URL to PDF in Landscape

Source: https://github.com/stumpylog/gotenberg-client/blob/main/README.md

Illustrates converting a web URL directly into a PDF document with landscape orientation. This example uses the 'PageOrientation' option from 'gotenberg-client.options'.

```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"))
```

--------------------------------

### Convert HTML to PDF/A1a Format

Source: https://github.com/stumpylog/gotenberg-client/blob/main/README.md

Demonstrates converting an HTML file with resources to a PDF/A1a compliant format. This example utilizes the 'PdfAFormat' option from the 'gotenberg-client.options' module.

```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"])
      response.pdf_format(PdfAFormat.A2b).run()
      response.to_file(Path("my-index.pdf"))
```

--------------------------------

### Format and Lint Code with Hatch

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/contributing.md

Applies code formatting and linting rules to the project using 'hatch'. This command ensures code consistency and adherence to style guides.

```bash
hatch fmt
```

--------------------------------

### Convert HTML with Resources to PDF using Chromium

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/index.md

Converts an HTML file along with its associated resources (like images and CSS) into a PDF using the Chromium engine. This example demonstrates how to include external files that the HTML document depends on. The output is saved to a specified file path.

```python
from gotenberg_client import GotenbergClient

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

--------------------------------

### Convert URL to PDF in Landscape Format using Chromium

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/index.md

Converts a given URL into a PDF document with a landscape page orientation using the Chromium engine. This example demonstrates how to specify page layout options. The output is saved to a specified file path.

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

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

--------------------------------

### Convert HTML to PDF/A1a Format using Chromium

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/index.md

Converts an HTML file with additional resources into a PDF/A1a format using the Chromium engine. This example shows how to specify PDF/A compliance levels and include multiple resources. The output is saved to a specified file path.

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

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

--------------------------------

### Convert HTML to PDF with Gotenberg Client (Python)

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Shows various ways to convert HTML content to PDF using the Gotenberg Python client's Chromium module. Examples include basic conversion, adding resources like CSS and images, using string content, and applying headers, footers, and page options.

```python
from pathlib import Path
from gotenberg_client import GotenbergClient
from gotenberg_client.options import PdfAFormat, PageOrientation
from gotenberg_client.constants import A4

with GotenbergClient("http://localhost:3000") as client:
    # Basic HTML to PDF conversion
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("index.html")).run()
        response.to_file(Path("output.pdf"))

    # HTML with additional resources (CSS, images, fonts)
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("index.html"))
            .resource(Path("style.css"))
            .resource(Path("image.png"))
            .resource(Path("font.woff"))
            .run()
        )
        response.to_file(Path("styled-output.pdf"))

    # Using batch resources and string content
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("index.html"))
            .resources([Path("img1.png"), Path("img2.png")])  # Multiple resources
            .string_resource("<style>body{color:red}</style>", name="inline.css", mime_type="text/css")
            .run()
        )

    # HTML from string (no file needed)
    with client.chromium.html_to_pdf() as route:
        html_content = "<html><body><h1>Hello World</h1></body></html>"
        response = route.string_index(html_content).run()
        response.to_file(Path("from-string.pdf"))

    # With header and footer
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("content.html"))
            .header(Path("header.html"))
            .footer(Path("footer.html"))
            .run()
        )

    # With page options
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("index.html"))
            .size(A4)                                    # Page size (A4, Letter, Legal, etc.)
            .orient(PageOrientation.Landscape)           # Landscape or Portrait
            .pdf_format(PdfAFormat.A2b)                 # PDF/A format
            .run()
        )
```

--------------------------------

### Add Metadata to Generated PDF

Source: https://github.com/stumpylog/gotenberg-client/blob/main/README.md

Shows how to embed various metadata fields (title, author, dates, etc.) into a generated PDF from HTML. This example uses the `.metadata()` method of the route object.

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

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(),
                trapped="Unknown"
            )
            .run())
        response.to_file(Path("my-index.pdf"))
```

--------------------------------

### Merge Multiple PDF Files using Gotenberg Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/index.md

Merges a list of PDF files into a single PDF document using the Gotenberg client. This example shows manual client and route closing if context managers are not used. It requires a running Gotenberg instance.

```python
from gotenberg_client import GotenbergClient

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

--------------------------------

### Initialize Gotenberg Client (Python)

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Demonstrates how to initialize both synchronous and asynchronous Gotenberg clients. It shows usage with context managers for automatic resource management and manual management. Configuration options like host, timeout, HTTP/2, and authentication are illustrated.

```python
from gotenberg_client import GotenbergClient, AsyncGotenbergClient
from httpx import BasicAuth

# Synchronous client (recommended as context manager)
with GotenbergClient("http://localhost:3000") as client:
    # Use client.chromium, client.libre_office, client.merge, etc.
    pass

# With configuration options
with GotenbergClient(
    host="http://localhost:3000",
    timeout=60.0,              # Request timeout in seconds
    http2=True,                # Enable HTTP/2 (default)
    auth=BasicAuth("user", "password"),  # Optional basic auth
) as client:
    pass

# Asynchronous client
async with AsyncGotenbergClient("http://localhost:3000") as client:
    # Use await with async routes
    pass

# Manual resource management (if context managers aren't suitable)
client = GotenbergClient("http://localhost:3000")
try:
    route = client.chromium.html_to_pdf()
    try:
        response = route.index("my-file.html").run()
    finally:
        route.close()
finally:
    client.close()
```

--------------------------------

### Initialize Gotenberg Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/usage.md

Demonstrates how to initialize the GotenbergClient. It requires the host URL of the Gotenberg server and allows optional configuration for timeouts, logging, and HTTP/2 usage.

```python
import logging

class GotenbergClient:

    def __init__(
        self,
        host: str,
        *,
        timeout: float = 30.0,
        log_level: int = logging.ERROR,
        http2: bool = True,
    ):
        ....

```

--------------------------------

### Convert HTML to PDF (Sync/Async)

Source: https://github.com/stumpylog/gotenberg-client/blob/main/README.md

Demonstrates converting a single HTML file to a PDF using both synchronous and asynchronous Gotenberg client methods. Requires the 'gotenberg-client' library and a running Gotenberg instance.

```python
from gotenberg_client import GotenbergClient, AsyncGotenbergClient
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 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"))
```

--------------------------------

### Set Up Pre-commit Hooks

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/contributing.md

Initializes the pre-commit hooks for the project. This ensures code style and quality checks are performed automatically before commits.

```bash
prek install
```

--------------------------------

### Build Documentation with Hatch

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/contributing.md

Generates the project's documentation using 'hatch'. This command is used to build the Sphinx documentation or other configured documentation formats.

```bash
hatch run docs:build
```

--------------------------------

### Async PDF Conversion and Manipulation with Gotenberg Client

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Demonstrates asynchronous PDF operations using AsyncGotenbergClient, including HTML to PDF, URL to PDF with retries, LibreOffice conversion, and PDF merging. Requires an active Gotenberg instance and the 'gotenberg-client' library.

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

async def convert_documents():
    async with AsyncGotenbergClient("http://localhost:3000") as client:
        # HTML to PDF
        async with client.chromium.html_to_pdf() as route:
            response = await route.index(Path("page.html")).run()
            response.to_file(Path("output.pdf"))

        # URL to PDF with retry
        async with client.chromium.url_to_pdf() as route:
            response = await (
                route.url("https://example.com")
                .run_with_retry(max_retry_count=3)
            )

        # LibreOffice conversion
        async with client.libre_office.to_pdf() as route:
            response = await route.convert(Path("document.docx")).run()

        # Merge PDFs
        async with client.merge.merge() as route:
            response = await (
                route.merge([Path("a.pdf"), Path("b.pdf")])
                .run()
            )

asyncio.run(convert_documents())
```

--------------------------------

### Run Tests with Hatch

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/contributing.md

Executes the project's test suite using the 'hatch' build and task manager. This command verifies the functionality of the code.

```bash
hatch test
```

--------------------------------

### Configure Page Size and Margins for PDF Generation

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Shows how to configure page sizes and margins for PDF generation using GotenbergClient. Supports predefined sizes (A4, Letter) and custom dimensions with various measurement units. Requires the 'gotenberg-client' library.

```python
from pathlib import Path
from gotenberg_client import GotenbergClient
from gotenberg_client.options import (
    PageSize, Measurement, MeasurementUnitType, PageMarginsType
)
from gotenberg_client.constants import A4, Letter, Legal, Tabloid

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        # Using predefined page sizes
        response = route.index(Path("page.html")).size(A4).run()

    with client.chromium.html_to_pdf() as route:
        # Custom page size
        custom_size = PageSize(
            width=Measurement(8.5, MeasurementUnitType.Inches),
            height=Measurement(11, MeasurementUnitType.Inches)
        )
        response = route.index(Path("page.html")).size(custom_size).run()

    with client.chromium.html_to_pdf() as route:
        # Custom margins with different units
        margins = PageMarginsType(
            top=Measurement(1, MeasurementUnitType.Centimeters),
            bottom=Measurement(1, MeasurementUnitType.Centimeters),
            left=Measurement(20, MeasurementUnitType.Millimeters),
            right=Measurement(20, MeasurementUnitType.Millimeters)
        )
        response = route.index(Path("page.html")).margins(margins).run()

# Available measurement units:
# - MeasurementUnitType.Inches ("in")
# - MeasurementUnitType.Millimeters ("mm")
# - MeasurementUnitType.Centimeters ("cm")
# - MeasurementUnitType.Points ("pt")
# - MeasurementUnitType.Pixels ("px")
# - MeasurementUnitType.Percent ("pc")

# Predefined page sizes: A0, A1, A2, A3, A4, A5, A6, Letter, Legal, Tabloid, Ledge
```

--------------------------------

### Convert HTML with Resources to PDF

Source: https://github.com/stumpylog/gotenberg-client/blob/main/README.md

Shows how to convert an HTML file to PDF while including additional resources like images and CSS. This requires the 'gotenberg-client' library and specifies the HTML file and its associated 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"))
```

--------------------------------

### LibreOffice - Office Documents to PDF

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Documentation for converting office documents (e.g., DOCX, XLSX, PPTX) to PDF using the LibreOffice engine via the gotenberg-client.

```APIDOC
## LibreOffice - Office Documents to PDF

### Convert Office Document to PDF

- **Method**: `libre_office.to_pdf`
- **Description**: Converts various office document formats into PDF.

### Required Properties

Specify at least one of the following to provide the document(s) for conversion:

- `.convert(file_path: str)`: Converts a single document from a file path.
- `.convert_files(file_paths: list[str])`: Converts multiple documents from a list of file paths.
- `.convert_in_memory_file(data: bytes, name: str)`: Converts a document from in-memory bytes, requiring a file name.

### Optional Properties (Common LibreOffice Options)

Refer to the [LibreOffice Properties documentation](https://gotenberg.dev/docs/routes#libreoffice-properties) for a full list of available options, which may include:

- Page ranges
- Landscape/Portrait orientation
- Scaling
- And more...
```

--------------------------------

### Convert URL to PDF using Gotenberg Client

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Converts a given URL to a PDF document using the Chromium engine. Supports options like page orientation, render wait time, cookies for authentication, and custom HTTP headers. Requires the 'gotenberg-client' library.

```python
from pathlib import Path
from datetime import timedelta
from gotenberg_client import GotenbergClient
from gotenberg_client.options import PageOrientation, CookieJar

with GotenbergClient("http://localhost:3000") as client:
    # Basic URL to PDF
    with client.chromium.url_to_pdf() as route:
        response = route.url("https://example.com").run()
        response.to_file(Path("webpage.pdf"))

    # With page orientation and render wait
    with client.chromium.url_to_pdf() as route:
        response = (
            route.url("https://example.com")
            .orient(PageOrientation.Landscape)
            .render_wait(timedelta(seconds=2.0))  # Wait for JS to render
            .run()
        )
        response.to_file(Path("landscape-page.pdf"))

    # With cookies for authenticated pages
    with client.chromium.url_to_pdf() as route:
        cookie = CookieJar(
            name="session_id",
            value="abc123",
            domain=".example.com",
            path="/",
            secure=True,
            http_only=True,
            same_site="Strict"
        )
        response = (
            route.url("https://example.com/protected")
            .cookies([cookie])
            .run()
        )

    # With custom HTTP headers
    with client.chromium.url_to_pdf() as route:
        response = (
            route.url("https://api.example.com/report")
            .extra_http_headers({"Authorization": "Bearer token123"})
            .run()
        )
```

--------------------------------

### LibreOffice - Office Document to PDF Conversion

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Convert Office documents (e.g., DOCX, ODT, PPTX, XLSX) to PDF synchronously or asynchronously using LibreOffice.

```APIDOC
## POST /forms/libreoffice/convert/to/pdf

### Description
Converts an office document to a PDF document using LibreOffice.

### Method
POST

### Endpoint
/forms/libreoffice/convert/to/pdf

### Parameters
#### Query Parameters
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
- **file** (file) - Required - The office document file to convert.

### Response
#### Success Response (200)
- **file** (binary) - The generated PDF file.

#### Response Example
(Binary PDF content)
```

```APIDOC
## POST /forms/libreoffice/convert/to/pdf/async

### Description
Converts an office document to a PDF document asynchronously using LibreOffice.

### Method
POST

### Endpoint
/forms/libreoffice/convert/to/pdf/async

### Parameters
#### Query Parameters
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
- **file** (file) - Required - The office document file to convert.

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### Use Gotenberg Client as Context Manager

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/usage.md

Shows how to use the GotenbergClient as a context manager for proper connection cleanup. This ensures that resources are released automatically when exiting the 'with' block.

```python
from gotenberg_client import GotenbergClient

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        ....

```

--------------------------------

### Convert LibreOffice Documents to PDF using Gotenberg Client

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Converts various LibreOffice document formats (DOCX, ODT, XLSX, ODS, PPTX, etc.) to PDF. Supports single file conversion, merging multiple files into one PDF, or outputting separate PDFs as a ZIP archive. Also handles in-memory buffers and password-protected files. Requires the 'gotenberg-client' library.

```python
from pathlib import Path
from io import BytesIO
from gotenberg_client import GotenbergClient
from gotenberg_client.options import PageOrientation, PdfAFormat

with GotenbergClient("http://localhost:3000") as client:
    # Single document conversion
    with client.libre_office.to_pdf() as route:
        response = route.convert(Path("document.docx")).run()
        response.to_file(Path("document.pdf"))

    # With PDF/A format
    with client.libre_office.to_pdf() as route:
        response = (
            route.convert(Path("report.xlsx"))
            .pdf_format(PdfAFormat.A2b)
            .run()
        )
        response.to_file(Path("report.pdf"))

    # Multiple documents merged into one PDF
    with client.libre_office.to_pdf() as route:
        response = (
            route.convert_files([Path("doc1.docx"), Path("doc2.docx")])
            .do_merge()  # Merge into single PDF
            .run()
        )
        response.to_file(Path("merged.pdf"))

    # Multiple documents as separate PDFs (returns ZIP)
    with client.libre_office.to_pdf() as route:
        response = (
            route.convert_files([Path("doc1.docx"), Path("doc2.docx")])
            .no_merge()  # Keep separate
            .run()
        )
        # Response is a ZipFileResponse
        response.extract_to(Path("output_folder"))

    # Convert from in-memory buffer
    with client.libre_office.to_pdf() as route:
        doc_bytes = Path("document.docx").read_bytes()
        response = (
            route.convert_in_memory_file(
                data=BytesIO(doc_bytes),
                name="document.docx"
            )
            .run()
        )

    # With password-protected document
    with client.libre_office.to_pdf() as route:
        response = (
            route.convert(Path("protected.odt"))
            .password("secret123")
            .run()
        )

    # With advanced options
    with client.libre_office.to_pdf() as route:
        response = (
            route.convert(Path("document.docx"))
            .orient(PageOrientation.Landscape)
            .page_ranges("1-4")
            .lossless_image_compression(lossless_image_compression=True)
            .quality(90)
            .flatten()
            .run()
        )
```

--------------------------------

### Chromium - Screenshot from URL

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Take a screenshot of a URL synchronously or asynchronously using the Chromium engine.

```APIDOC
## POST /forms/chromium/screenshot/url

### Description
Takes a screenshot of a given URL using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/screenshot/url

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to take a screenshot of.

### Request Body
(No specific request body defined, parameters are typically sent as form data or query parameters)

### Response
#### Success Response (200)
- **file** (binary) - The generated image file (e.g., PNG).

#### Response Example
(Binary image content)
```

```APIDOC
## POST /forms/chromium/screenshot/url/async

### Description
Takes a screenshot of a given URL asynchronously using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/screenshot/url/async

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to take a screenshot of.

### Request Body
(No specific request body defined, parameters are typically sent as form data or query parameters)

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### Convert Office Documents to PDF using LibreOffice Route

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Shows how to convert office documents (like .docx) to PDF format using the LibreOffice route of the Gotenberg client. It supports converting single files, multiple files, or in-memory file data.

```python
# Example using convert()
# route.convert("mydoc.docx")

# Example using convert_files()
# route.convert_files(["mydoc.docx", "another.odt"])

# Example using convert_in_memory_file()
# with open("mydoc.docx", "rb") as f:
#     data = f.read()
# route.convert_in_memory_file(data, name="mydoc.docx")
```

--------------------------------

### Configure Screenshot Settings for Gotenberg Chromium Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Configures various settings for capturing screenshots of web pages using the Gotenberg Chromium module. Options include setting dimensions (`.width()`, `.height()`), clipping behavior (`.clip()`, `.clip_to_dimensions()`, `.no_clip_to_dimensions()`), output format (`.output_format()`), quality (`.quality()`), background handling (`.omit_background()`, `.hide_background()`, `.show_background()`), and image optimization (`.image_optimize()`, `.image_optimize_for_speed()`, `.image_optimize_for_quality()`).

```python
client.chromium.route_for_screenshot()
    .width(1024)
    .height(768)
    .clip()
    .output_format("png")
    .quality(80)
    .omit_background()
    .image_optimize_for_speed()
```

--------------------------------

### Configure Webhooks for Gotenberg Notifications

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Set up webhook URLs to receive asynchronous notifications from Gotenberg regarding the status of conversion tasks. This allows for decoupled processing and real-time updates.

```python
from gotenberg_client import GotenbergClient

with GotenbergClient("http://localhost:3000") as client:
    # Configure webhook URLs at client level
    client.add_webhook_url("https://myapp.com/webhook/success")
    client.add_error_webhook_url("https://myapp.com/webhook/error")
    client.set_webhook_http_method("POST")
    client.set_webhook_extra_headers({"Authorization": "Bearer token123"})

    # All subsequent requests will use these webhook settings
    with client.chromium.html_to_pdf() as route:
        response = route.index("large-document.html").run()
```

--------------------------------

### Convert HTML File to PDF using Gotenberg Chromium Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Converts an HTML file, along with its associated resources, into a PDF document. It requires an index file (HTML) to be set using `.index()` or `.string_index()`. Additional resources like CSS, images, or JavaScript can be included using `.resource()` or `.resources()`. String resources are also supported for text-based content.

```python
client.chromium.html_to_pdf()
    .index("index.html")
    .resource("file-here")
    .resources(["file1", "file2"])
    .string_resource("<html></html>")
```

--------------------------------

### Chromium - HTML to PDF Conversion

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Convert HTML content to a PDF document synchronously or asynchronously using the Chromium engine.

```APIDOC
## POST /forms/chromium/convert/html

### Description
Converts provided HTML content to a PDF document using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/convert/html

### Parameters
#### Query Parameters
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
- **html** (string) - Required - The HTML content to convert.

### Request Example
{
  "html": "<h1>Hello World</h1><p>This is a test.</p>"
}

### Response
#### Success Response (200)
- **file** (binary) - The generated PDF file.

#### Response Example
(Binary PDF content)
```

```APIDOC
## POST /forms/chromium/convert/html/async

### Description
Converts provided HTML content to a PDF document asynchronously using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/convert/html/async

### Parameters
#### Query Parameters
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
- **html** (string) - Required - The HTML content to convert.

### Request Example
{
  "html": "<h1>Hello World</h1><p>This is a test.</p>"
}

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### Chromium - Markdown to PDF Conversion

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Convert Markdown content to a PDF document synchronously or asynchronously using the Chromium engine.

```APIDOC
## POST /forms/chromium/convert/markdown

### Description
Converts provided Markdown content to a PDF document using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/convert/markdown

### Parameters
#### Query Parameters
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
- **markdown** (string) - Required - The Markdown content to convert.

### Request Example
{
  "markdown": "# Hello World\n\nThis is a test."
}

### Response
#### Success Response (200)
- **file** (binary) - The generated PDF file.

#### Response Example
(Binary PDF content)
```

```APIDOC
## POST /forms/chromium/convert/markdown/async

### Description
Converts provided Markdown content to a PDF document asynchronously using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/convert/markdown/async

### Parameters
#### Query Parameters
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
- **markdown** (string) - Required - The Markdown content to convert.

### Request Example
{
  "markdown": "# Hello World\n\nThis is a test."
}

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### Convert Markdown to PDF using Gotenberg Client

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Converts Markdown files to PDF, optionally using an HTML template for styling. Supports single or multiple Markdown files and external resources like CSS. Requires the 'gotenberg-client' library.

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

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.markdown_to_pdf() as route:
        # The index.html wraps markdown content, e.g.:
        # <html><body>{{ toHTML "markdown.md" }}</body></html>
        response = (
            route.index(Path("template.html"))       # HTML template
            .markdown_file(Path("document.md"))      # Single markdown file
            .run()
        )
        response.to_file(Path("document.pdf"))

    # Multiple markdown files
    with client.chromium.markdown_to_pdf() as route:
        response = (
            route.index(Path("template.html"))
            .markdown_files([Path("chapter1.md"), Path("chapter2.md")])
            .resource(Path("style.css"))  # Optional CSS
            .run()
        )
```

--------------------------------

### PDF/A Conversion API

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Convert existing PDF files to the PDF/A archival format.

```APIDOC
## POST /convert/pdfa

### Description
Converts PDF documents to a specified PDF/A archival format.

### Method
POST

### Endpoint
/convert/pdfa

### Parameters
#### Query Parameters
- **pdf_a_format** (string) - Required - The target PDF/A format (e.g., 'A1b', 'A2b', 'A3b', 'A4f').

#### Request Body
- **files** (array of file paths) - Required - An array of PDF file paths to convert.

### Request Example
```json
{
  "files": ["document.pdf"],
  "pdf_a_format": "A2b"
}
```

### Response
#### Success Response (200)
- **file** (binary) - The converted PDF/A document or a zip archive of converted documents.

#### Response Example
(Binary PDF or zip archive content)
```

--------------------------------

### Chromium - Screenshot from HTML

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Take a screenshot of HTML content synchronously or asynchronously using the Chromium engine.

```APIDOC
## POST /forms/chromium/screenshot/html

### Description
Takes a screenshot of provided HTML content using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/screenshot/html

### Parameters
#### Query Parameters
(No specific query parameters defined)

### Request Body
- **html** (string) - Required - The HTML content to take a screenshot of.

### Request Example
{
  "html": "<h1>Hello World</h1><p>This is a test.</p>"
}

### Response
#### Success Response (200)
- **file** (binary) - The generated image file (e.g., PNG).

#### Response Example
(Binary image content)
```

```APIDOC
## POST /forms/chromium/screenshot/html/async

### Description
Takes a screenshot of provided HTML content asynchronously using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/screenshot/html/async

### Parameters
#### Query Parameters
(No specific query parameters defined)

### Request Body
- **html** (string) - Required - The HTML content to take a screenshot of.

### Request Example
{
  "html": "<h1>Hello World</h1><p>This is a test.</p>"
}

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### HTML to PDF Conversion API

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Convert HTML content to PDF using a headless Chromium browser. Supports metadata injection.

```APIDOC
## POST /chromium/convert/html

### Description
Converts HTML content to a PDF document using a headless Chromium browser. Allows for setting PDF metadata during conversion.

### Method
POST

### Endpoint
/chromium/convert/html

### Parameters
#### Request Body
- **index** (file path or URL) - Required - The path to the main HTML file or a URL to render.
- **metadata** (object) - Optional - An object containing metadata fields to embed in the PDF (e.g., title, author, subject).

### Request Example
```json
{
  "index": "report.html",
  "metadata": {
    "title": "Q4 Report",
    "author": "Marketing Team"
  }
}
```

### Response
#### Success Response (200)
- **file** (binary) - The generated PDF document.

#### Response Example
(Binary PDF content)
```

--------------------------------

### PDF/A & PDF/UA Conversion

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Convert existing PDF documents to PDF/A or PDF/UA formats synchronously or asynchronously.

```APIDOC
## POST /forms/pdfa/convert

### Description
Converts a PDF document to a specified archive format (PDF/A or PDF/UA).

### Method
POST

### Endpoint
/forms/pdfa/convert

### Parameters
#### Query Parameters
- **output_format** (string) - Required - The target format ('pdfa' or 'pdfua').

### Request Body
- **file** (file) - Required - The PDF file to convert.

### Response
#### Success Response (200)
- **file** (binary) - The converted PDF file.

#### Response Example
(Binary PDF content)
```

```APIDOC
## POST /forms/pdfa/convert/async

### Description
Converts a PDF document to a specified archive format (PDF/A or PDF/UA) asynchronously.

### Method
POST

### Endpoint
/forms/pdfa/convert/async

### Parameters
#### Query Parameters
- **output_format** (string) - Required - The target format ('pdfa' or 'pdfua').

### Request Body
- **file** (file) - Required - The PDF file to convert.

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### Convert HTML to PDF using Chromium

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/index.md

Converts a single HTML file into a PDF using the Chromium engine. It requires the `gotenberg-client` library and assumes a running Gotenberg instance. The output is saved to a specified file path.

```python
from gotenberg_client import GotenbergClient

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

--------------------------------

### Chromium - Screenshot from Markdown

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Take a screenshot of Markdown content synchronously or asynchronously using the Chromium engine.

```APIDOC
## POST /forms/chromium/screenshot/markdown

### Description
Takes a screenshot of provided Markdown content using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/screenshot/markdown

### Parameters
#### Query Parameters
(No specific query parameters defined)

### Request Body
- **markdown** (string) - Required - The Markdown content to take a screenshot of.

### Request Example
{
  "markdown": "# Hello World\n\nThis is a test."
}

### Response
#### Success Response (200)
- **file** (binary) - The generated image file (e.g., PNG).

#### Response Example
(Binary image content)
```

```APIDOC
## POST /forms/chromium/screenshot/markdown/async

### Description
Takes a screenshot of provided Markdown content asynchronously using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/screenshot/markdown/async

### Parameters
#### Query Parameters
(No specific query parameters defined)

### Request Body
- **markdown** (string) - Required - The Markdown content to take a screenshot of.

### Request Example
{
  "markdown": "# Hello World\n\nThis is a test."
}

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### Convert Markdown Files to PDF using Gotenberg Chromium Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Converts Markdown files into a PDF document. Similar to HTML conversion, it requires an index file (HTML) to be specified using `.index()` or `.string_index()`. Optional resources can be added using `.resource()` or `.resources()`, and text-based string resources can be included with `.string_resource()`.

```python
client.chromium.markdown_to_pdf()
    .index("index.html")
    .resource("file-here")
    .resources(["file1", "file2"])
    .string_resource("<html></html>")
```

--------------------------------

### Chromium - URL to PDF Conversion

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/ref_routes.md

Convert a URL to a PDF document synchronously or asynchronously using the Chromium engine.

```APIDOC
## POST /forms/chromium/convert/url

### Description
Converts a given URL to a PDF document using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/convert/url

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to convert.
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
(No specific request body defined, parameters are typically sent as form data or query parameters)

### Response
#### Success Response (200)
- **file** (binary) - The generated PDF file.

#### Response Example
(Binary PDF content)
```

```APIDOC
## POST /forms/chromium/convert/url/async

### Description
Converts a given URL to a PDF document asynchronously using the Chromium engine.

### Method
POST

### Endpoint
/forms/chromium/convert/url/async

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to convert.
- **pdfa** (boolean) - Optional - Whether to convert to PDF/A format.
- **pdfua** (boolean) - Optional - Whether to convert to PDF/UA format.

### Request Body
(No specific request body defined, parameters are typically sent as form data or query parameters)

### Response
#### Success Response (200)
- **location** (string) - The URL to poll for the result.

#### Response Example
{
  "location": "/api/status/your-job-id"
}
```

--------------------------------

### Header and Footer Configuration

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Configure custom HTML content for headers and footers in the generated PDF.

```APIDOC
## POST /forms/chromium/convert/url

### Description
This endpoint allows for the conversion of a URL to a PDF document with custom header and footer content.

### Method
POST

### Endpoint
/forms/chromium/convert/url

### Parameters
#### Query Parameters
- **header_html** (Path) - Optional - Path to an HTML file to be used as the header.
- **footer_html** (Path) - Optional - Path to an HTML file to be used as the footer.

### Request Example
```json
{
  "url": "https://example.com",
  "header_html": "/path/to/header.html",
  "footer_html": "/path/to/footer.html"
}
```

### Response
#### Success Response (200)
- **file** (binary) - The generated PDF file.

#### Response Example
(Binary PDF content)
```

--------------------------------

### Add PDF Metadata with Gotenberg Client

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Demonstrates how to add metadata such as title, author, creation date, and keywords to a PDF generated from HTML using the Gotenberg client. It requires the 'gotenberg-client' library and a running Gotenberg instance.

```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",
                creation_date=datetime.now(),
                keywords=["sample", "document"],
                subject="Sample PDF Generation",
                trapped="Unknown"
            )
            .run()
        )
```

--------------------------------

### Check Code Formatting with Hatch

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/contributing.md

Checks if the code adheres to the project's formatting standards without making changes. This is useful for CI pipelines.

```bash
hatch fmt --check
```

--------------------------------

### Page Properties Configuration

Source: https://github.com/stumpylog/gotenberg-client/blob/main/docs/routes.md

Configure various page properties such as size, margins, orientation, and scaling for PDF generation.

```APIDOC
## POST /forms/chromium/convert/url

### Description
This endpoint allows for the conversion of a URL to a PDF document with various page property configurations.

### Method
POST

### Endpoint
/forms/chromium/convert/url

### Parameters
#### Query Parameters
- **single_page** (bool) - Optional - Set to true to generate a PDF with a single page.
- **paper_width** (float) - Optional - Sets the width of the paper.
- **paper_height** (float) - Optional - Sets the height of the paper.
- **margin_top** (float) - Optional - Sets the top margin.
- **margin_bottom** (float) - Optional - Sets the bottom margin.
- **margin_left** (float) - Optional - Sets the left margin.
- **margin_right** (float) - Optional - Sets the right margin.
- **prefer_css_page_size** (bool) - Optional - If true, the CSS page size will be preferred.
- **print_background** (bool) - Optional - If true, background graphics will be printed.
- **omit_background** (bool) - Optional - If true, background graphics will be omitted.
- **landscape** (bool) - Optional - If true, the page orientation will be landscape.
- **scale** (int | float) - Optional - Scales the content of the PDF.
- **native_page_ranges** (str) - Optional - Specifies the page ranges to be included in the PDF.

### Request Example
```json
{
  "url": "https://example.com",
  "single_page": true,
  "paper_width": 210,
  "paper_height": 297,
  "margin_top": 10,
  "margin_bottom": 10,
  "margin_left": 10,
  "margin_right": 10,
  "prefer_css_page_size": false,
  "print_background": true,
  "omit_background": false,
  "landscape": false,
  "scale": 1,
  "native_page_ranges": "1-3,5"
}
```

### Response
#### Success Response (200)
- **file** (binary) - The generated PDF file.

#### Response Example
(Binary PDF content)
```

--------------------------------

### Manage PDF Metadata with Python

Source: https://context7.com/stumpylog/gotenberg-client/llms.txt

Read and write metadata (title, author, subject, keywords, dates) for PDF files using the Gotenberg client. Metadata can also be added during HTML to PDF conversion.

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

with GotenbergClient("http://localhost:3000") as client:
    # Read metadata from PDF
    with client.metadata.read() as route:
        metadata = route.read(Path("document.pdf")).run()
        # Returns dict: {"document.pdf": {"Title": "...", "Author": "...", ...}}
        print(metadata)

    # Write metadata to PDF
    with client.metadata.write() as route:
        response = (
            route.write(Path("document.pdf"))
            .metadata(
                title="Annual Report 2024",
                author="Jane Doe",
                subject="Financial Summary",
                keywords=["finance", "report", "2024"],
                creation_date=datetime.now(),
                creator="gotenberg-client",
            )
            .run()
        )
        response.to_file(Path("document-with-metadata.pdf"))

    # Add metadata during HTML conversion
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("report.html"))
            .metadata(
                title="Q4 Report",
                author="Marketing Team",
                subject="Quarterly Analysis"
            )
            .run()
        )
```
Tokens:
Raw