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.
@@ -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
+ [![PyPI - Version](https://img.shields.io/pypi/v/gotenberg-client.svg)](https://pypi.org/project/gotenberg-client)
36
+ [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/gotenberg-client.svg)](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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.18.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any