Merge branch 'release/0.7.0'

Author: stumpylog

.codecov.yml

@@ -2,3 +2,15 @@ codecov:
   require_ci_to_pass: true
 comment:
   require_changes: true
+coverage:
+  status:
+    project:
+      default:
+        # https://docs.codecov.com/docs/commit-status#threshold
+        threshold: 1%
+    patch:
+      default:
+        # For the changed lines only, target 90% covered, but
+        # allow as low as 80%
+        target: 90%
+        threshold: 10%

.docker/content/favicon.ico

@@ -5,7 +5,7 @@
 version: "3"
 services:
   gotenberg-client-test-server:
-    image: docker.io/gotenberg/gotenberg:8.5.1
+    image: docker.io/gotenberg/gotenberg:8.11.0
     hostname: gotenberg-client-test-server
     container_name: gotenberg-client-test-server
     network_mode: host

.docker/docker-compose.ci-test.yml

@@ -25,10 +25,10 @@ jobs:
       -
         uses: actions/checkout@v4
       -
-        name: Set up Python 3.10
+        name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
           cache: 'pip'
       -
         name: Install Hatch
@@ -40,6 +40,10 @@ jobs:
         name: Lint project
         run: |
           hatch fmt --check
+      -
+        name: Check project typing
+        run: |
+          hatch run typing:run
       -
         name: Check files with pre-commit
         uses: pre-commit/[email protected]
@@ -108,6 +112,56 @@ jobs:
         docker compose --file ${GITHUB_WORKSPACE}/.docker/docker-compose.ci-test.yml logs
         docker compose --file ${GITHUB_WORKSPACE}/.docker/docker-compose.ci-test.yml down
 
+  test-edge:
+    name: Test Gotenberg :edge
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    needs:
+      - lint
+    steps:
+    -
+      uses: actions/checkout@v4
+    -
+      name: Start containers
+      run: |
+        docker compose --file ${GITHUB_WORKSPACE}/.docker/docker-compose.ci-test-edge.yml pull --quiet
+        docker compose --file ${GITHUB_WORKSPACE}/.docker/docker-compose.ci-test-edge.yml up --detach
+        echo "Wait for container to be started"
+        sleep 5
+        docker inspect gotenberg-client-test-edge-server
+    -
+      name: Install poppler-utils
+      run: |
+        sudo apt-get update
+        sudo apt-get install --yes --no-install-recommends poppler-utils
+    -
+      name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+        cache: 'pip'
+    -
+      name: Install Hatch
+      run: |
+        python3 -m pip install --upgrade pip
+        pip install --upgrade hatch
+    -
+      name: Show environment
+      run: |
+        hatch test --show --python 3.11
+    -
+      name: Run tests
+      run: |
+        hatch test --cover --python 3.11
+        ls -ahl .
+    -
+      name: Stop containers
+      if: always()
+      run: |
+        docker compose --file ${GITHUB_WORKSPACE}/.docker/docker-compose.ci-test-edge.yml logs
+        docker compose --file ${GITHUB_WORKSPACE}/.docker/docker-compose.ci-test-edge.yml down
+
   build:
     name: Build
     runs-on: ubuntu-latest
@@ -243,4 +297,4 @@ jobs:
           path: dist
       -
         name: Publish build to PyPI
-        uses: pypa/gh-action-pypi-publish@v1.8.14
+        uses: pypa/gh-action-pypi-publish@v1.10.2

.github/workflows/ci.yml

@@ -5,7 +5,7 @@
 repos:
   # General hooks
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-docstring-first
       - id: check-json
@@ -28,8 +28,9 @@ repos:
           - svg
       - id: check-case-conflict
       - id: detect-private-key
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: 'v3.1.0'
+    # See https://github.com/prettier/prettier/issues/15742 for the fork reason
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: "v3.3.3"
     hooks:
       - id: prettier
         types_or:
@@ -44,9 +45,13 @@ repos:
       - id: codespell
   # Python hooks
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.4.6'
+    rev: 'v0.6.9'
     hooks:
       # Run the linter.
       - id: ruff
       # Run the formatter.
       - id: ruff-format
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: "2.2.4"
+    hooks:
+      - id: pyproject-fmt

.pre-commit-config.yaml

@@ -5,11 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.7.0] - 2024-10-08
 
 ### Fixed
 
-- Wrong paper size preset for A4 ([#24](https://github.com/stumpylog/gotenberg-client/pull/24))
+- `mike` deployment mis-ordered the version and alias, this has been corrected
+- `mypy` wasn't running correctly in CI
+- Wrong paper size preset for A4 by [@mannerydhe](https://github.com/mannerydhe) ([#24](https://github.com/stumpylog/gotenberg-client/pull/24))
+
+### Added
+
+- All routes now return a stronger typed response than just an `httpx.Response` ([#23](https://github.com/stumpylog/gotenberg-client/pull/23))
+- All public methods now include docstrings ([#33](https://github.com/stumpylog/gotenberg-client/pull/33))
+- The Chromium based HTML and Markdown to PDF routes can now accept accept a `str`, containing either HTML text, Markdown or other text based resources for conversion ([#30](https://github.com/stumpylog/gotenberg-client/pull/30))
+  - See `string_index`, `string_resource` and `string_resources` for those routes
+
+### Changed
+
+- Bump pypa/gh-action-pypi-publish from 1.8.14 to 1.9.0 by @dependabot ([#25](https://github.com/stumpylog/gotenberg-client/pull/25))
+- Bump pypa/gh-action-pypi-publish from 1.9.0 to 1.10.2 by @dependabot ([#31](https://github.com/stumpylog/gotenberg-client/pull/31))
+- CI testing now runs against Gotenberg 8.11 ([#32](https://github.com/stumpylog/gotenberg-client/pull/32))
+- Development tool updates in `pyproject.toml` and pre-commit hook updates
+- Properly use `pytest` fixtures in all testing ([#34](https://github.com/stumpylog/gotenberg-client/pull/34))
+- Upgrade `pre-commit` to 4.0.1 ([#35](https://github.com/stumpylog/gotenberg-client/pull/35))
 
 ## [0.6.0] - 2024-06-13
 

CHANGELOG.md

@@ -52,7 +52,7 @@ endpoint. All the routes use the same format and general idea.
 - 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/)
+For more detailed examples, check the [documentation](https://stumpylog.github.io/gotenberg-client/latest/)
 
 ### Examples
 
@@ -64,7 +64,7 @@ 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()
-      Path("my-index.pdf").write_bytes(response.content)
+      response.to_file(Path("my-index.pdf"))
 ```
 
 Converting an HTML file with additional resources into a PDF:
@@ -75,7 +75,7 @@ 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()
-      Path("my-index.pdf").write_bytes(response.content)
+      response.to_file(Path("my-index.pdf"))
 ```
 
 Converting an HTML file with additional resources into a PDF/A1a format:
@@ -87,7 +87,7 @@ 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()
-      Path("my-index.pdf").write_bytes(response.content)
+      response.to_file(Path("my-index.pdf"))
 ```
 
 Converting a URL into PDF, in landscape format
@@ -99,7 +99,7 @@ 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()
-      Path("my-world.pdf").write_bytes(response.content)
+      response.to_file(Path("my-world.pdf"))
 ```
 
 To ensure the proper clean up of all used resources, both the client and the route(s) should be
@@ -119,6 +119,13 @@ 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.

README.md

@@ -22,7 +22,7 @@ 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()
-      Path("my-index.pdf").write_bytes(response.content)
+      response.to_file(Path("my-index.pdf"))
 ```
 
 Converting an HTML file with additional resources into a PDF:
@@ -33,7 +33,7 @@ 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()
-      Path("my-index.pdf").write_bytes(response.content)
+      response.to_file(Path("my-index.pdf"))
 ```
 
 Converting an HTML file with additional resources into a PDF/A1a format:
@@ -45,7 +45,7 @@ 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()
-      Path("my-index.pdf").write_bytes(response.content)
+      response.to_file(Path("my-index.pdf"))
 ```
 
 Converting a URL into PDF, in landscape format
@@ -57,7 +57,7 @@ from gotenberg_client.options import PageOrientation
 with GotenbergClient("http://localhost:3000") as client:
     with client.chromium.html_to_pdf() as route:
       response = route.url("https://hello.world").orient(PageOrientation.Landscape).run()
-      Path("my-world.pdf").write_bytes(response.content)
+      response.to_file(Path("my-world.pdf"))
 ```
 
 To ensure the proper clean up of all used resources, both the client and the route(s) should be
@@ -76,3 +76,21 @@ try:
 finally:
   client.close()
 ```
+
+## API Responses
+
+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)
+
+Determining which response is a little complicated, as Gotenberg can produce a single PDF from multiple files or
+a zip file containing multiple PDFs, depending on how the route is configured and how many files were provided.
+
+For example, the LibreOffice convert route may:
+
+- Produce a single PDF when a single office document is provided
+- Produce a zipped response when multiple office documents are provided
+- Produce a single PDF when multiple office documents are provided AND the route is asked to merge the result