| Name | gotenberg-client JSON |
| Version |
0.8.2
JSON |
| download |
| home_page | None |
| Summary | A Python client for interfacing with the Gotenberg API |
| upload_time | 2024-12-17 19:44:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
api
client
html
pdf
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Gotenberg API Client
[](https://pypi.org/project/gotenberg-client)
[](https://pypi.org/project/gotenberg-client)
[](https://codecov.io/gh/stumpylog/gotenberg-client)
---
## Table of Contents
- [Installation](#installation)
- [What](#what)
- [Why](#why)
- [Features](#features)
- [How](#how)
- [Examples](#examples)
- [License](#license)
## Installation
```console
pip install gotenberg-client
```
## What
This is a Python client for interfacing with [Gotenberg](https://gotenberg.dev/), which in turn is a wrapper around
powerful tools for PDF generation and creation in various ways, using a stateless API. It's a very powerful tool
to generate and manipulate PDFs.
## Why
As far as I can tell, no active Python library exists to interface with the Gotenberg API.
### Features
- HTTP/2 enabled by default
- Abstract away the handling of multi-part/form-data and deal with `Path`s instead
- Based on the modern [httpx](https://github.com/encode/httpx) library
- Full support for type hinting and concrete return types as much as possible
- Nearly full test coverage run against an actual Gotenberg server for multiple Python and PyPy versions
## How
All the routes and options from the Gotenberg routes are implemented, with the exception of the Prometheus metrics
endpoint. All the routes use the same format and general idea.
1. First, you add the file or files you want to process
1. Then, configure the endpoint with its various options the route supports
1. Finally, run the route and receive your resulting file
- Files will be PDF or ZIP, depending on what endpoint and its configuration. Endpoints which handle
multiple files, but don't merge them, return a ZIP archive of the resulting PDFs
For more detailed examples, check the [documentation](https://stumpylog.github.io/gotenberg-client/latest/)
### Examples
Converting a single HTML file into a PDF:
```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"))
```
Converting an HTML file with additional resources into a PDF:
```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"))
```
Converting an HTML file with additional resources into a PDF/A1a format:
```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"]).pdf_format(PdfAFormat.A2b).run()
response.to_file(Path("my-index.pdf"))
```
Converting a URL into PDF, in landscape format
```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"))
```
Adding metadata to a PDF:
This example shows how to add metadata to your generated PDF. All metadata fields are optional and include:
- Document info (title, author, subject, keywords)
- Dates (creation, modification)
- Technical details (pdf version, creator, producer)
- PDF standards (trapped status, marked status)
```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(),
trapped="Unknown"
)
.run())
response.to_file(Path("my-index.pdf"))
```
To ensure the proper clean up of all used resources, both the client and the route(s) should be
used as context manager. If for some reason you cannot, you should `.close` the client and any
routes:
```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()
```
The response from any `.run()` or `.run_with_retry()` will be either a `SingleFileResponse` or `ZipFileResponse`.
There provide a slimmed down set of fields from an `httpx.Response`, including the headers, the status code and
the response content. They also provide two convenience methods:
- `to_file` - Accepts a path and writes the content of the response to it
- `extract_to` - Only on a `ZipFileResponse`, extracts the zip into the given directory (which must exist)
## License
`gotenberg-client` is distributed under the terms of the [MPL 2.0](https://spdx.org/licenses/MPL-2.0.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "gotenberg-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "api, client, html, pdf",
"author": null,
"author_email": "Trenton H <rda0128ou@mozmail.com>",
"download_url": "https://files.pythonhosted.org/packages/33/93/7b6354144a6254f907c7d313382912767ee457a7e5ccf0a50c8e8d0a1316/gotenberg_client-0.8.2.tar.gz",
"platform": null,
"description": "# Gotenberg API Client\n\n[](https://pypi.org/project/gotenberg-client)\n[](https://pypi.org/project/gotenberg-client)\n[](https://codecov.io/gh/stumpylog/gotenberg-client)\n\n---\n\n## Table of Contents\n\n- [Installation](#installation)\n- [What](#what)\n- [Why](#why)\n - [Features](#features)\n- [How](#how)\n - [Examples](#examples)\n- [License](#license)\n\n## Installation\n\n```console\npip install gotenberg-client\n```\n\n## What\n\nThis is a Python client for interfacing with [Gotenberg](https://gotenberg.dev/), which in turn is a wrapper around\npowerful tools for PDF generation and creation in various ways, using a stateless API. It's a very powerful tool\nto generate and manipulate PDFs.\n\n## Why\n\nAs far as I can tell, no active Python library exists to interface with the Gotenberg API.\n\n### Features\n\n- HTTP/2 enabled by default\n- Abstract away the handling of multi-part/form-data and deal with `Path`s instead\n- Based on the modern [httpx](https://github.com/encode/httpx) library\n- Full support for type hinting and concrete return types as much as possible\n- Nearly full test coverage run against an actual Gotenberg server for multiple Python and PyPy versions\n\n## How\n\nAll the routes and options from the Gotenberg routes are implemented, with the exception of the Prometheus metrics\nendpoint. All the routes use the same format and general idea.\n\n1. First, you add the file or files you want to process\n1. Then, configure the endpoint with its various options the route supports\n1. Finally, run the route and receive your resulting file\n\n- Files will be PDF or ZIP, depending on what endpoint and its configuration. Endpoints which handle\n multiple files, but don't merge them, return a ZIP archive of the resulting PDFs\n\nFor more detailed examples, check the [documentation](https://stumpylog.github.io/gotenberg-client/latest/)\n\n### Examples\n\nConverting a single HTML file into a PDF:\n\n```python\nfrom gotenberg_client import GotenbergClient\n\nwith GotenbergClient(\"http://localhost:3000\") as client:\n with client.chromium.html_to_pdf() as route:\n response = route.index(\"my-index.html\").run()\n response.to_file(Path(\"my-index.pdf\"))\n```\n\nConverting an HTML file with additional resources into a PDF:\n\n```python\nfrom gotenberg_client import GotenbergClient\n\nwith GotenbergClient(\"http://localhost:3000\") as client:\n with client.chromium.html_to_pdf() as route:\n response = route.index(\"my-index.html\").resource(\"image.png\").resource(\"style.css\").run()\n response.to_file(Path(\"my-index.pdf\"))\n```\n\nConverting an HTML file with additional resources into a PDF/A1a format:\n\n```python\nfrom gotenberg_client import GotenbergClient\nfrom gotenberg_client.options import PdfAFormat\n\nwith GotenbergClient(\"http://localhost:3000\") as client:\n with client.chromium.html_to_pdf() as route:\n response = route.index(\"my-index.html\").resources([\"image.png\", \"style.css\"]).pdf_format(PdfAFormat.A2b).run()\n response.to_file(Path(\"my-index.pdf\"))\n```\n\nConverting a URL into PDF, in landscape format\n\n```python\nfrom gotenberg_client import GotenbergClient\nfrom gotenberg_client.options import PageOrientation\n\nwith GotenbergClient(\"http://localhost:3000\") as client:\n with client.chromium.url_to_pdf() as route:\n response = route.url(\"https://hello.world\").orient(PageOrientation.Landscape).run()\n response.to_file(Path(\"my-world.pdf\"))\n```\n\nAdding metadata to a PDF:\n\nThis example shows how to add metadata to your generated PDF. All metadata fields are optional and include:\n\n- Document info (title, author, subject, keywords)\n- Dates (creation, modification)\n- Technical details (pdf version, creator, producer)\n- PDF standards (trapped status, marked status)\n\n```python\nfrom gotenberg_client import GotenbergClient\nfrom datetime import datetime\n\nwith GotenbergClient(\"http://localhost:3000\") as client:\n with client.chromium.html_to_pdf() as route:\n response = (route\n .index(\"my-index.html\")\n .metadata(\n title=\"My Document\",\n author=\"John Doe\",\n subject=\"Example PDF\",\n keywords=[\"sample\", \"document\", \"test\"],\n creation_date=datetime.now(),\n trapped=\"Unknown\"\n )\n .run())\n response.to_file(Path(\"my-index.pdf\"))\n```\n\nTo ensure the proper clean up of all used resources, both the client and the route(s) should be\nused as context manager. If for some reason you cannot, you should `.close` the client and any\nroutes:\n\n```python\nfrom gotenberg_client import GotenbergClient\n\ntry:\n client = GotenbergClient(\"http://localhost:3000\")\n try:\n route = client.merge([\"myfile.pdf\", \"otherfile.pdf\"]).run()\n finally:\n route.close()\nfinally:\n client.close()\n```\n\nThe response from any `.run()` or `.run_with_retry()` will be either a `SingleFileResponse` or `ZipFileResponse`.\nThere provide a slimmed down set of fields from an `httpx.Response`, including the headers, the status code and\nthe response content. They also provide two convenience methods:\n\n- `to_file` - Accepts a path and writes the content of the response to it\n- `extract_to` - Only on a `ZipFileResponse`, extracts the zip into the given directory (which must exist)\n\n## License\n\n`gotenberg-client` is distributed under the terms of the [MPL 2.0](https://spdx.org/licenses/MPL-2.0.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client for interfacing with the Gotenberg API",
"version": "0.8.2",
"project_urls": {
"Changelog": "https://github.com/stumpylog/gotenberg-client/blob/main/CHANGELOG.md",
"Documentation": "https://stumpylog.github.io/gotenberg-client/",
"Issues": "https://github.com/stumpylog/gotenberg-client/issues",
"Source": "https://github.com/stumpylog/gotenberg-client/"
},
"split_keywords": [
"api",
" client",
" html",
" pdf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca5df6f1237d182e315a8b06479f06434bc66f97f0563562002aa62bf4474494",
"md5": "ead5d45ff67ffc8a6a445393805e1996",
"sha256": "2a873e7fa9c4e9790f03da0130b12fabdb2144fc4e54732ac1196cd5a6a7f110"
},
"downloads": -1,
"filename": "gotenberg_client-0.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ead5d45ff67ffc8a6a445393805e1996",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 32538,
"upload_time": "2024-12-17T19:44:05",
"upload_time_iso_8601": "2024-12-17T19:44:05.525246Z",
"url": "https://files.pythonhosted.org/packages/ca/5d/f6f1237d182e315a8b06479f06434bc66f97f0563562002aa62bf4474494/gotenberg_client-0.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "33937b6354144a6254f907c7d313382912767ee457a7e5ccf0a50c8e8d0a1316",
"md5": "5e1adb4d5ddfe93b7974da419d75031f",
"sha256": "58387c6ceed6f274113c524f79b4cdbd83d971d0972805fe0f1dac2b648e27db"
},
"downloads": -1,
"filename": "gotenberg_client-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "5e1adb4d5ddfe93b7974da419d75031f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 417584,
"upload_time": "2024-12-17T19:44:08",
"upload_time_iso_8601": "2024-12-17T19:44:08.414346Z",
"url": "https://files.pythonhosted.org/packages/33/93/7b6354144a6254f907c7d313382912767ee457a7e5ccf0a50c8e8d0a1316/gotenberg_client-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 19:44:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stumpylog",
"github_project": "gotenberg-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gotenberg-client"
}
