pdfbolt 1.0.0__py3-none-any.whl

pdfbolt/__init__.py

@@ -0,0 +1,114 @@
+from ._version import VERSION
+from .client import PDFBolt
+from .direct_result import DirectConversionResult
+from .errors import (
+    PDFBoltAPIError,
+    PDFBoltConfigurationError,
+    PDFBoltError,
+    PDFBoltNetworkError,
+    PDFBoltValidationError,
+    PDFBoltWebhookSignatureError,
+)
+from .models import (
+    AsyncConversionJob,
+    AsyncConversionWebhookEvent,
+    OneTimeCredits,
+    RateLimitInfo,
+    RateLimitWindow,
+    RecurringCredits,
+    SyncConversionResult,
+    UsageSummary,
+)
+from .types import (
+    AsyncConversionWebhookStatus,
+    AsyncConvertParams,
+    AsyncHtmlParams,
+    AsyncOptions,
+    AsyncTemplateParams,
+    AsyncUrlParams,
+    CompressionLevel,
+    ContentDisposition,
+    ConversionErrorCode,
+    ConversionOptions,
+    DirectConvertParams,
+    DirectHtmlParams,
+    DirectOptions,
+    DirectTemplateParams,
+    DirectUrlParams,
+    DomainCookie,
+    EmulateMediaType,
+    HttpCredentials,
+    Margin,
+    MarginDimension,
+    PageDimension,
+    PaperFormat,
+    PDFBoltCookie,
+    PrintProduction,
+    SyncConversionStatus,
+    SyncConvertParams,
+    SyncHtmlParams,
+    SyncOptions,
+    SyncTemplateParams,
+    SyncUrlParams,
+    UrlCookie,
+    ViewportSize,
+    WaitForSelector,
+    WaitUntil,
+)
+from .webhooks import Webhooks, webhooks
+
+__all__ = [
+    "AsyncConvertParams",
+    "AsyncConversionJob",
+    "AsyncConversionWebhookEvent",
+    "AsyncConversionWebhookStatus",
+    "AsyncHtmlParams",
+    "AsyncOptions",
+    "AsyncTemplateParams",
+    "AsyncUrlParams",
+    "CompressionLevel",
+    "ContentDisposition",
+    "ConversionErrorCode",
+    "ConversionOptions",
+    "DirectConvertParams",
+    "DirectConversionResult",
+    "DirectHtmlParams",
+    "DirectOptions",
+    "DirectTemplateParams",
+    "DirectUrlParams",
+    "DomainCookie",
+    "EmulateMediaType",
+    "HttpCredentials",
+    "Margin",
+    "MarginDimension",
+    "OneTimeCredits",
+    "PDFBolt",
+    "PDFBoltAPIError",
+    "PDFBoltCookie",
+    "PDFBoltConfigurationError",
+    "PDFBoltError",
+    "PDFBoltNetworkError",
+    "PDFBoltValidationError",
+    "PDFBoltWebhookSignatureError",
+    "PageDimension",
+    "PaperFormat",
+    "PrintProduction",
+    "RateLimitInfo",
+    "RateLimitWindow",
+    "RecurringCredits",
+    "SyncConvertParams",
+    "SyncConversionResult",
+    "SyncConversionStatus",
+    "SyncHtmlParams",
+    "SyncOptions",
+    "SyncTemplateParams",
+    "SyncUrlParams",
+    "UrlCookie",
+    "UsageSummary",
+    "VERSION",
+    "ViewportSize",
+    "Webhooks",
+    "WaitForSelector",
+    "WaitUntil",
+    "webhooks",
+]

pdfbolt/_utils.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import base64
+from collections.abc import Mapping
+from typing import Any
+
+from .errors import PDFBoltValidationError
+
+RAW_NESTED_KEYS = {
+    "additionalWebhookHeaders",
+    "additional_webhook_headers",
+    "extraHTTPHeaders",
+    "extra_http_headers",
+    "templateData",
+    "template_data",
+}
+
+API_KEY_OVERRIDES = {
+    "apply_extra_http_headers_to_all_resources": "applyExtraHTTPHeadersToAllResources",
+    "extra_http_headers": "extraHTTPHeaders",
+}
+
+
+def encode_base64(value: str) -> str:
+    return base64.b64encode(value.encode("utf-8")).decode("ascii")
+
+
+def encode_header_footer_templates(params: dict[str, Any]) -> dict[str, Any]:
+    encoded = dict(params)
+    for key in ("header_template", "headerTemplate", "footer_template", "footerTemplate"):
+        value = encoded.get(key)
+        if isinstance(value, str):
+            encoded[key] = encode_base64(value)
+    return encoded
+
+
+def split_request_options(params: Mapping[str, Any]) -> tuple[dict[str, Any], float | None]:
+    body: dict[str, Any] = {}
+    request_timeout = None
+
+    for key, value in params.items():
+        if key == "request_timeout":
+            request_timeout = _optional_timeout(value)
+        else:
+            body[key] = value
+
+    return body, request_timeout
+
+
+def to_api_body(params: Mapping[str, Any]) -> dict[str, Any]:
+    return {_to_api_key(key): _to_api_value(value, key=key) for key, value in params.items()}
+
+
+def require_string_field(params: Mapping[str, Any], field_name: str, method_name: str) -> str:
+    value = params.get(field_name)
+    if not isinstance(value, str):
+        raise PDFBoltValidationError(f"{field_name} is required when using {method_name}().")
+    return value
+
+
+def require_object_field(
+    params: Mapping[str, Any],
+    field_name: str,
+    method_name: str,
+) -> Mapping[str, Any]:
+    value = params.get(field_name)
+    if not isinstance(value, Mapping):
+        raise PDFBoltValidationError(f"{field_name} must be an object when using {method_name}().")
+    return value
+
+
+def merge_params(required: Mapping[str, Any], optional: Mapping[str, Any]) -> dict[str, Any]:
+    return {**required, **optional}
+
+
+def _to_api_value(value: Any, *, key: str) -> Any:
+    if key in RAW_NESTED_KEYS:
+        return value
+
+    if isinstance(value, Mapping):
+        return to_api_body(value)
+
+    if isinstance(value, list):
+        return [_to_api_value(item, key="") for item in value]
+
+    return value
+
+
+def _to_api_key(key: str) -> str:
+    if key in API_KEY_OVERRIDES:
+        return API_KEY_OVERRIDES[key]
+
+    if "_" not in key:
+        return key
+
+    parts = key.split("_")
+    return parts[0] + "".join(part[:1].upper() + part[1:] for part in parts[1:])
+
+
+def _optional_timeout(value: Any) -> float | None:
+    if value is None:
+        return None
+
+    if isinstance(value, int | float) and not isinstance(value, bool):
+        return float(value)
+
+    raise PDFBoltValidationError("request_timeout must be a number of seconds.")

pdfbolt/_version.py

@@ -0,0 +1 @@
+VERSION = "1.0.0"

pdfbolt/client.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import requests
+
+from .http import DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_SECONDS, PDFBoltHttpClient
+from .resources.async_conversions import AsyncConversionsResource
+from .resources.direct import DirectResource
+from .resources.sync import SyncResource
+from .resources.usage import UsageResource
+from .webhooks import Webhooks, webhooks
+
+
+class PDFBolt:
+    webhooks: Webhooks = webhooks
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+        session: requests.Session | None = None,
+    ) -> None:
+        http = PDFBoltHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            request_timeout=request_timeout,
+            session=session,
+        )
+
+        self.direct = DirectResource(http)
+        self.sync = SyncResource(http)
+        self.async_conversions = AsyncConversionsResource(http)
+        self.usage = UsageResource(http)

pdfbolt/direct_result.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from .errors import PDFBoltNetworkError
+from .models import RateLimitInfo
+from .rate_limit import read_header, read_number_header, read_rate_limit_info
+
+
+class DirectConversionResult:
+    def __init__(self, *, body: bytes, headers: Mapping[str, str]) -> None:
+        self.headers = headers
+        self.content_type = _normalize_content_type(read_header(headers, "content-type"))
+        self.content_disposition = read_header(headers, "content-disposition")
+        self.conversion_cost = read_number_header(headers, "x-pdfbolt-conversion-cost")
+        self.filename = _parse_content_disposition_filename(self.content_disposition)
+        self.rate_limit: RateLimitInfo = read_rate_limit_info(headers)
+        self.base64: str | None
+
+        if self.content_type == "text/plain":
+            try:
+                self.base64 = body.decode("utf-8").strip()
+                if not self.base64:
+                    raise ValueError("empty Base64 response")
+                self.buffer = base64.b64decode(self.base64, validate=True)
+            except (UnicodeDecodeError, binascii.Error, ValueError) as error:
+                raise PDFBoltNetworkError(
+                    "PDFBolt API returned a malformed Base64 direct response."
+                ) from error
+        else:
+            self.base64 = None
+            self.buffer = body
+
+    @property
+    def size(self) -> int:
+        return len(self.buffer)
+
+    def save(self, file_path: str | Path) -> None:
+        Path(file_path).write_bytes(self.buffer)
+
+
+def _normalize_content_type(value: str | None) -> str:
+    if not value:
+        return "application/pdf"
+
+    content_types = [
+        part.split(";", 1)[0].strip().lower()
+        for part in value.split(",")
+        if part.split(";", 1)[0].strip()
+    ]
+    if "application/pdf" in content_types:
+        return "application/pdf"
+    if "text/plain" in content_types:
+        return "text/plain"
+
+    return content_types[0] if content_types else "application/pdf"
+
+
+def _parse_content_disposition_filename(content_disposition: str | None) -> str | None:
+    if not content_disposition:
+        return None
+
+    match = re.search(r'(?:^|;)\s*filename="?([^";]+)"?', content_disposition, re.IGNORECASE)
+    return match.group(1) if match else None

pdfbolt/errors.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from .models import RateLimitInfo
+from .rate_limit import read_rate_limit_info
+
+
+class PDFBoltError(Exception):
+    """Base class for all PDFBolt SDK errors."""
+
+
+class PDFBoltAPIError(PDFBoltError):
+    """Raised when the PDFBolt API returns an HTTP error response."""
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        status_code: int,
+        timestamp: str | None = None,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        raw_body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.timestamp = timestamp
+        self.error_code = error_code
+        self.error_message = error_message
+        self.rate_limit: RateLimitInfo = read_rate_limit_info(headers)
+        self.headers = headers
+        self.raw_body = raw_body
+
+
+class PDFBoltNetworkError(PDFBoltError):
+    """Raised when the SDK did not receive a usable HTTP response."""
+
+
+class PDFBoltWebhookSignatureError(PDFBoltError):
+    """Raised when webhook signature verification fails."""
+
+
+class PDFBoltValidationError(PDFBoltError):
+    """Raised before a request is sent when high-level helper parameters are invalid."""
+
+
+class PDFBoltConfigurationError(PDFBoltError):
+    """Raised when the SDK client is missing required configuration."""

pdfbolt/http.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+import requests
+
+from ._version import VERSION
+from .errors import PDFBoltAPIError, PDFBoltConfigurationError, PDFBoltNetworkError
+
+DEFAULT_BASE_URL = "https://api.pdfbolt.com"
+DEFAULT_REQUEST_TIMEOUT_SECONDS = 120.0
+
+
+class PDFBoltHttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+        session: requests.Session | None = None,
+    ) -> None:
+        if not api_key:
+            raise PDFBoltConfigurationError("PDFBolt API key is required.")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._request_timeout = request_timeout
+        self._session = session or requests.Session()
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Mapping[str, Any] | None = None,
+        request_timeout: float | None = None,
+    ) -> tuple[dict[str, Any], Mapping[str, str]]:
+        response = self._request(
+            method,
+            path,
+            body=body,
+            request_timeout=request_timeout,
+            accept="application/json",
+        )
+        try:
+            data = response.json()
+        except ValueError as error:
+            raise PDFBoltNetworkError(
+                f"PDFBolt API returned a malformed JSON response for {path} "
+                f"(status {response.status_code})."
+            ) from error
+
+        if not isinstance(data, dict):
+            raise PDFBoltNetworkError(
+                f"PDFBolt API returned a malformed JSON response for {path} "
+                f"(status {response.status_code})."
+            )
+
+        return data, response.headers
+
+    def request_binary(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Mapping[str, Any] | None = None,
+        request_timeout: float | None = None,
+    ) -> tuple[bytes, Mapping[str, str]]:
+        response = self._request(
+            method,
+            path,
+            body=body,
+            request_timeout=request_timeout,
+            accept="application/pdf, text/plain, application/json",
+        )
+        return response.content, response.headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Mapping[str, Any] | None,
+        request_timeout: float | None,
+        accept: str,
+    ) -> requests.Response:
+        timeout = self._request_timeout if request_timeout is None else request_timeout
+        headers = self._headers(accept=accept, has_body=body is not None)
+
+        try:
+            response = self._session.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+                json=body,
+                timeout=timeout,
+            )
+        except requests.Timeout as error:
+            raise PDFBoltNetworkError(f"PDFBolt request timed out after {timeout}s.") from error
+        except Exception as error:
+            raise PDFBoltNetworkError(
+                "PDFBolt request failed before receiving a response."
+            ) from error
+
+        if response.status_code >= 400:
+            raise _create_api_error(response)
+
+        return response
+
+    def _headers(self, *, accept: str, has_body: bool) -> dict[str, str]:
+        headers = {
+            "Accept": accept,
+            "API-KEY": self._api_key,
+            "User-Agent": f"pdfbolt-python/{VERSION}",
+        }
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+
+def _create_api_error(response: requests.Response) -> PDFBoltAPIError:
+    raw_body = response.text
+    parsed = _parse_json_object(raw_body)
+    error_message = _read_string(parsed, "errorMessage")
+    message = (
+        error_message
+        or response.reason
+        or (f"PDFBolt API request failed with status {response.status_code}.")
+    )
+
+    return PDFBoltAPIError(
+        message=message,
+        status_code=response.status_code,
+        timestamp=_read_string(parsed, "timestamp"),
+        error_code=_read_string(parsed, "errorCode"),
+        error_message=error_message,
+        headers=response.headers,
+        raw_body=raw_body,
+    )
+
+
+def _parse_json_object(raw_body: str) -> dict[str, Any] | None:
+    try:
+        parsed = json.loads(raw_body)
+    except json.JSONDecodeError:
+        return None
+
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _read_string(source: dict[str, Any] | None, key: str) -> str | None:
+    value = source.get(key) if source else None
+    return value if isinstance(value, str) else None