gotenberg-client 0.1.0__py3-none-any.whl

gotenberg_client/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+__version__ = "0.1.0"

gotenberg_client/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+from gotenberg_client._client import GotenbergClient
+
+__all__ = ["GotenbergClient"]

gotenberg_client/_base.py

@@ -0,0 +1,122 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+import logging
+from contextlib import ExitStack
+from pathlib import Path
+from types import TracebackType
+from typing import Dict
+from typing import Optional
+from typing import Type
+
+from httpx import Client
+from httpx import Response
+from httpx._types import RequestFiles
+
+from gotenberg_client._types_compat import Self
+from gotenberg_client._utils import guess_mime_type
+from gotenberg_client.options import PdfAFormat
+
+logger = logging.getLogger(__name__)
+
+
+class BaseRoute:
+    """
+    The base implementation of a Gotenberg API route.  Anything settings or
+    actions shared between all routes should be implemented here
+    """
+
+    def __init__(self, client: Client, api_route: str) -> None:
+        self._client = client
+        self._route = api_route
+        self._stack = ExitStack()
+        self._form_data: Dict[str, str] = {}
+        self._file_map: Dict[str, Path] = {}
+
+    def __enter__(self) -> Self:
+        self.reset()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        self.reset()
+
+    def reset(self) -> None:
+        """
+        Calls all context manager __exit__ via the ExitStack and clears
+        all set files and form data options
+        """
+        self._stack.close()
+        self._form_data.clear()
+        self._file_map.clear()
+
+    def close(self) -> None:
+        """
+        Alias for reset
+        """
+        self.reset()
+
+    def run(self) -> Response:
+        """
+        Executes the configured route against the server and returns the resulting
+        Response.
+        TODO: It would be nice to return a simpler response to the user
+        """
+        resp = self._client.post(url=self._route, data=self._form_data, files=self.get_files())
+        resp.raise_for_status()
+        return resp
+
+    def get_files(self) -> RequestFiles:
+        """
+        Deals with opening all provided files for multi-part uploads, including
+        pushing their new contexts onto the stack to ensure resources like file
+        handles are cleaned up
+        """
+        files = {}
+        for filename in self._file_map:
+            file_path = self._file_map[filename]
+            # Gotenberg requires these to have the specific name
+            filepath_name = filename if filename in {"index.html", "header.html", "footer.html"} else file_path.name
+
+            # Helpful but not necessary to provide the mime type when possible
+            mime_type = guess_mime_type(file_path)
+            if mime_type is not None:
+                files.update(
+                    {filepath_name: (filepath_name, self._stack.enter_context(file_path.open("rb")), mime_type)},
+                )
+            else:  # pragma: no cover
+                files.update({filepath_name: (filepath_name, self._stack.enter_context(file_path.open("rb")))})  # type: ignore
+        return files
+
+    def _add_file_map(self, filepath: Path, name: Optional[str] = None) -> None:
+        """
+        Small helper to handle bookkeeping of files for later opening.  The name is
+        optional to support those things which are required to have a certain name
+        """
+        if name is None:
+            name = filepath.name
+        if name in self._file_map:  # pragma: no cover
+            logger.warning(f"{name} has already been provided, overwriting anyway")
+        self._file_map[name] = filepath
+
+    def pdf_format(self, pdf_format: PdfAFormat) -> "BaseRoute":
+        """
+        All routes provide the option to configure the output PDF as a
+        PDF/A format
+        """
+        self._form_data.update(pdf_format.to_form())
+        return self
+
+
+class BaseApi:
+    """
+    Simple base class for an API, which wraps one or more routes, providing
+    each with the client to use
+    """
+
+    def __init__(self, client: Client) -> None:
+        self._client = client

gotenberg_client/_client.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+import logging
+from importlib.util import find_spec
+from types import TracebackType
+from typing import Dict
+from typing import Optional
+from typing import Type
+
+from httpx import Client
+
+from gotenberg_client._convert.chromium import ChromiumApi
+from gotenberg_client._convert.libre_office import LibreOfficeApi
+from gotenberg_client._convert.pdfa import PdfAApi
+from gotenberg_client._health import HealthCheckApi
+from gotenberg_client._merge import MergeApi
+
+
+class GotenbergClient:
+    """
+    The user's primary interface to the Gotenberg instance
+    """
+
+    def __init__(
+        self,
+        *,
+        gotenerg_url: str,
+        timeout: float = 30.0,
+        log_level: int = logging.ERROR,
+        http2: bool = True,
+    ):
+        # Configure the client
+        self._client = Client(base_url=gotenerg_url, timeout=timeout, http2=http2)
+
+        # Set the log level
+        logging.getLogger("httpx").setLevel(log_level)
+        logging.getLogger("httpcore").setLevel(log_level)
+
+        # TODO Brotli?
+        if find_spec("brotli") is not None:
+            self._client.headers.update({"Accept-Encoding": "gzip,deflate,br"})
+        else:
+            self._client.headers.update({"Accept-Encoding": "gzip,deflate"})
+
+        # Add the resources
+        self.chromium = ChromiumApi(self._client)
+        self.libre_office = LibreOfficeApi(self._client)
+        self.pdf_a = PdfAApi(self._client)
+        self.merge = MergeApi(self._client)
+        self.health = HealthCheckApi(self._client)
+        # TODO
+
+    def add_headers(self, header: Dict[str, str]) -> None:  # pragma: no cover
+        """
+        Updates the httpx Client headers with the given values
+        """
+        self._client.headers.update(header)
+
+    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.close()

gotenberg_client/_convert/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0

gotenberg_client/_convert/chromium.py

@@ -0,0 +1,174 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+import json
+import logging
+from pathlib import Path
+from typing import Dict
+from typing import Final
+from typing import List
+from typing import Union
+
+from gotenberg_client._base import BaseApi
+from gotenberg_client._convert.common import ConvertBaseRoute
+from gotenberg_client._types_compat import Self
+from gotenberg_client.options import EmulatedMediaType
+from gotenberg_client.options import Margin
+from gotenberg_client.options import PageSize
+
+logger = logging.getLogger()
+
+
+# See https://github.com/psf/requests/issues/1081#issuecomment-428504128
+class ForceMultipartDict(Dict):
+    def __bool__(self) -> bool:
+        return True
+
+
+FORCE_MULTIPART: Final = ForceMultipartDict()
+
+
+class ChromiumBaseRoute(ConvertBaseRoute):
+    """
+    https://gotenberg.dev/docs/routes#convert-with-chromium
+    """
+
+    def header(self, header: Path) -> Self:
+        self._add_file_map(header, "header.html")
+        return self
+
+    def footer(self, footer: Path) -> Self:
+        self._add_file_map(footer, "footer.html")
+        return self
+
+    def resource(self, resource: Path) -> Self:
+        self._add_file_map(resource)
+        return self
+
+    def resources(self, resources: List[Path]) -> Self:
+        for x in resources:
+            self.resource(x)
+        return self
+
+    def size(self, size: PageSize) -> Self:
+        self._form_data.update(size.to_form())
+        return self
+
+    page_size = size
+
+    def margins(self, margins: Margin) -> Self:
+        self._form_data.update(margins.to_form())
+        return self
+
+    def prefer_css_page_size(self) -> Self:
+        self._form_data.update({"preferCssPageSize": "true"})
+        return self
+
+    def prefer_set_page_size(self) -> Self:
+        self._form_data.update({"preferCssPageSize": "false"})
+        return self
+
+    def background_graphics(self) -> Self:
+        self._form_data.update({"printBackground": "true"})
+        return self
+
+    def no_background_graphics(self) -> Self:
+        self._form_data.update({"printBackground": "false"})
+        return self
+
+    def hide_background(self) -> Self:
+        self._form_data.update({"omitBackground": "true"})
+        return self
+
+    def show_background(self) -> Self:
+        self._form_data.update({"omitBackground": "false"})
+        return self
+
+    def scale(self, scale: Union[int, float]) -> Self:
+        self._form_data.update({"scale": str(scale)})
+        return self
+
+    def render_wait(self, wait: Union[int, float]) -> Self:
+        self._form_data.update({"waitDelay": str(wait)})
+        return self
+
+    def render_expr(self, expr: str) -> Self:
+        self._form_data.update({"waitForExpression": expr})
+        return self
+
+    def media_type(self, media_type: EmulatedMediaType) -> Self:
+        self._form_data.update(media_type.to_form())
+        return self
+
+    def user_agent(self, agent: str) -> Self:
+        self._form_data.update({"userAgent": agent})
+        return self
+
+    def headers(self, headers: Dict[str, str]) -> Self:
+        json_str = json.dumps(headers)
+        # TODO: Need to check this
+        self._form_data.update({"extraHttpHeaders": json_str})
+        return self
+
+    def fail_on_exceptions(self) -> Self:
+        self._form_data.update({"failOnConsoleExceptions": "true"})
+        return self
+
+    def dont_fail_on_exceptions(self) -> Self:
+        self._form_data.update({"failOnConsoleExceptions": "false"})
+        return self
+
+
+class _FileBasedRoute(ChromiumBaseRoute):
+    def index(self, index: Path) -> Self:
+        self._add_file_map(index, "index.html")
+        return self
+
+
+class HtmlRoute(_FileBasedRoute):
+    """
+    https://gotenberg.dev/docs/routes#html-file-into-pdf-route
+    """
+
+
+class UrlRoute(ChromiumBaseRoute):
+    """
+    https://gotenberg.dev/docs/routes#url-into-pdf-route
+    """
+
+    def url(self, url: str) -> Self:
+        self._form_data["url"] = url
+        return self
+
+    def get_files(self) -> ForceMultipartDict:
+        return FORCE_MULTIPART
+
+
+class MarkdownRoute(_FileBasedRoute):
+    """
+    https://gotenberg.dev/docs/routes#markdown-files-into-pdf-route
+    """
+
+    def markdown_file(self, markdown_file: Path) -> Self:
+        self._add_file_map(markdown_file)
+        return self
+
+    def markdown_files(self, markdown_files: List[Path]) -> Self:
+        for x in markdown_files:
+            self.markdown_file(x)
+        return self
+
+
+class ChromiumApi(BaseApi):
+    _URL_CONVERT_ENDPOINT = "/forms/chromium/convert/url"
+    _HTML_CONVERT_ENDPOINT = "/forms/chromium/convert/html"
+    _MARKDOWN_CONVERT_ENDPOINT = "/forms/chromium/convert/markdown"
+
+    def html_to_pdf(self) -> HtmlRoute:
+        return HtmlRoute(self._client, self._HTML_CONVERT_ENDPOINT)
+
+    def url_to_pdf(self) -> UrlRoute:
+        return UrlRoute(self._client, self._URL_CONVERT_ENDPOINT)
+
+    def markdown_to_pdf(self) -> MarkdownRoute:
+        return MarkdownRoute(self._client, self._MARKDOWN_CONVERT_ENDPOINT)

gotenberg_client/_convert/common.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+import logging
+
+from gotenberg_client._base import BaseRoute
+from gotenberg_client._types_compat import Self
+from gotenberg_client.options import PageOrientation
+
+logger = logging.getLogger()
+
+
+class ConvertBaseRoute(BaseRoute):
+    """
+    All 3 convert routes provide control over orientation and page ranges
+    """
+
+    def orient(self, orient: PageOrientation) -> Self:
+        """
+        Sets the page orientation, either Landscape or portrait
+        """
+        self._form_data.update(orient.to_form())
+        return self
+
+    def page_ranges(self, ranges: str) -> Self:
+        """
+        Sets the page range string, allowing either some range or just a
+        few pages
+        """
+        self._form_data.update({"nativePageRanges": ranges})
+        return self

gotenberg_client/_convert/libre_office.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+from pathlib import Path
+from typing import List
+
+from gotenberg_client._base import BaseApi
+from gotenberg_client._convert.common import ConvertBaseRoute
+from gotenberg_client._types_compat import Self
+
+
+class LibreOfficeConvertRoute(ConvertBaseRoute):
+    """
+    https://gotenberg.dev/docs/routes#convert-with-libreoffice
+    """
+
+    def convert(self, file_path: Path) -> Self:
+        """
+        Adds a single file to be converted to PDF.  Can be called multiple times,
+        resulting in a ZIP of the PDFs, unless merged
+        """
+        self._add_file_map(file_path)
+        return self
+
+    def convert_files(self, file_paths: List[Path]) -> Self:
+        """
+        Adds all provided files for conversion
+        """
+        for x in file_paths:
+            self.convert(x)
+        return self
+
+    def merge(self) -> Self:
+        """
+        Merge the resulting PDFs into one
+        """
+        self._form_data.update({"merge": "true"})
+        return self
+
+    def no_merge(self) -> Self:
+        """
+        Don't merge the resulting PDFs
+        """
+        self._form_data.update({"merge": "false"})
+        return self
+
+
+class LibreOfficeApi(BaseApi):
+    _CONVERT_ENDPOINT = "/forms/libreoffice/convert"
+
+    def to_pdf(self) -> LibreOfficeConvertRoute:
+        """
+        Returns the LibreOffice conversion route
+        """
+        return LibreOfficeConvertRoute(self._client, self._CONVERT_ENDPOINT)

gotenberg_client/_convert/pdfa.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+from pathlib import Path
+from typing import List
+
+from gotenberg_client._base import BaseApi
+from gotenberg_client._convert.common import ConvertBaseRoute
+from gotenberg_client._types_compat import Self
+
+
+class PdfAConvertRoute(ConvertBaseRoute):
+    """
+    https://gotenberg.dev/docs/routes#convert-into-pdfa-route
+    """
+
+    def convert(self, file_path: Path) -> Self:
+        """
+        Convert a single PDF into the provided PDF/A format
+        """
+        self._add_file_map(file_path)
+        return self
+
+    def convert_files(self, file_paths: List[Path]) -> Self:
+        for x in file_paths:
+            self.convert(x)
+        return self
+
+
+class PdfAApi(BaseApi):
+    _CONVERT_ENDPOINT = "/forms/pdfengines/convert"
+
+    def to_pdfa(self) -> PdfAConvertRoute:
+        return PdfAConvertRoute(self._client, self._CONVERT_ENDPOINT)

gotenberg_client/_health.py

@@ -0,0 +1,131 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+import dataclasses
+import datetime
+import enum
+import re
+from typing import Optional
+from typing import TypedDict
+from typing import no_type_check
+
+from gotenberg_client._base import BaseApi
+
+_TIME_RE = re.compile(
+    r"(?P<year>\d{4})-"
+    r"(?P<month>\d{2})-"
+    r"(?P<day>\d{2})"
+    r"[ tT]"
+    r"(?P<hour>\d{2}):"
+    r"(?P<minute>\d{2}):"
+    r"(?P<second>\d{2})"
+    r"(?P<fractional_seconds>\.\d+)?"
+    r"(?P<timezone>[zZ]|[+-]\d{2}:\d{2})?",
+)
+
+
+class _ModuleStatusType(TypedDict):
+    status: str
+    timestamp: str
+
+
+class _AllModulesType(TypedDict):
+    chromium: _ModuleStatusType
+    uno: _ModuleStatusType
+
+
+class _HealthCheckApiResponseType(TypedDict):
+    status: str
+    details: _AllModulesType
+
+
+@enum.unique
+class StatusOptions(str, enum.Enum):
+    Up = "up"
+    Down = "down"
+
+
+@enum.unique
+class ModuleOptions(str, enum.Enum):
+    Chromium = "chromium"
+    Uno = "uno"
+
+
+@dataclasses.dataclass
+class ModuleStatus:
+    status: StatusOptions
+    timestamp: datetime.datetime
+
+
+class HealthStatus:
+    """
+    Decodes the JSON health response into Python types
+    """
+
+    def __init__(self, data: _HealthCheckApiResponseType) -> None:
+        self.data = data
+        self.overall = StatusOptions(data["status"])
+
+        self.chromium: Optional[ModuleStatus] = None
+        if ModuleOptions.Chromium.value in self.data["details"]:
+            self.chromium = self._extract_status(ModuleOptions.Chromium)
+
+        self.uno: Optional[ModuleStatus] = None
+        if ModuleOptions.Uno.value in self.data["details"]:
+            self.uno = self._extract_status(ModuleOptions.Uno)
+
+    def _extract_status(self, module: ModuleOptions) -> ModuleStatus:
+        status = StatusOptions(self.data["details"][module.value]["status"])
+
+        # mypy is quite wrong here, it's clearly marked as a datetime.datetime, not Any
+        timestamp = self._extract_datetime(self.data["details"][module.value]["timestamp"])  # type: ignore
+        # Also wrong here
+        return ModuleStatus(status, timestamp)  # type: ignore
+
+    @staticmethod
+    @no_type_check
+    def _extract_datetime(timestamp: str) -> datetime.datetime:
+        m = _TIME_RE.match(timestamp)
+        if not m:
+            msg = f"Unable to parse {timestamp}"
+            raise ValueError(msg)
+
+        (year, month, day, hour, minute, second, frac_sec, timezone_str) = m.groups()
+
+        microseconds = int(float(frac_sec) * 1000000.0) if frac_sec is not None else 0
+        tzinfo = None
+        if timezone_str is not None:
+            if timezone_str.lower() == "z":
+                tzinfo = datetime.timezone.utc
+            else:
+                multi = -1 if timezone_str[0:1] == "-" else 1
+                hours = int(timezone_str[1:3])
+                minutes = int(timezone_str[4:])
+                delta = datetime.timedelta(hours=hours, minutes=minutes) * multi
+                tzinfo = datetime.timezone(delta)
+
+        return datetime.datetime(
+            year=int(year),
+            month=int(month),
+            day=int(day),
+            hour=int(hour),
+            minute=int(minute),
+            second=int(second),
+            microsecond=microseconds,
+            tzinfo=tzinfo,
+        )
+
+
+class HealthCheckApi(BaseApi):
+    """
+    Provides the route for health checks
+    """
+
+    _HEALTH_ENDPOINT = "/health"
+
+    def health(self) -> HealthStatus:
+        resp = self._client.get(self._HEALTH_ENDPOINT, headers={"Accept": "application/json"})
+        resp.raise_for_status()
+        json_data: _HealthCheckApiResponseType = resp.json()
+
+        return HealthStatus(json_data)

gotenberg_client/_merge.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+from pathlib import Path
+from typing import List
+
+from gotenberg_client._base import BaseApi
+from gotenberg_client._base import BaseRoute
+
+
+class MergeRoute(BaseRoute):
+    """
+    Handles the merging of a given set of files
+    """
+
+    def merge(self, files: List[Path]) -> "MergeRoute":
+        """
+        Adds the given files into the file mapping.  This method will maintain the
+        ordering of the list.  Calling this method multiple times may not merge
+        in the expected ordering
+        """
+        for idx, filepath in enumerate(files):
+            # Include index to enforce ordering
+            self._add_file_map(filepath, f"{idx}_{filepath.name}")
+        return self
+
+
+class MergeApi(BaseApi):
+    """
+    Wraps the merge route
+    """
+
+    _MERGE_ENDPOINT = "/forms/pdfengines/merge"
+
+    def merge(self) -> MergeRoute:
+        return MergeRoute(self._client, self._MERGE_ENDPOINT)

gotenberg_client/_metrics.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0

gotenberg_client/_types_compat.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2023-present Trenton H <rda0128ou@mozmail.com>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self  # noqa: F401