Fleshes out the README and provides examples

.github/workflows/ci.yml

@@ -56,7 +56,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', 'pypy3.8', 'pypy3.9']
+        # No pikepdf wheels for pypy3.8
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', 'pypy3.9']
 
     steps:
     -

README.md

@@ -8,6 +8,11 @@
 ## Table of Contents
 
 - [Installation](#installation)
+- [What](#what)
+- [Why](#why)
+  - [Features](#features)
+- [How](#how)
+  - [Examples](#examplesV)
 - [License](#license)
 
 ## Installation
@@ -33,6 +38,74 @@ As far as I can tell, no Python library exists to interface with the Gotenberg A
 - Full support for type hinting and concrete return types as mush 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 configure
+
+### Examples
+
+Converting a single HTML file into a PDF:
+
+```python
+with GotenbergClient("http://localhost:3000") as client:
+    with client.chromium.html_to_pdf() as route:
+      response = route.index("my-index.html").run()
+      Path("my-index.pdf").write_bytes(response.content)
+```
+
+Converting an HTML file with additional resources into a PDF:
+
+```python
+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()
+      Path("my-index.pdf").write_bytes(response.content)
+```
+
+Converting an HTML file with additional resources into a PDF/A1a format:
+
+```python
+from gotenberg_client.pdf_format import PdfAFormatOptions
+
+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").pdf_format(PdfAFormatOptions.A1a).run()
+      Path("my-index.pdf").write_bytes(response.content)
+```
+
+Converting a URL into PDF, in landscape format
+
+```python
+from gotenberg_client.convert.common import PageOrientationOptions
+
+with GotenbergClient("http://localhost:3000") as client:
+    with client.chromium.html_to_pdf() as route:
+      response = route.url("https://hello.world").orient(PageOrientationOptions.Landscape).run()
+      Path("my-world.pdf").write_bytes(response.content)
+```
+
+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
+try:
+  client = GotenbergClient("http://localhost:3000")
+  try:
+    route = client.merge(["myfile.pdf", "otherfile.pdf"]).run()
+  finally:
+    route.close()
+finally:
+  client.close()
+```
+
 ## License
 
 `gotenberg-client` is distributed under the terms of the [MPL 2.0](https://spdx.org/licenses/MPL-2.0.html) license.

src/gotenberg_client/base.py

@@ -41,6 +41,9 @@ def reset(self) -> None:
         self._form_data.clear()
         self._file_map.clear()
 
+    def close(self) -> None:
+        self.reset()
+
     def run(self) -> Response:
         resp = self._client.post(url=self._route, data=self._form_data, files=self.get_files())
         resp.raise_for_status()

src/gotenberg_client/client.py

@@ -53,10 +53,13 @@ def add_headers(self, header: Dict[str, str]) -> None:  # pragma: no cover
     def __enter__(self) -> "GotenbergClient":
         return self
 
+    def close(self) -> None:
+        self._client.close()
+
     def __exit__(
         self,
         exc_type: Optional[Type[BaseException]],
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> None:
-        self._client.close()
+        self.close()