|
| 1 | +# Gotenberg Python Client |
| 2 | + |
| 3 | +This is a Python client for interfacing with [Gotenberg](https://gotenberg.dev/), which in turn is a wrapper around |
| 4 | +powerful tools for PDF generation and creation in various ways, using a stateless API. It's a very powerful tool |
| 5 | +to generate and manipulate PDFs. |
| 6 | + |
| 7 | +## Features |
| 8 | + |
| 9 | +- HTTP/2 enabled by default |
| 10 | +- Abstract away the handling of multi-part/form-data and deal with `Path`s instead |
| 11 | +- Based on the modern [httpx](https://github.com/encode/httpx) library |
| 12 | +- Full support for type hinting and concrete return types as much as possible |
| 13 | +- Nearly full test coverage run against an actual Gotenberg server for multiple Python and PyPy versions |
| 14 | + |
| 15 | +## Examples |
| 16 | + |
| 17 | +Converting a single HTML file into a PDF: |
| 18 | + |
| 19 | +```python |
| 20 | +from gotenberg_client import GotenbergClient |
| 21 | + |
| 22 | +with GotenbergClient("http://localhost:3000") as client: |
| 23 | + with client.chromium.html_to_pdf() as route: |
| 24 | + response = route.index("my-index.html").run() |
| 25 | + Path("my-index.pdf").write_bytes(response.content) |
| 26 | +``` |
| 27 | + |
| 28 | +Converting an HTML file with additional resources into a PDF: |
| 29 | + |
| 30 | +```python |
| 31 | +from gotenberg_client import GotenbergClient |
| 32 | + |
| 33 | +with GotenbergClient("http://localhost:3000") as client: |
| 34 | + with client.chromium.html_to_pdf() as route: |
| 35 | + response = route.index("my-index.html").resource("image.png").resource("style.css").run() |
| 36 | + Path("my-index.pdf").write_bytes(response.content) |
| 37 | +``` |
| 38 | + |
| 39 | +Converting an HTML file with additional resources into a PDF/A1a format: |
| 40 | + |
| 41 | +```python |
| 42 | +from gotenberg_client import GotenbergClient |
| 43 | +from gotenberg_client.options import PdfAFormat |
| 44 | + |
| 45 | +with GotenbergClient("http://localhost:3000") as client: |
| 46 | + with client.chromium.html_to_pdf() as route: |
| 47 | + response = route.index("my-index.html").resources(["image.png", "style.css"]).pdf_format(PdfAFormat.A1a).run() |
| 48 | + Path("my-index.pdf").write_bytes(response.content) |
| 49 | +``` |
| 50 | + |
| 51 | +Converting a URL into PDF, in landscape format |
| 52 | + |
| 53 | +```python |
| 54 | +from gotenberg_client import GotenbergClient |
| 55 | +from gotenberg_client.options import PageOrientation |
| 56 | + |
| 57 | +with GotenbergClient("http://localhost:3000") as client: |
| 58 | + with client.chromium.html_to_pdf() as route: |
| 59 | + response = route.url("https://hello.world").orient(PageOrientation.Landscape).run() |
| 60 | + Path("my-world.pdf").write_bytes(response.content) |
| 61 | +``` |
| 62 | + |
| 63 | +To ensure the proper clean up of all used resources, both the client and the route(s) should be |
| 64 | +used as context manager. If for some reason you cannot, you should `.close` the client and any |
| 65 | +routes: |
| 66 | + |
| 67 | +```python |
| 68 | +from gotenberg_client import GotenbergClient |
| 69 | + |
| 70 | +try: |
| 71 | + client = GotenbergClient("http://localhost:3000") |
| 72 | + try: |
| 73 | + route = client.merge(["myfile.pdf", "otherfile.pdf"]).run() |
| 74 | + finally: |
| 75 | + route.close() |
| 76 | +finally: |
| 77 | + client.close() |
| 78 | +``` |
0 commit comments