gotenberg-client 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- gotenberg_client/__about__.py +4 -0
- gotenberg_client/__init__.py +6 -0
- gotenberg_client/_base.py +122 -0
- gotenberg_client/_client.py +72 -0
- gotenberg_client/_convert/__init__.py +3 -0
- gotenberg_client/_convert/chromium.py +174 -0
- gotenberg_client/_convert/common.py +31 -0
- gotenberg_client/_convert/libre_office.py +55 -0
- gotenberg_client/_convert/pdfa.py +34 -0
- gotenberg_client/_health.py +131 -0
- gotenberg_client/_merge.py +36 -0
- gotenberg_client/_metrics.py +3 -0
- gotenberg_client/_types_compat.py +10 -0
- gotenberg_client/_utils.py +42 -0
- gotenberg_client/options.py +101 -0
- gotenberg_client/py.typed +0 -0
- gotenberg_client-0.1.0.dist-info/METADATA +153 -0
- gotenberg_client-0.1.0.dist-info/RECORD +20 -0
- gotenberg_client-0.1.0.dist-info/WHEEL +4 -0
- gotenberg_client-0.1.0.dist-info/licenses/LICENSE +373 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MPL-2.0
|
|
4
|
+
from importlib.util import find_spec
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Dict
|
|
7
|
+
from typing import Optional
|
|
8
|
+
from typing import Union
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def optional_to_form(value: Optional[Union[bool, int, float, str]], name: str) -> Dict[str, str]:
|
|
12
|
+
"""
|
|
13
|
+
Quick helper to convert an optional type into a form data field
|
|
14
|
+
with the given name or no changes if the value is None
|
|
15
|
+
"""
|
|
16
|
+
if value is None:
|
|
17
|
+
return {}
|
|
18
|
+
else:
|
|
19
|
+
return {name: str(value).lower()}
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def guess_mime_type_stdlib(url: Path) -> Optional[str]:
|
|
23
|
+
"""
|
|
24
|
+
Uses the standard library to guess a mimetype
|
|
25
|
+
"""
|
|
26
|
+
import mimetypes
|
|
27
|
+
|
|
28
|
+
mime_type, _ = mimetypes.guess_type(url)
|
|
29
|
+
return mime_type
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def guess_mime_type_magic(url: Path) -> Optional[str]:
|
|
33
|
+
"""
|
|
34
|
+
Uses libmagic to guess the mimetype
|
|
35
|
+
"""
|
|
36
|
+
import magic # type: ignore
|
|
37
|
+
|
|
38
|
+
return magic.from_file(url, mime=True) # type: ignore
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
# Use the best option
|
|
42
|
+
guess_mime_type = guess_mime_type_magic if find_spec("magic") is not None else guess_mime_type_stdlib
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MPL-2.0
|
|
4
|
+
import dataclasses
|
|
5
|
+
import enum
|
|
6
|
+
from typing import Dict
|
|
7
|
+
from typing import Final
|
|
8
|
+
from typing import Optional
|
|
9
|
+
from typing import Union
|
|
10
|
+
|
|
11
|
+
from gotenberg_client._utils import optional_to_form
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@enum.unique
|
|
15
|
+
class PdfAFormat(enum.Enum):
|
|
16
|
+
A1a = enum.auto()
|
|
17
|
+
A2b = enum.auto()
|
|
18
|
+
A3b = enum.auto()
|
|
19
|
+
|
|
20
|
+
def to_form(self) -> Dict[str, str]:
|
|
21
|
+
if self.value == PdfAFormat.A1a.value:
|
|
22
|
+
return {"pdfFormat": "PDF/A-1a"}
|
|
23
|
+
elif self.value == PdfAFormat.A2b.value:
|
|
24
|
+
return {"pdfFormat": "PDF/A-2b"}
|
|
25
|
+
elif self.value == PdfAFormat.A3b.value:
|
|
26
|
+
return {"pdfFormat": "PDF/A-3b"}
|
|
27
|
+
else: # pragma: no cover
|
|
28
|
+
raise NotImplementedError(self.value)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@enum.unique
|
|
32
|
+
class PageOrientation(enum.Enum):
|
|
33
|
+
Landscape = enum.auto()
|
|
34
|
+
Portrait = enum.auto()
|
|
35
|
+
|
|
36
|
+
def to_form(self) -> Dict[str, str]:
|
|
37
|
+
if self.value == PageOrientation.Landscape.value:
|
|
38
|
+
return {"landscape": "true"}
|
|
39
|
+
elif self.value == PageOrientation.Portrait.value:
|
|
40
|
+
return {"landscape": "false"}
|
|
41
|
+
else: # pragma: no cover
|
|
42
|
+
raise NotImplementedError(self.value)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclasses.dataclass
|
|
46
|
+
class PageSize:
|
|
47
|
+
width: Optional[Union[float, int]] = None
|
|
48
|
+
height: Optional[Union[float, int]] = None
|
|
49
|
+
|
|
50
|
+
def to_form(self) -> Dict[str, str]:
|
|
51
|
+
data = optional_to_form(self.width, "paperWidth")
|
|
52
|
+
data.update(optional_to_form(self.height, "paperHeight"))
|
|
53
|
+
return data
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
# Define common paper sizes as shortcuts
|
|
57
|
+
A0: Final = PageSize(width=33.1, height=46.8)
|
|
58
|
+
A1: Final = PageSize(width=23.4, height=33.1)
|
|
59
|
+
A2: Final = PageSize(width=16.54, height=23.4)
|
|
60
|
+
A3: Final = PageSize(width=11.7, height=16.54)
|
|
61
|
+
A4: Final = PageSize(width=8.5, height=11)
|
|
62
|
+
A5: Final = PageSize(width=5.83, height=8.27)
|
|
63
|
+
A6: Final = PageSize(width=4.13, height=5.83)
|
|
64
|
+
Letter = A4
|
|
65
|
+
Legal: Final = PageSize(width=8.5, height=14)
|
|
66
|
+
Tabloid: Final = PageSize(width=11, height=17)
|
|
67
|
+
Ledge: Final = PageSize(width=17, height=11)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclasses.dataclass
|
|
71
|
+
class Margin:
|
|
72
|
+
top: Optional[Union[float, int]] = None
|
|
73
|
+
bottom: Optional[Union[float, int]] = None
|
|
74
|
+
left: Optional[Union[float, int]] = None
|
|
75
|
+
right: Optional[Union[float, int]] = None
|
|
76
|
+
|
|
77
|
+
def to_form(self) -> Dict[str, str]:
|
|
78
|
+
data = optional_to_form(self.top, "marginTop")
|
|
79
|
+
data.update(optional_to_form(self.bottom, "marginBottom"))
|
|
80
|
+
data.update(optional_to_form(self.left, "marginLeft"))
|
|
81
|
+
data.update(optional_to_form(self.right, "marginRight"))
|
|
82
|
+
return data
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
Gotenberg_Default_Margins: Final = Margin(0.39, 0.39, 0.39, 0.39)
|
|
86
|
+
Word_Default_Margins: Final = Margin(top=1.0, bottom=1.0, left=1.0, right=1.0)
|
|
87
|
+
Word_Narrow_Margins: Final = Margin(top=0.5, bottom=0.5, left=0.5, right=0.5)
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
@enum.unique
|
|
91
|
+
class EmulatedMediaType(str, enum.Enum):
|
|
92
|
+
Print = enum.auto()
|
|
93
|
+
Screen = enum.auto()
|
|
94
|
+
|
|
95
|
+
def to_form(self) -> Dict[str, str]:
|
|
96
|
+
if self.value == EmulatedMediaType.Print.value:
|
|
97
|
+
return {"emulatedMediaType": "print"}
|
|
98
|
+
elif self.value == EmulatedMediaType.Screen.value:
|
|
99
|
+
return {"emulatedMediaType": "screen"}
|
|
100
|
+
else: # pragma: no cover
|
|
101
|
+
raise NotImplementedError(self.value)
|
|
File without changes
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: gotenberg-client
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python client for interfacing with the Gotenberg API
|
|
5
|
+
Project-URL: Documentation, https://github.com/stumpylog/gotenberg-client/#readme
|
|
6
|
+
Project-URL: Issues, https://github.com/stumpylog/gotenberg-client/issues
|
|
7
|
+
Project-URL: Source, https://github.com/stumpylog/gotenberg-client/
|
|
8
|
+
Project-URL: Changelog, https://github.com/stumpylog/gotenberg-client/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Trenton H <rda0128ou@mozmail.com>
|
|
10
|
+
License-Expression: MPL-2.0
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Web Environment
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
23
|
+
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
24
|
+
Requires-Python: >=3.8
|
|
25
|
+
Requires-Dist: httpx[http2]~=0.24
|
|
26
|
+
Requires-Dist: typing-extensions; python_version < '3.11'
|
|
27
|
+
Provides-Extra: compression
|
|
28
|
+
Requires-Dist: httpx[brotli,http2]~=0.24; extra == 'compression'
|
|
29
|
+
Provides-Extra: magic
|
|
30
|
+
Requires-Dist: python-magic; extra == 'magic'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# Gotenberg API Client
|
|
34
|
+
|
|
35
|
+
[](https://pypi.org/project/gotenberg-client)
|
|
36
|
+
[](https://pypi.org/project/gotenberg-client)
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Table of Contents
|
|
41
|
+
|
|
42
|
+
- [Installation](#installation)
|
|
43
|
+
- [What](#what)
|
|
44
|
+
- [Why](#why)
|
|
45
|
+
- [Features](#features)
|
|
46
|
+
- [How](#how)
|
|
47
|
+
- [Examples](#examples)
|
|
48
|
+
- [License](#license)
|
|
49
|
+
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
```console
|
|
53
|
+
pip install gotenberg-client
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## What
|
|
57
|
+
|
|
58
|
+
This is a Python client for interfacing with [Gotenberg](https://gotenberg.dev/), which in turn is a wrapper around
|
|
59
|
+
powerful tools for PDF generation and creation in various ways, using a stateless API. It's a very powerful tool
|
|
60
|
+
to generate and manipulate PDFs.
|
|
61
|
+
|
|
62
|
+
## Why
|
|
63
|
+
|
|
64
|
+
As far as I can tell, no active Python library exists to interface with the Gotenberg API.
|
|
65
|
+
|
|
66
|
+
### Features
|
|
67
|
+
|
|
68
|
+
- HTTP/2 enabled by default
|
|
69
|
+
- Abstract away the handling of multi-part/form-data and deal with `Path`s instead
|
|
70
|
+
- Based on the modern [httpx](https://github.com/encode/httpx) library
|
|
71
|
+
- Full support for type hinting and concrete return types as mush as possible
|
|
72
|
+
- Nearly full test coverage run against an actual Gotenberg server for multiple Python and PyPy versions
|
|
73
|
+
|
|
74
|
+
## How
|
|
75
|
+
|
|
76
|
+
All the routes and options from the Gotenberg routes are implemented, with the exception of the Prometheus metrics
|
|
77
|
+
endpoint. All the routes use the same format and general idea.
|
|
78
|
+
|
|
79
|
+
1. First, you add the file or files you want to process
|
|
80
|
+
1. Then, configure the endpoint with its various options the route supports
|
|
81
|
+
1. Finally, run the route and receive your resulting file
|
|
82
|
+
|
|
83
|
+
- Files will be PDF or ZIP, depending on what endpoint and its configuration. Endpoints which handle
|
|
84
|
+
multiple files, but don't merge them, return a ZIP archive of the resulting PDFs
|
|
85
|
+
|
|
86
|
+
### Examples
|
|
87
|
+
|
|
88
|
+
Converting a single HTML file into a PDF:
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from gotenberg_client import GotenbergClient
|
|
92
|
+
|
|
93
|
+
with GotenbergClient("http://localhost:3000") as client:
|
|
94
|
+
with client.chromium.html_to_pdf() as route:
|
|
95
|
+
response = route.index("my-index.html").run()
|
|
96
|
+
Path("my-index.pdf").write_bytes(response.content)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Converting an HTML file with additional resources into a PDF:
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from gotenberg_client import GotenbergClient
|
|
103
|
+
|
|
104
|
+
with GotenbergClient("http://localhost:3000") as client:
|
|
105
|
+
with client.chromium.html_to_pdf() as route:
|
|
106
|
+
response = route.index("my-index.html").resource("image.png").resource("style.css").run()
|
|
107
|
+
Path("my-index.pdf").write_bytes(response.content)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Converting an HTML file with additional resources into a PDF/A1a format:
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from gotenberg_client import GotenbergClient
|
|
114
|
+
from gotenberg_client.options import PdfAFormat
|
|
115
|
+
|
|
116
|
+
with GotenbergClient("http://localhost:3000") as client:
|
|
117
|
+
with client.chromium.html_to_pdf() as route:
|
|
118
|
+
response = route.index("my-index.html").resources(["image.png", "style.css"]).pdf_format(PdfAFormat.A1a).run()
|
|
119
|
+
Path("my-index.pdf").write_bytes(response.content)
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Converting a URL into PDF, in landscape format
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
from gotenberg_client import GotenbergClient
|
|
126
|
+
from gotenberg_client.options import PageOrientation
|
|
127
|
+
|
|
128
|
+
with GotenbergClient("http://localhost:3000") as client:
|
|
129
|
+
with client.chromium.html_to_pdf() as route:
|
|
130
|
+
response = route.url("https://hello.world").orient(PageOrientation.Landscape).run()
|
|
131
|
+
Path("my-world.pdf").write_bytes(response.content)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
To ensure the proper clean up of all used resources, both the client and the route(s) should be
|
|
135
|
+
used as context manager. If for some reason you cannot, you should `.close` the client and any
|
|
136
|
+
routes:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
from gotenberg_client import GotenbergClient
|
|
140
|
+
|
|
141
|
+
try:
|
|
142
|
+
client = GotenbergClient("http://localhost:3000")
|
|
143
|
+
try:
|
|
144
|
+
route = client.merge(["myfile.pdf", "otherfile.pdf"]).run()
|
|
145
|
+
finally:
|
|
146
|
+
route.close()
|
|
147
|
+
finally:
|
|
148
|
+
client.close()
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## License
|
|
152
|
+
|
|
153
|
+
`gotenberg-client` is distributed under the terms of the [MPL 2.0](https://spdx.org/licenses/MPL-2.0.html) license.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
gotenberg_client/__about__.py,sha256=sAiUgeJWCJDT40jVobMpHJAVQvdo8R53oLr6KL82hfQ,132
|
|
2
|
+
gotenberg_client/__init__.py,sha256=47Y_0KYyhb43J73Z5V5xO2h_584HsEv9uWxnNQO9LhI,194
|
|
3
|
+
gotenberg_client/_base.py,sha256=hV00w21wS0BdD2x8hWBOYVYWVefZMts_8z3tOvpHOo8,4059
|
|
4
|
+
gotenberg_client/_client.py,sha256=OS2Kezt08f49cSuyfKcbwwx0Vr80A-HYFA_GerghdUU,2169
|
|
5
|
+
gotenberg_client/_health.py,sha256=4EgEE65xDO2dNPdGkenDRO6hyxJrC05ky-qF5wrdU0s,3697
|
|
6
|
+
gotenberg_client/_merge.py,sha256=PiT1yeEmkFrz7v1cin9GJ8xqtlU06_i93T5HFJ27qPc,1018
|
|
7
|
+
gotenberg_client/_metrics.py,sha256=JGAc-hOnV2jyDwRp3atybZ27MYe9etfk4TJsPDBAqFQ,110
|
|
8
|
+
gotenberg_client/_types_compat.py,sha256=wYiQzGQaWBr_uih6jeJqRkMHRawqTv2W1ThLJTYik-o,242
|
|
9
|
+
gotenberg_client/_utils.py,sha256=WNYVKNODYkO4_OQb1uEGm3Frdv5X69VxeDMTC6UbOl4,1128
|
|
10
|
+
gotenberg_client/options.py,sha256=pNcGoUavA3ENvB7sQM6wKHnF5WHfC6FFzeEG4Z4lvPA,3282
|
|
11
|
+
gotenberg_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
12
|
+
gotenberg_client/_convert/__init__.py,sha256=JGAc-hOnV2jyDwRp3atybZ27MYe9etfk4TJsPDBAqFQ,110
|
|
13
|
+
gotenberg_client/_convert/chromium.py,sha256=ZHrDsXsdVFfwDZXprWN1ekrhcDsoPDou3VFI6MhFJgg,5029
|
|
14
|
+
gotenberg_client/_convert/common.py,sha256=1HYooLUNR0y-hTyBx7QPFs6fHV8RZpHzU3CVvw9tt50,887
|
|
15
|
+
gotenberg_client/_convert/libre_office.py,sha256=FFwd_5RPy6pTDltpvJJAsh-bJX4rrg4TTfjIPjxPSiQ,1539
|
|
16
|
+
gotenberg_client/_convert/pdfa.py,sha256=T2qlUz0PL25xrjAqDb5Q2OJO4U77lUXhnfWFuftHBds,957
|
|
17
|
+
gotenberg_client-0.1.0.dist-info/METADATA,sha256=rI1pdnPOYyVd8Qu1LpwqeSeCE_lThxO5mGu5KgPAEco,5462
|
|
18
|
+
gotenberg_client-0.1.0.dist-info/WHEEL,sha256=9QBuHhg6FNW7lppboF2vKVbCGTVzsFykgRQjjlajrhA,87
|
|
19
|
+
gotenberg_client-0.1.0.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
|
|
20
|
+
gotenberg_client-0.1.0.dist-info/RECORD,,
|