pdfgate 0.0.2__py3-none-any.whl

pdfgate/__about__.py

@@ -0,0 +1,6 @@
+"""Package metadata for pdfgate."""
+
+# SPDX-FileCopyrightText: 2026-present Fernando Gasperi <fgasperijabalera@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.2"

pdfgate/__init__.py

@@ -0,0 +1,81 @@
+"""Public package initialization for pdfgate."""
+
+# SPDX-FileCopyrightText: 2026-present Fernando Gasperi <fgasperijabalera@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from .pdfgate import PDFGate
+from .params import (
+    PageSizeType,
+    FileOrientation,
+    EmulateMediaType,
+    PdfStandardFont,
+    PdfPageMargin,
+    ClickSelectorChain,
+    ClickSelectorChainSetup,
+    PDFGateParams,
+    GetDocumentParams,
+    GetFileParams,
+    GeneratePDFAuthentication,
+    Viewport,
+    GeneratePDFParams,
+    FlattenPDFBaseParams,
+    FileParam,
+    FlattenPDFByFileParams,
+    FlattenPDFByDocumentIdParams,
+    ExtractPDFFormDataByDocumentIdParams,
+    ExtractPDFFormDataByFileParams,
+    EncryptionAlgorithm,
+    ProtectPDFBaseParams,
+    ProtectPDFByDocumentIdParams,
+    ProtectPDFByFileParams,
+    CompressPDFBaseParams,
+    CompressPDFByDocumentIdParams,
+    CompressPDFByFileParams,
+    WatermarkType,
+    WatermarkPDFBaseParams,
+    WatermarkPDFByDocumentIdParams,
+    WatermarkPDFByFileParams,
+)
+from .responses import (
+    DocumentStatus,
+    DocumentType,
+    PDFGateDocument,
+)
+
+__all__ = [
+    "PDFGate",
+    "PageSizeType",
+    "FileOrientation",
+    "EmulateMediaType",
+    "PdfStandardFont",
+    "PdfPageMargin",
+    "ClickSelectorChain",
+    "ClickSelectorChainSetup",
+    "PDFGateParams",
+    "GetDocumentParams",
+    "GetFileParams",
+    "GeneratePDFAuthentication",
+    "Viewport",
+    "GeneratePDFParams",
+    "FlattenPDFBaseParams",
+    "FileParam",
+    "FlattenPDFByFileParams",
+    "FlattenPDFByDocumentIdParams",
+    "ExtractPDFFormDataByDocumentIdParams",
+    "ExtractPDFFormDataByFileParams",
+    "EncryptionAlgorithm",
+    "ProtectPDFBaseParams",
+    "ProtectPDFByDocumentIdParams",
+    "ProtectPDFByFileParams",
+    "CompressPDFBaseParams",
+    "CompressPDFByDocumentIdParams",
+    "CompressPDFByFileParams",
+    "WatermarkType",
+    "WatermarkPDFBaseParams",
+    "WatermarkPDFByDocumentIdParams",
+    "WatermarkPDFByFileParams",
+    "DocumentStatus",
+    "DocumentType",
+    "PDFGateDocument",
+]

pdfgate/config.py

@@ -0,0 +1,18 @@
+"""Configuration values for API domains and default timeouts."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Config:
+    """Holds constant configuration values for the SDK."""
+
+    PRODUCTION_API_DOMAIN: str = "https://api.pdfgate.com"
+    SANDBOX_API_DOMAIN: str = "https://api-sandbox.pdfgate.com"
+
+    DEFAULT_TIMEOUT_SECONDS: int = 60
+    GENERATE_PDF_TIMEOUT_MINUTES: int = 15
+    FLATTEN_PDF_TIMEOUT_MINUTES: int = 3
+    COMPRESS_PDF_TIMEOUT_MINUTES: int = 3
+    PROTECT_PDF_TIMEOUT_MINUTES: int = 3
+    WATERMARK_PDF_TIMEOUT_MINUTES: int = 3

pdfgate/dict_keys_converter.py

@@ -0,0 +1,54 @@
+"""Key conversion helpers for camelCase and snake_case dictionaries."""
+
+import re
+from typing import Any, Union
+
+
+def camel_to_snake(name: str) -> str:
+    """Convert a string from camelCase to snake_case."""
+    # Inserts an underscore before any uppercase letter that is followed by a
+    # lowercase letter or digit.
+    # This is needed for cases like: TestHTTPResponse -> TestHTTP_Response
+    s1 = re.sub("(.)([A-Z][a-z0-9]+)", r"\1_\2", name)
+    # Inserts an underscore before any uppercase letter that is preceded by a lowercase letter or digit
+    s2 = re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1)
+    return s2.lower()
+
+
+def convert_camel_keys_to_snake(
+    data: Union[dict[Any, Any], list[Any], Any],
+) -> Union[dict[Any, Any], list[Any], Any]:
+    """Recursively converts all keys in a dictionary or list to snake_case."""
+    if isinstance(data, dict):
+        new_dict = {}
+        for key, value in data.items():  # type: ignore
+            new_key = camel_to_snake(key)  # type: ignore
+            new_dict[new_key] = convert_camel_keys_to_snake(value)  # type: ignore
+        return new_dict  # type: ignore
+    elif isinstance(data, list):
+        return [convert_camel_keys_to_snake(item) for item in data]  # type: ignore
+    else:
+        return data
+
+
+def snake_to_camel(key: str) -> str:
+    """Convert a snake_case string to camelCase."""
+    parts = key.split("_")
+
+    return parts[0] + "".join(word.capitalize() for word in parts[1:])
+
+
+def convert_snake_keys_to_camel(
+    data: Union[dict[Any, Any], list[Any], Any],
+) -> Union[dict[Any, Any], list[Any], Any]:
+    """Recursively converts all keys in a dictionary or list to camelCase."""
+    if isinstance(data, dict):
+        new_dict = {}
+        for key, value in data.items():  # type: ignore
+            new_key = snake_to_camel(key)  # type: ignore
+            new_dict[new_key] = convert_snake_keys_to_camel(value)  # type: ignore
+        return new_dict  # type: ignore
+    elif isinstance(data, list):
+        return [convert_snake_keys_to_camel(item) for item in data]  # type: ignore
+    else:
+        return data

pdfgate/errors.py

@@ -0,0 +1,9 @@
+"""Custom exception types for the PDFGate SDK."""
+
+
+class PDFGateError(Exception):
+    """Base error for SDK failures."""
+
+
+class ParamsValidationError(PDFGateError):
+    """Raised when required parameters are missing or invalid."""

pdfgate/http_client.py

@@ -0,0 +1,76 @@
+"""HTTP client implementations for synchronous and asynchronous requests."""
+
+from typing import NoReturn
+import httpx
+
+from pdfgate.errors import PDFGateError
+from pdfgate.request_builder import PDFGateRequest
+
+
+class PDFGateHTTPClientBase:
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    def get_headers(self) -> dict[str, str]:
+        """Return the authorization HTTP headers for API requests.
+
+        Returns:
+            A dict of headers including the Authorization bearer token.
+        """
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def raise_error_from_http_status_error(self, e: httpx.HTTPStatusError) -> NoReturn:
+        """Raise a PDFGateError with details from an HTTP status error."""
+        status_code = e.response.status_code
+        content_type = e.response.headers.get("Content-Type", "")
+        message = e.response.text
+        if "application/json" in content_type:
+            try:
+                error_info = e.response.json()
+                message = error_info.get("message", e.response.text)
+            except ValueError:
+                message = e.response.text
+
+        raise PDFGateError(
+            f"HTTP Error: status {status_code} - message: {message}"
+        ) from e
+
+
+class PDFGateHTTPClientSync(PDFGateHTTPClientBase):
+    """Synchronous HTTP client for PDFGate API requests."""
+
+    def __init__(self, api_key: str):
+        super().__init__(api_key=api_key)
+
+    def try_make_request(self, request: PDFGateRequest) -> httpx.Response:
+        """Send a request synchronously raising HTTP errors."""
+        try:
+            with httpx.Client(timeout=request.timeout) as client:
+                response = client.send(request.request)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            self.raise_error_from_http_status_error(e)
+        except httpx.RequestError as e:
+            raise PDFGateError(f"Request failed: {e}") from e
+
+        return response
+
+
+class PDFGateHTTPClientAsync(PDFGateHTTPClientBase):
+    """Asynchronous HTTP client for PDFGate API requests."""
+
+    def __init__(self, api_key: str):
+        super().__init__(api_key=api_key)
+
+    async def try_make_request_async(self, request: PDFGateRequest) -> httpx.Response:
+        """Send a request asynchronously raising HTTP errors."""
+        try:
+            async with httpx.AsyncClient(timeout=request.timeout) as client:
+                response = await client.send(request.request)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            self.raise_error_from_http_status_error(e)
+        except httpx.RequestError as e:
+            raise PDFGateError(f"Request failed: {e}") from e
+
+        return response

pdfgate/params.py

@@ -0,0 +1,308 @@
+"""Parameter types and enums used by PDFGate API calls."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, NamedTuple, Optional, Union
+
+
+class PageSizeType(Enum):
+    """Supported page sizes for generated PDFs."""
+
+    A0 = "a0"
+    A1 = "a1"
+    A2 = "a2"
+    A3 = "a3"
+    A4 = "a4"
+    A5 = "a5"
+    A6 = "a6"
+    LEDGER = "ledger"
+    TABLOID = "tabloid"
+    LEGAL = "legal"
+    LETTER = "letter"
+
+
+class FileOrientation(Enum):
+    """Orientation options for generated PDFs."""
+
+    PORTRAIT = "portrait"
+    LANDSCAPE = "landscape"
+
+
+class EmulateMediaType(Enum):
+    """Media types for CSS emulation during rendering."""
+
+    SCREEN = "screen"
+    PRINT = "print"
+
+
+class PdfStandardFont(Enum):
+    """Standard built-in fonts supported by the renderer."""
+
+    TIMES_ROMAN = "times-roman"
+    TIMES_BOLD = "times-bold"
+    TIMES_ITALIC = "times-italic"
+    TIMES_BOLD_ITALIC = "times-bolditalic"
+    HELVETICA = "helvetica"
+    HELVETICA_BOLD = "helvetica-bold"
+    HELVETICA_OBLIQUE = "helvetica-oblique"
+    HELVETICA_BOLD_OBLIQUE = "helvetica-boldoblique"
+    COURIER = "courier"
+    COURIER_BOLD = "courier-bold"
+    COURIER_OBLIQUE = "courier-oblique"
+    COURIER_BOLD_OBLIQUE = "courier-boldoblique"
+
+
+@dataclass
+class PdfPageMargin:
+    """Margins to apply to a PDF page."""
+
+    top: Optional[str] = None
+    bottom: Optional[str] = None
+    left: Optional[str] = None
+    right: Optional[str] = None
+
+
+@dataclass
+class ClickSelectorChain:
+    """Sequence of selectors to click in order."""
+
+    selectors: list[str]
+
+
+@dataclass
+class ClickSelectorChainSetup:
+    """Configuration for click selector chains."""
+
+    ignore_failing_chains: Optional[bool] = None
+    chains: Optional[list["ClickSelectorChain"]] = None
+
+
+@dataclass
+class PDFGateParams:
+    """Marker base class for all parameter dataclasses."""
+
+    pass
+
+
+@dataclass
+class GetDocumentParams(PDFGateParams):
+    """Parameters for fetching a document's metadata."""
+
+    document_id: str
+    pre_signed_url_expires_in: Optional[int] = None
+
+
+@dataclass
+class GetFileParams(PDFGateParams):
+    """Parameters for downloading a document's file content."""
+
+    document_id: str
+
+
+@dataclass
+class GeneratePDFAuthentication:
+    """ "Authentication credentials for accessing protected web content."""
+
+    username: str
+    password: str
+
+
+@dataclass
+class Viewport:
+    """Viewport dimensions for rendering."""
+
+    width: int
+    height: int
+
+
+@dataclass
+class GeneratePDFParams(PDFGateParams):
+    """Parameters for generating a PDF from HTML or a URL."""
+
+    html: Optional[str] = None
+    url: Optional[str] = None
+    json_response: Optional[bool] = False
+    pre_signed_url_expires_in: Optional[int] = None
+    page_size_type: Optional[PageSizeType] = None
+    width: Optional[int] = None
+    height: Optional[int] = None
+    orientation: Optional[FileOrientation] = None
+    header: Optional[str] = None
+    footer: Optional[str] = None
+    margin: Optional[PdfPageMargin] = None
+    timeout: Optional[int] = None
+    javascript: Optional[str] = None
+    css: Optional[str] = None
+    emulate_media_type: Optional[EmulateMediaType] = None
+    http_headers: Optional[dict[str, str]] = None
+    metadata: Optional[Any] = None
+    wait_for_selector: Optional[str] = None
+    click_selector: Optional[str] = None
+    click_selector_chain_setup: Optional[ClickSelectorChainSetup] = None
+    wait_for_network_idle: Optional[bool] = None
+    enable_form_fields: Optional[bool] = None
+    delay: Optional[int] = None
+    load_images: Optional[bool] = None
+    scale: Optional[float] = None
+    page_ranges: Optional[str] = None
+    print_background: Optional[bool] = None
+    user_agent: Optional[str] = None
+    authentication: Optional[GeneratePDFAuthentication] = None
+    viewport: Optional[Viewport] = None
+
+
+@dataclass
+class FlattenPDFBaseParams(PDFGateParams):
+    """Common parameters for flattening PDFs."""
+
+    json_response: Optional[bool] = False
+    pre_signed_url_expires_in: Optional[int] = None
+    metadata: Optional[Any] = None
+
+
+class FileParam(NamedTuple):
+    """Binary file payload for multipart PDF uploads."""
+
+    name: str
+    data: bytes
+    type: Optional[str] = None
+
+
+@dataclass
+class FlattenPDFByFileParams(FlattenPDFBaseParams):
+    """Parameters for flattening a PDF provided as a file."""
+
+    file: Optional[FileParam] = None
+
+
+@dataclass
+class FlattenPDFByDocumentIdParams(FlattenPDFBaseParams):
+    """Parameters for flattening a PDF by document ID."""
+
+    document_id: Optional[str] = None
+
+
+FlattenPDFParams = Union[FlattenPDFByFileParams, FlattenPDFByDocumentIdParams]
+
+
+@dataclass
+class ExtractPDFFormDataByDocumentIdParams(PDFGateParams):
+    """Parameters for extracting form data by document ID."""
+
+    document_id: str
+
+
+@dataclass
+class ExtractPDFFormDataByFileParams(PDFGateParams):
+    """Parameters for extracting form data from a file."""
+
+    file: FileParam
+
+
+ExtractPDFFormDataParams = Union[
+    ExtractPDFFormDataByDocumentIdParams, ExtractPDFFormDataByFileParams
+]
+
+
+class EncryptionAlgorithm(Enum):
+    """Supported encryption algorithms."""
+
+    AES_256 = "AES256"
+    AES_128 = "AES128"
+
+
+@dataclass
+class ProtectPDFBaseParams(PDFGateParams):
+    """Common parameters for protecting PDFs."""
+
+    algorithm: Optional[EncryptionAlgorithm] = None
+    user_password: Optional[str] = None
+    owner_password: Optional[str] = None
+    disable_print: Optional[bool] = None
+    disable_copy: Optional[bool] = None
+    disable_editing: Optional[bool] = None
+    encrypt_metadata: Optional[bool] = None
+    json_response: Optional[bool] = False
+    pre_signed_url_expires_in: Optional[int] = None
+    metadata: Optional[Any] = None
+
+
+@dataclass
+class ProtectPDFByDocumentIdParams(ProtectPDFBaseParams):
+    """Parameters for protecting a PDF by document ID."""
+
+    document_id: Optional[str] = None
+
+
+@dataclass
+class ProtectPDFByFileParams(ProtectPDFBaseParams):
+    """Parameters for protecting a PDF provided as a file."""
+
+    file: Optional[FileParam] = None
+
+
+ProtectPDFParams = Union[ProtectPDFByDocumentIdParams, ProtectPDFByFileParams]
+
+
+@dataclass
+class CompressPDFBaseParams(PDFGateParams):
+    """Common parameters for compressing PDFs."""
+
+    linearize: Optional[bool] = None
+    json_response: Optional[bool] = False
+    pre_signed_url_expires_in: Optional[int] = None
+    metadata: Optional[Any] = None
+
+
+@dataclass
+class CompressPDFByDocumentIdParams(CompressPDFBaseParams):
+    """Parameters for compressing a PDF by document ID."""
+
+    document_id: Optional[str] = None
+
+
+@dataclass
+class CompressPDFByFileParams(CompressPDFBaseParams):
+    """Parameters for compressing a PDF provided as a file."""
+
+    file: Optional[FileParam] = None
+
+
+CompressPDFParams = Union[CompressPDFByDocumentIdParams, CompressPDFByFileParams]
+
+
+class WatermarkType(Enum):
+    TEXT = "text"
+    IMAGE = "image"
+
+
+@dataclass
+class WatermarkPDFBaseParams(PDFGateParams):
+    type: WatermarkType
+    text: Optional[str] = None
+    watermark: Optional[FileParam] = None
+    font: Optional[PdfStandardFont] = None
+    font_size: Optional[int] = None
+    font_color: Optional[str] = None
+    opacity: Optional[float] = None
+    x_position: Optional[int] = None
+    y_position: Optional[int] = None
+    image_width: Optional[int] = None
+    image_height: Optional[int] = None
+    rotate: Optional[float] = None
+    json_response: Optional[bool] = False
+    pre_signed_url_expires_in: Optional[int] = None
+    metadata: Optional[Any] = None
+
+
+@dataclass
+class WatermarkPDFByDocumentIdParams(WatermarkPDFBaseParams):
+    document_id: Optional[str] = None
+
+
+@dataclass
+class WatermarkPDFByFileParams(WatermarkPDFBaseParams):
+    file: Optional[FileParam] = None
+
+
+WatermarkPDFParams = Union[WatermarkPDFByDocumentIdParams, WatermarkPDFByFileParams]