zpljet 1.0.0__py3-none-any.whl

zpljet/__init__.py

@@ -0,0 +1,41 @@
+"""Official Python SDK for the ZPLJet API."""
+
+from ._client import AsyncZplJet, Transport, TransportResponse, ZplJet
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConversionFailedError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    ServiceUnavailableError,
+    ZplJetError,
+)
+from ._types import HostedLabel, LabelData
+from ._version import __version__
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncZplJet",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConversionFailedError",
+    "HostedLabel",
+    "LabelData",
+    "PayloadTooLargeError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "Transport",
+    "TransportResponse",
+    "ZplJet",
+    "ZplJetError",
+    "__version__",
+]

zpljet/_client.py

@@ -0,0 +1,499 @@
+"""ZPLJet API client — sync (:class:`ZplJet`) and async (:class:`AsyncZplJet`)."""
+
+from __future__ import annotations
+
+import asyncio
+import email.utils
+import http.client
+import json
+import math
+import random
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Callable, Literal, cast, overload
+
+from ._errors import APIConnectionError, APIError, APITimeoutError, ZplJetError
+from ._types import HostedLabel, LabelData
+from ._version import __version__
+
+__all__ = ["AsyncZplJet", "Transport", "TransportResponse", "ZplJet"]
+
+DEFAULT_BASE_URL = "https://api.zpljet.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+MAX_RETRIES_CAP = 10
+
+_MAX_RETRY_DELAY = 30.0
+_BASE_RETRY_DELAY = 0.5
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
+
+
+def _normalize_max_retries(value: int) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        raise ValueError("max_retries must be a finite integer >= 0")
+    return min(value, MAX_RETRIES_CAP)
+
+
+def _normalize_timeout(value: float) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError("timeout must be a finite number > 0")
+    timeout = float(value)
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError("timeout must be a finite number > 0")
+    return timeout
+
+
+def _assert_secure_base_url(base_url: str, allow_insecure_http: bool) -> None:
+    """Refuse to send the API key over plaintext http to a non-loopback host."""
+    parsed = urllib.parse.urlparse(base_url)
+    if parsed.scheme == "https":
+        return
+    if parsed.scheme == "http":
+        host = (parsed.hostname or "").lower()
+        if allow_insecure_http or host in _LOOPBACK_HOSTS:
+            return
+        raise ZplJetError(
+            f"Refusing to send your API key over plaintext http:// to {parsed.netloc}. "
+            "Use https, or pass allow_insecure_http=True for local/testing."
+        )
+    raise ZplJetError(f"Unsupported base_url scheme: {parsed.scheme or '(none)'}")
+
+
+@dataclass(frozen=True)
+class TransportResponse:
+    """A raw HTTP response, as returned by a :data:`Transport`."""
+
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+    def header(self, name: str) -> str | None:
+        """Case-insensitive header lookup."""
+        lowered = name.lower()
+        for key, value in self.headers.items():
+            if key.lower() == lowered:
+                return value
+        return None
+
+
+#: Sends one POST request: ``(url, body, headers, timeout) -> TransportResponse``.
+#: Must raise :class:`APITimeoutError` / :class:`APIConnectionError` on
+#: transport failures. Inject a custom one for proxies or tests.
+Transport = Callable[[str, bytes, Mapping[str, str], float], TransportResponse]
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> urllib.request.Request | None:
+        return None
+
+
+_NO_REDIRECT_OPENER = urllib.request.build_opener(_NoRedirectHandler())
+
+
+def _urllib_transport(
+    url: str, body: bytes, headers: Mapping[str, str], timeout: float
+) -> TransportResponse:
+    """Send one request with the standard library."""
+    request = urllib.request.Request(url, data=body, headers=dict(headers), method="POST")
+    try:
+        with _NO_REDIRECT_OPENER.open(request, timeout=timeout) as response:
+            return TransportResponse(
+                status=response.status,
+                headers=dict(response.headers.items()),
+                body=response.read(),
+            )
+    except urllib.error.HTTPError as exc:
+        with exc:
+            try:
+                error_body = exc.read()
+            except (http.client.HTTPException, OSError) as read_exc:
+                raise APIConnectionError(
+                    f"Request to {url} failed while reading the response: {read_exc}"
+                ) from read_exc
+            return TransportResponse(
+                status=exc.code,
+                headers=dict(exc.headers.items()) if exc.headers else {},
+                body=error_body,
+            )
+    except socket.timeout as exc:
+        raise APITimeoutError(f"Request to {url} timed out after {timeout}s") from exc
+    except urllib.error.URLError as exc:
+        if isinstance(exc.reason, socket.timeout):
+            raise APITimeoutError(f"Request to {url} timed out after {timeout}s") from exc
+        raise APIConnectionError(f"Request to {url} failed: {exc.reason}") from exc
+    except http.client.HTTPException as exc:
+        raise APIConnectionError(f"Request to {url} failed: {exc!r}") from exc
+    except OSError as exc:
+        raise APIConnectionError(f"Request to {url} failed: {exc}") from exc
+
+
+class ZplJet:
+    """Synchronous ZPLJet API client with automatic retries.
+
+    :param api_key: Your ZPLJet API key (``zpl_…``), created in the dashboard
+        at https://zpljet.com/dashboard. Keep it server-side.
+    :param base_url: API origin. Defaults to ``https://api.zpljet.com``.
+    :param timeout: Per-attempt timeout in seconds. Defaults to ``60``.
+    :param max_retries: How many times a failed request is automatically
+        retried. Defaults to ``2``. Set ``0`` to disable.
+    :param transport: Custom :data:`Transport` — useful for proxies,
+        instrumentation, and tests. Defaults to a stdlib ``urllib`` transport.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        allow_insecure_http: bool = False,
+        transport: Transport | None = None,
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ZplJetError(
+                "Missing API key. Pass ZplJet(api_key='zpl_…') — create one at "
+                "https://zpljet.com/dashboard."
+            )
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        _assert_secure_base_url(self.base_url, allow_insecure_http)
+        self.timeout = _normalize_timeout(timeout)
+        self.max_retries = _normalize_max_retries(max_retries)
+        self._transport: Transport = transport or _urllib_transport
+
+    @overload
+    def convert(
+        self,
+        zpl: str,
+        *,
+        dpmm: int | None = ...,
+        width_mm: float | None = ...,
+        height_mm: float | None = ...,
+        format: Literal["pdf", "png"] | None = ...,
+        output: Literal["url"],
+        timeout: float | None = ...,
+        max_retries: int | None = ...,
+    ) -> HostedLabel: ...
+
+    @overload
+    def convert(
+        self,
+        zpl: str,
+        *,
+        dpmm: int | None = ...,
+        width_mm: float | None = ...,
+        height_mm: float | None = ...,
+        format: Literal["pdf", "png"] | None = ...,
+        output: Literal["data", None] = ...,
+        timeout: float | None = ...,
+        max_retries: int | None = ...,
+    ) -> LabelData: ...
+
+    def convert(
+        self,
+        zpl: str,
+        *,
+        dpmm: int | None = None,
+        width_mm: float | None = None,
+        height_mm: float | None = None,
+        format: Literal["pdf", "png"] | None = None,
+        output: Literal["data", "url"] | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> LabelData | HostedLabel:
+        """Convert ZPL to a PDF or PNG.
+
+        With ``output="data"`` (the default) the API returns the raw file
+        bytes and stores nothing. With ``output="url"`` (paid plans) the file
+        is hosted and a public link is returned.
+
+        :param zpl: Raw ZPL — one or more ``^XA…^XZ`` label blocks. Max 512 KB.
+        :param dpmm: Print density in dots/mm: 6, 8 (default, 203 dpi),
+            12 (300 dpi), or 24 (600 dpi).
+        :param width_mm: Physical label width in millimeters (default 101.6).
+        :param height_mm: Physical label height in millimeters (default 152.4).
+        :param format: ``"pdf"`` (default) or ``"png"``.
+        :param output: ``"data"`` (default) or ``"url"`` (paid plans).
+        :param timeout: Per-attempt timeout override for this call, seconds.
+        :param max_retries: Retry-count override for this call.
+
+        :raises BadRequestError: the ZPL or parameters failed validation (400)
+        :raises AuthenticationError: missing or invalid API key (401)
+        :raises QuotaExceededError: monthly quota used up (402)
+        :raises PermissionDeniedError: hosting not allowed for this account (403)
+        :raises RateLimitError: rate limit exceeded, after retries (429)
+        :raises ConversionFailedError: the engine could not render the ZPL (502)
+        :raises APIConnectionError: network failure or timeout, after retries
+        """
+        return self._convert(
+            zpl,
+            dpmm=dpmm,
+            width_mm=width_mm,
+            height_mm=height_mm,
+            format=format,
+            output=output,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    def _convert(
+        self,
+        zpl: str,
+        *,
+        dpmm: int | None,
+        width_mm: float | None,
+        height_mm: float | None,
+        format: Literal["pdf", "png"] | None,
+        output: Literal["data", "url"] | None,
+        timeout: float | None,
+        max_retries: int | None,
+    ) -> LabelData | HostedLabel:
+        body: dict[str, Any] = {"zpl": zpl}
+        if dpmm is not None:
+            body["dpmm"] = dpmm
+        if width_mm is not None:
+            body["widthMm"] = width_mm
+        if height_mm is not None:
+            body["heightMm"] = height_mm
+        if format is not None:
+            body["format"] = format
+        if output is not None:
+            body["output"] = output
+
+        response = self._request_with_retries("/v1/convert", body, timeout, max_retries)
+
+        if output == "url":
+            return _parse_hosted_label(response.body)
+        return LabelData(
+            data=response.body,
+            content_type=response.header("content-type") or "application/octet-stream",
+            id=response.header("x-conversion-id") or "",
+        )
+
+    def _request_with_retries(
+        self,
+        path: str,
+        body: dict[str, Any],
+        timeout: float | None,
+        max_retries: int | None,
+    ) -> TransportResponse:
+        """POST ``body`` as JSON, retrying transient failures."""
+        url = f"{self.base_url}{path}"
+        payload = json.dumps(body).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "X-API-Key": self.api_key,
+            "User-Agent": f"zpljet-python/{__version__}",
+        }
+        retries = (
+            self.max_retries
+            if max_retries is None
+            else _normalize_max_retries(max_retries)
+        )
+        attempt_timeout = self.timeout if timeout is None else _normalize_timeout(timeout)
+
+        attempt = 0
+        while True:
+            error: APIError | APIConnectionError
+            header_retry_after: float | None = None
+            try:
+                response = self._transport(url, payload, headers, attempt_timeout)
+                if 200 <= response.status < 300:
+                    return response
+                error = APIError.from_response(response.status, _parse_error_body(response.body))
+                header_retry_after = _parse_retry_after_header(response.header("retry-after"))
+            except APIConnectionError as exc:
+                error = exc
+
+            if attempt >= retries or not _is_retryable(error):
+                raise error
+            _sleep(_retry_delay(error, attempt, header_retry_after))
+            attempt += 1
+
+
+class AsyncZplJet:
+    """Async ZPLJet client backed by :func:`asyncio.to_thread`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        allow_insecure_http: bool = False,
+        transport: Transport | None = None,
+    ) -> None:
+        self._client = ZplJet(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            allow_insecure_http=allow_insecure_http,
+            transport=transport,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._client.base_url
+
+    @overload
+    async def convert(
+        self,
+        zpl: str,
+        *,
+        dpmm: int | None = ...,
+        width_mm: float | None = ...,
+        height_mm: float | None = ...,
+        format: Literal["pdf", "png"] | None = ...,
+        output: Literal["url"],
+        timeout: float | None = ...,
+        max_retries: int | None = ...,
+    ) -> HostedLabel: ...
+
+    @overload
+    async def convert(
+        self,
+        zpl: str,
+        *,
+        dpmm: int | None = ...,
+        width_mm: float | None = ...,
+        height_mm: float | None = ...,
+        format: Literal["pdf", "png"] | None = ...,
+        output: Literal["data", None] = ...,
+        timeout: float | None = ...,
+        max_retries: int | None = ...,
+    ) -> LabelData: ...
+
+    async def convert(
+        self,
+        zpl: str,
+        *,
+        dpmm: int | None = None,
+        width_mm: float | None = None,
+        height_mm: float | None = None,
+        format: Literal["pdf", "png"] | None = None,
+        output: Literal["data", "url"] | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> LabelData | HostedLabel:
+        """Async :meth:`ZplJet.convert` — same parameters and errors."""
+        return await asyncio.to_thread(
+            self._client._convert,
+            zpl,
+            dpmm=dpmm,
+            width_mm=width_mm,
+            height_mm=height_mm,
+            format=format,
+            output=output,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+
+def _parse_error_body(body: bytes) -> dict[str, Any]:
+    """Parse the structured ``{"error": {…}}`` body; tolerate anything else."""
+    try:
+        parsed = json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return {}
+    if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict):
+        return cast(dict[str, Any], parsed["error"])
+    return {}
+
+
+def _parse_success_object(body: bytes) -> dict[str, Any]:
+    try:
+        parsed = json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise ZplJetError("Invalid JSON in successful API response") from exc
+    if not isinstance(parsed, dict):
+        raise ZplJetError("Invalid payload in successful API response")
+    return parsed
+
+
+def _required_string(payload: dict[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value:
+        raise ZplJetError(f"Invalid {key} in successful API response")
+    return value
+
+
+def _parse_hosted_label(body: bytes) -> HostedLabel:
+    payload = _parse_success_object(body)
+    pages = payload.get("pages")
+    retention_days = payload.get("retentionDays")
+    if not isinstance(pages, int) or isinstance(pages, bool) or pages < 1:
+        raise ZplJetError("Invalid pages in successful API response")
+    if (
+        not isinstance(retention_days, int)
+        or isinstance(retention_days, bool)
+        or retention_days < 1
+    ):
+        raise ZplJetError("Invalid retentionDays in successful API response")
+    return HostedLabel(
+        id=_required_string(payload, "id"),
+        url=_required_string(payload, "url"),
+        pages=pages,
+        retention_days=retention_days,
+        expires_at=_required_string(payload, "expiresAt"),
+    )
+
+
+def _is_retryable(error: APIError | APIConnectionError) -> bool:
+    """Return whether a failure is transient."""
+    if isinstance(error, APIConnectionError):
+        return True
+    if error.status == 429:
+        return True
+    return error.status >= 500 and error.code != "conversion_failed"
+
+
+def _parse_retry_after_header(value: str | None) -> float | None:
+    """Parse delta-seconds or an HTTP date."""
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, when.timestamp() - time.time())
+
+
+def _retry_delay(
+    error: APIError | APIConnectionError,
+    attempt: int,
+    header_retry_after: float | None = None,
+) -> float:
+    """Calculate the next retry delay."""
+    if isinstance(error, APIError):
+        retry_after = error.raw.get("retryAfter")
+        if isinstance(retry_after, (int, float)) and not isinstance(retry_after, bool):
+            return min(max(float(retry_after), 0.0), _MAX_RETRY_DELAY)
+    if header_retry_after is not None:
+        return min(header_retry_after, _MAX_RETRY_DELAY)
+    backoff = _BASE_RETRY_DELAY * (2.0**attempt)
+    return min(backoff + backoff * 0.25 * random.random(), _MAX_RETRY_DELAY)
+
+
+def _sleep(seconds: float) -> None:
+    if seconds > 0:
+        time.sleep(seconds)

zpljet/_errors.py

@@ -0,0 +1,172 @@
+"""Typed errors for the ZPLJet API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConversionFailedError",
+    "PayloadTooLargeError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "ZplJetError",
+]
+
+
+class ZplJetError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class APIConnectionError(ZplJetError):
+    """A network failure prevented a usable response."""
+
+    def __init__(self, message: str = "Connection error") -> None:
+        super().__init__(message)
+
+
+class APITimeoutError(APIConnectionError):
+    """A single attempt exceeded the configured timeout."""
+
+    def __init__(self, message: str = "Request timed out") -> None:
+        super().__init__(message)
+
+
+class APIError(ZplJetError):
+    """An HTTP error response from the API."""
+
+    status: int
+    """HTTP status code."""
+
+    code: str | None
+    """Stable machine-readable code — safe to branch on."""
+
+    doc_url: str | None
+    """Link to the docs entry for this code."""
+
+    raw: dict[str, Any]
+    """The raw parsed ``error`` object, including any context fields."""
+
+    def __init__(self, status: int, message: str, raw: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        raw = raw or {}
+        self.status = status
+        self.code = raw.get("code") if isinstance(raw.get("code"), str) else None
+        self.doc_url = raw.get("docUrl") if isinstance(raw.get("docUrl"), str) else None
+        self.raw = raw
+
+    @property
+    def message(self) -> str:
+        """The human-readable error message (may change; don't parse it)."""
+        return str(self.args[0]) if self.args else ""
+
+    @staticmethod
+    def from_response(status: int, raw: dict[str, Any]) -> APIError:
+        """Build the most specific error subclass for a response."""
+        message = raw.get("message")
+        if not isinstance(message, str) or not message:
+            message = f"HTTP {status} error from the ZPLJet API"
+        cls = _ERROR_CLASSES.get(str(raw.get("code")), APIError)
+        return cls(status, message, raw)
+
+
+class BadRequestError(APIError):
+    """400 ``invalid_request`` response."""
+
+    def __init__(self, status: int, message: str, raw: dict[str, Any] | None = None) -> None:
+        super().__init__(status, message, raw)
+        self.param: str | None = _str_field(self.raw, "param")
+        """Dot-path of the invalid field, e.g. ``"zpl"`` or ``"dpmm"``."""
+
+
+class AuthenticationError(APIError):
+    """401 ``missing_api_key`` or ``invalid_api_key`` response."""
+
+
+class PayloadTooLargeError(APIError):
+    """413 ``payload_too_large`` — request body exceeded the API limit."""
+
+
+class QuotaExceededError(APIError):
+    """402 ``quota_exceeded`` — the monthly conversion quota is used up."""
+
+    def __init__(self, status: int, message: str, raw: dict[str, Any] | None = None) -> None:
+        super().__init__(status, message, raw)
+        self.plan: str | None = _str_field(self.raw, "plan")
+        """Plan id the account is on (e.g. ``"free"``)."""
+        self.quota: int | None = _int_field(self.raw, "quota")
+        """Monthly quota for that plan."""
+        self.used: int | None = _int_field(self.raw, "used")
+        """Conversions used so far this month."""
+        self.resets_at: str | None = _str_field(self.raw, "resetsAt")
+        """ISO 8601 UTC timestamp — when the quota resets."""
+
+
+class PermissionDeniedError(APIError):
+    """403 ``hosting_not_allowed`` or ``no_retention_enforced`` response."""
+
+
+class RateLimitError(APIError):
+    """429 ``rate_limit_exceeded`` response."""
+
+    def __init__(self, status: int, message: str, raw: dict[str, Any] | None = None) -> None:
+        super().__init__(status, message, raw)
+        self.retry_after: float | None = _num_field(self.raw, "retryAfter")
+        """Seconds to wait before retrying."""
+        self.retry_at: str | None = _str_field(self.raw, "retryAt")
+        """ISO 8601 UTC timestamp — when to retry."""
+
+
+class ConversionFailedError(APIError):
+    """502 ``conversion_failed`` response."""
+
+    def __init__(self, status: int, message: str, raw: dict[str, Any] | None = None) -> None:
+        super().__init__(status, message, raw)
+        self.conversion_id: str | None = _str_field(self.raw, "conversionId")
+        """Id of the failed attempt — quote it when contacting support."""
+
+
+class ServiceUnavailableError(APIError):
+    """503 ``service_unavailable`` response."""
+
+    def __init__(self, status: int, message: str, raw: dict[str, Any] | None = None) -> None:
+        super().__init__(status, message, raw)
+        self.retry_after: float | None = _num_field(self.raw, "retryAfter")
+        """Seconds to wait before retrying."""
+
+
+_ERROR_CLASSES: dict[str, type[APIError]] = {
+    "invalid_request": BadRequestError,
+    "missing_api_key": AuthenticationError,
+    "invalid_api_key": AuthenticationError,
+    "payload_too_large": PayloadTooLargeError,
+    "quota_exceeded": QuotaExceededError,
+    "hosting_not_allowed": PermissionDeniedError,
+    "no_retention_enforced": PermissionDeniedError,
+    "rate_limit_exceeded": RateLimitError,
+    "conversion_failed": ConversionFailedError,
+    "service_unavailable": ServiceUnavailableError,
+}
+
+
+def _str_field(raw: dict[str, Any], key: str) -> str | None:
+    value = raw.get(key)
+    return value if isinstance(value, str) else None
+
+
+def _int_field(raw: dict[str, Any], key: str) -> int | None:
+    value = raw.get(key)
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _num_field(raw: dict[str, Any], key: str) -> float | None:
+    value = raw.get(key)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value)

zpljet/_types.py

@@ -0,0 +1,43 @@
+"""Result types for the ZPLJet API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["HostedLabel", "LabelData"]
+
+
+@dataclass(frozen=True)
+class LabelData:
+    """Result of a conversion with ``output="data"`` (the default)."""
+
+    data: bytes
+    """The rendered file bytes (PDF or PNG)."""
+
+    content_type: str
+    """``"application/pdf"`` or ``"image/png"``."""
+
+    id: str
+    """Conversion id (from the ``X-Conversion-Id`` response header)."""
+
+
+@dataclass(frozen=True)
+class HostedLabel:
+    """Result of a conversion with ``output="url"`` (hosted, paid plans)."""
+
+    id: str
+    """Conversion id."""
+
+    url: str
+    """Public URL to the hosted file. Works until the file is deleted at
+    ``expires_at``."""
+
+    pages: int
+    """Number of pages rendered (one per ``^XA…^XZ`` block)."""
+
+    retention_days: int
+    """How many days the file is retained."""
+
+    expires_at: str
+    """ISO 8601 UTC timestamp — when the hosted file is deleted and its URL
+    stops working."""

zpljet/_version.py

@@ -0,0 +1,3 @@
+"""SDK version."""
+
+__version__ = "1.0.0"

zpljet-1.0.0.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: zpljet
+Version: 1.0.0
+Summary: Official Python SDK for the ZPLJet API — fast ZPL to PDF/PNG conversion
+Project-URL: Homepage, https://zpljet.com/docs
+Project-URL: Documentation, https://zpljet.com/docs/sdks
+Project-URL: Repository, https://github.com/zpljet/zpljet-python
+Project-URL: Changelog, https://github.com/zpljet/zpljet-python/blob/main/CHANGELOG.md
+Author-email: ZPLJet <support@zpljet.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: barcode,label,pdf,png,printing,shipping-label,zebra,zpl,zpljet
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zpljet
+
+Official Python SDK for the [ZPLJet](https://zpljet.com) API — fast ZPL → PDF/PNG conversion.
+
+[![PyPI version](https://img.shields.io/pypi/v/zpljet.svg)](https://pypi.org/project/zpljet/)
+[![CI](https://github.com/zpljet/zpljet-python/actions/workflows/ci.yml/badge.svg)](https://github.com/zpljet/zpljet-python/actions/workflows/ci.yml)
+[![license](https://img.shields.io/pypi/l/zpljet.svg)](https://github.com/zpljet/zpljet-python/blob/main/LICENSE)
+
+- **Zero dependencies** — a single small client on top of the stdlib
+- **Fully typed** (`py.typed`) — parameters, results, and every API error code
+- **Reliable by default** — automatic retries with exponential backoff (honoring `Retry-After`), per-request timeouts, typed exceptions
+- **Sync and async** — `ZplJet` for scripts and servers, `AsyncZplJet` for asyncio code
+- Python ≥ 3.9
+
+## Installation
+
+Choose one:
+
+```sh
+pip install zpljet
+uv add zpljet
+poetry add zpljet
+```
+
+## Quickstart
+
+Create an API key in the [dashboard](https://zpljet.com/dashboard) (keys look like `zpl_…`), then:
+
+```python
+import os
+from pathlib import Path
+
+from zpljet import ZplJet
+
+zpljet = ZplJet(api_key=os.environ["ZPLJET_API_KEY"])
+
+label = zpljet.convert(zpl="^XA^FO50,50^A0N,50,50^FDHello^FS^XZ")
+
+Path("label.pdf").write_bytes(label.data)
+```
+
+> **Keep your API key server-side.** Anyone with the key can spend your quota.
+
+## Usage
+
+### Convert to PDF or PNG
+
+`convert()` accepts every parameter of [`POST /v1/convert`](https://zpljet.com/docs/api-reference):
+
+```python
+label = zpljet.convert(
+    zpl="^XA^FO50,50^A0N,50,50^FDHello^FS^XZ",
+    format="png",     # "pdf" (default) | "png"
+    dpmm=12,          # 6 | 8 (default, 203 dpi) | 12 (300 dpi) | 24 (600 dpi)
+    width_mm=101.6,   # label width, default 4 in
+    height_mm=152.4,  # label height, default 6 in
+)
+
+label.data          # bytes — the file
+label.content_type  # "application/pdf" | "image/png"
+label.id            # conversion id (shows up in your dashboard)
+```
+
+### Hosted URLs (paid plans)
+
+Pass `output="url"` to have ZPLJet host the file and return a public link
+instead of the bytes. Files are retained for your account's retention window
+(a dashboard setting, up to your plan's maximum).
+
+```python
+hosted = zpljet.convert(zpl="^XA^FO50,50^A0N,50,50^FDHello^FS^XZ", output="url")
+
+hosted.url             # public URL to the PDF (works until the file is deleted)
+hosted.pages           # pages rendered (one per ^XA…^XZ block)
+hosted.retention_days  # how long the file is kept
+hosted.expires_at      # when the file is deleted and the URL stops working (ISO 8601, UTC)
+```
+
+The return type narrows automatically: `output="url"` gives a `HostedLabel`,
+everything else a `LabelData`.
+
+### Async
+
+`AsyncZplJet` has the identical interface for asyncio code:
+
+```python
+from zpljet import AsyncZplJet
+
+zpljet = AsyncZplJet(api_key=os.environ["ZPLJET_API_KEY"])
+label = await zpljet.convert(zpl="^XA^FO50,50^A0N,50,50^FDHello^FS^XZ")
+```
+
+The async client runs the dependency-free transport in a worker thread. Bound
+large batches with a semaphore; see
+[`examples/05_async_batch.py`](https://github.com/zpljet/zpljet-python/blob/main/examples/05_async_batch.py).
+
+### Error handling
+
+Every API error code maps to a dedicated exception, so you branch with
+`except` — no string matching:
+
+```python
+from zpljet import (
+    ZplJet,
+    APIConnectionError,
+    BadRequestError,
+    ConversionFailedError,
+    QuotaExceededError,
+    RateLimitError,
+)
+
+try:
+    label = zpljet.convert(zpl=zpl)
+except BadRequestError as err:
+    print(f"Invalid request ({err.param}): {err.message}")
+except QuotaExceededError as err:
+    print(f"Quota used up ({err.used}/{err.quota}), resets {err.resets_at}")
+except RateLimitError as err:
+    print(f"Rate limited — retry after {err.retry_after}s")
+except ConversionFailedError as err:
+    print(f"Engine rejected the ZPL (conversion {err.conversion_id})")
+except APIConnectionError as err:
+    print(f"Network problem: {err}")
+```
+
+| Exception | Status | `error.code` | Extra fields |
+| --- | --- | --- | --- |
+| `BadRequestError` | 400 | `invalid_request` | `param` |
+| `AuthenticationError` | 401 | `missing_api_key` · `invalid_api_key` | — |
+| `QuotaExceededError` | 402 | `quota_exceeded` | `plan`, `quota`, `used`, `resets_at` |
+| `PermissionDeniedError` | 403 | `hosting_not_allowed` · `no_retention_enforced` | — |
+| `PayloadTooLargeError` | 413 | `payload_too_large` | — |
+| `RateLimitError` | 429 | `rate_limit_exceeded` | `retry_after`, `retry_at` |
+| `ConversionFailedError` | 502 | `conversion_failed` | `conversion_id` |
+| `ServiceUnavailableError` | 503 | `service_unavailable` | `retry_after` |
+| `APIError` | any | anything else | `status`, `code`, `raw` |
+| `APITimeoutError` | — | (an attempt timed out) | — |
+| `APIConnectionError` | — | (request never got a response) | — |
+
+All of these extend `ZplJetError`, and every HTTP error carries `status`,
+`code`, `doc_url`, and the raw error payload in `raw`. Full code reference:
+[zpljet.com/docs/errors](https://zpljet.com/docs/errors).
+
+### Retries
+
+Rate limits, transient 5xx responses, timeouts, and network failures retry up
+to twice by default. Retries use exponential backoff and honor `Retry-After`.
+`conversion_failed` is never retried.
+
+```python
+# Client-wide
+zpljet = ZplJet(api_key=key, max_retries=5)
+
+# Or per request
+zpljet.convert(zpl=zpl, max_retries=0)  # fail fast
+```
+
+### Timeouts
+
+Each attempt has a 60-second timeout by default:
+
+```python
+zpljet = ZplJet(api_key=key, timeout=10.0)
+
+# Per request:
+zpljet.convert(zpl=zpl, timeout=5.0)
+```
+
+A timed-out attempt raises `APITimeoutError` (after retries).
+
+### Configuration
+
+```python
+zpljet = ZplJet(
+    api_key="zpl_…",                     # required
+    base_url="https://api.zpljet.com",   # default
+    timeout=60.0,                        # per-attempt timeout, seconds
+    max_retries=2,                       # automatic retries
+    transport=my_transport,              # custom transport (proxies, tests)
+)
+```
+
+The default transport uses stdlib `urllib`. For connection pooling, inject any
+callable matching `(url, body, headers, timeout) -> TransportResponse`.
+
+## Examples
+
+Runnable scripts live in [`examples/`](https://github.com/zpljet/zpljet-python/tree/main/examples):
+
+```sh
+ZPLJET_API_KEY=zpl_… python examples/01_convert_to_pdf.py
+```
+
+## Contributing & development
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+ruff check .
+mypy
+pytest
+
+ZPLJET_API_KEY=zpl_… pytest tests/test_e2e.py
+```
+
+## License
+
+[MIT](https://github.com/zpljet/zpljet-python/blob/main/LICENSE)

zpljet-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+zpljet/__init__.py,sha256=ywvsyJIMlws35IdKTaeViGtCacooOhHVxeOOVDK1gdE,939
+zpljet/_client.py,sha256=La8mUbL_03PcLw8UGiD7WCo23dPgwPrpbNwvCdOjZp4,17459
+zpljet/_errors.py,sha256=hdcOdJYhBSJGhSag5fYwkuzoNZQdEeEtIttCLUmry38,5932
+zpljet/_types.py,sha256=-d-_xsLane3ujpTU4M-7kCz6f-pQXJOYTcLxOJJQjAc,1033
+zpljet/_version.py,sha256=LJGvGF-KxOob9POgX213X7Wdm0sk0M4mvoHNldEZKwI,42
+zpljet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zpljet-1.0.0.dist-info/METADATA,sha256=x7j3ks_BXH-HdneyKuDTKgwFsqlaN8FFCTlkhKZYzbY,7996
+zpljet-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+zpljet-1.0.0.dist-info/licenses/LICENSE,sha256=wEwN5cT4ZYoQ83DaueRDJVnU1UumV8HAT1jcVv9n4S8,1063
+zpljet-1.0.0.dist-info/RECORD,,

zpljet-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zpljet-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZPLJet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.