printeasy-sdk 0.1.0__py3-none-any.whl

printeasy/__init__.py

@@ -0,0 +1,16 @@
+"""PrintEasy Python SDK."""
+
+from . import webhooks
+from ._client import PrintEasy
+from ._http import PrintEasyError, PrintEasyTimeoutError
+from .webhooks import WebhookVerificationError
+
+__version__ = "0.1.0"
+__all__ = [
+    "PrintEasy",
+    "PrintEasyError",
+    "PrintEasyTimeoutError",
+    "WebhookVerificationError",
+    "__version__",
+    "webhooks",
+]

printeasy/_client.py

@@ -0,0 +1,221 @@
+"""The PrintEasy client: retries, idempotency keys, pagination and create_and_wait."""
+
+import os
+import time
+import uuid
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+import httpx
+from httpx._utils import get_environment_proxies
+
+from . import webhooks as _webhooks
+from ._http import PrintEasyError, PrintEasyTimeoutError, RetryTransport
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from ._raw import MaskedAuthenticatedClient
+
+DEFAULT_BASE_URL = "https://api.printeasy.adfinite.com"
+TERMINAL = {"done", "error", "cancelled", "expired"}
+
+
+def _q(id: str) -> str:
+    """Quote an id for use as one path segment."""
+    return quote(str(id), safe="")
+
+
+class _ListResource:
+    def __init__(self, client: "PrintEasy", path: str):
+        self._c, self._path = client, path
+
+    def list(self, **params: Any) -> dict:
+        """One page: `{"data": [...], "hasMore": bool, "nextCursor": str | None}`."""
+        return self._c._request("GET", self._path, params=params)
+
+    def iterate(self, **params: Any) -> Iterator[dict]:
+        """Every item across pages, following nextCursor."""
+        after = params.pop("after", None)
+        while True:
+            page = self.list(**params, after=after)
+            yield from page["data"]
+            if not page["hasMore"] or not page["nextCursor"]:
+                return
+            after = page["nextCursor"]
+
+
+class _Resource(_ListResource):
+    def get(self, id: str) -> dict:
+        return self._c._request("GET", f"{self._path}/{_q(id)}")
+
+
+class _PrintJobs(_Resource):
+    def create(self, body: dict, *, idempotency_key: str | None = None) -> dict:
+        """Create a print job. A random Idempotency-Key is sent when none is given,
+        so retries after a network error or 5xx never print twice."""
+        key = idempotency_key or str(uuid.uuid4())
+        return self._c._request(
+            "POST", self._path, json=body, headers={"Idempotency-Key": key}
+        )
+
+    def cancel(self, id: str) -> dict:
+        return self._c._request("POST", f"{self._path}/{_q(id)}/cancel")
+
+    def create_and_wait(
+        self,
+        body: dict,
+        *,
+        timeout_s: float = 60.0,
+        poll_interval_s: float = 1.0,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """Create a job and poll it until it is done, error, cancelled or expired.
+
+        Raises PrintEasyTimeoutError (with the last seen job) after timeout_s.
+        """
+        job = self.create(body, idempotency_key=idempotency_key)
+        deadline = self._c._clock() + timeout_s
+        while job["state"] not in TERMINAL:
+            left = deadline - self._c._clock()
+            if left <= 0:
+                raise PrintEasyTimeoutError(job)
+            self._c._sleep(min(poll_interval_s, left))
+            job = self.get(job["id"])
+        return job
+
+
+class _Webhooks(_Resource):
+    verify = staticmethod(_webhooks.verify)
+
+    def create(self, body: dict) -> dict:
+        """Create an endpoint; the response holds the signing secret, shown only once."""
+        return self._c._request("POST", self._path, json=body)
+
+    def update(self, id: str, body: dict) -> dict:
+        return self._c._request("PATCH", f"{self._path}/{_q(id)}", json=body)
+
+    def delete(self, id: str) -> None:
+        self._c._request("DELETE", f"{self._path}/{_q(id)}")
+
+    def deliveries(self, id: str) -> _ListResource:
+        """Deliveries of one endpoint, with list and iterate."""
+        return _ListResource(self._c, f"{self._path}/{_q(id)}/deliveries")
+
+    def replay(self, delivery_id: str) -> dict:
+        return self._c._request(
+            "POST", f"{self._path}/deliveries/{_q(delivery_id)}/replay"
+        )
+
+
+def _transports(
+    transport: httpx.BaseTransport | None, max_retries: int, sleep
+) -> tuple[RetryTransport, dict[str, RetryTransport | None] | None]:
+    """The retrying default transport, plus proxy mounts from the environment.
+
+    With no transport given this follows httpx's own HTTP_PROXY, HTTPS_PROXY,
+    ALL_PROXY and NO_PROXY handling (a None mount means direct, through the
+    default transport), with every proxy transport wrapped in RetryTransport.
+    """
+    if transport is not None:
+        return RetryTransport(transport, max_retries, sleep), None
+    mounts: dict[str, RetryTransport | None] = {
+        pattern: None
+        if proxy is None
+        else RetryTransport(httpx.HTTPTransport(proxy=proxy), max_retries, sleep)
+        for pattern, proxy in get_environment_proxies().items()
+    }
+    return RetryTransport(httpx.HTTPTransport(), max_retries, sleep), mounts
+
+
+class PrintEasy:
+    """Client for the PrintEasy API.
+
+    The API key defaults to the PRINTEASY_API_KEY environment variable. 429 responses
+    are retried, and 5xx or network errors too for replay safe requests (GET, PATCH,
+    DELETE and print job creation, which always sends an Idempotency-Key).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+        sleep=time.sleep,
+        clock=time.monotonic,
+    ):
+        key = api_key or os.environ.get("PRINTEASY_API_KEY")
+        if not key:
+            raise ValueError("pass api_key or set PRINTEASY_API_KEY")
+        self._key, self._base_url, self._sleep, self._clock = (
+            key,
+            base_url,
+            sleep,
+            clock,
+        )
+        self._raw: MaskedAuthenticatedClient | None = None
+        default, mounts = _transports(transport, max_retries, sleep)
+        self._http = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            transport=default,
+            mounts=mounts,
+            headers={
+                "Authorization": f"Bearer {key}",
+                "Accept": "application/json",
+                "User-Agent": "printeasy-python",
+            },
+        )
+        self.computers = _Resource(self, "/v1/computers")
+        self.printers = _Resource(self, "/v1/printers")
+        self.events = _ListResource(self, "/v1/events")
+        self.print_jobs = _PrintJobs(self, "/v1/printjobs")
+        self.webhooks = _Webhooks(self, "/v1/webhooks")
+
+    def whoami(self) -> dict:
+        return self._request("GET", "/v1/whoami")
+
+    def usage(self) -> dict:
+        return self._request("GET", "/v1/usage")
+
+    @property
+    def raw(self) -> "MaskedAuthenticatedClient":
+        """The generated client (printeasy._generated) on the same retrying httpx client.
+
+        Its repr masks the API key.
+        """
+        if self._raw is None:
+            from ._raw import MaskedAuthenticatedClient
+
+            self._raw = MaskedAuthenticatedClient(
+                base_url=self._base_url, token=self._key
+            ).set_httpx_client(self._http)
+        return self._raw
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Self":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        json: Any = None,
+        headers: dict | None = None,
+    ) -> Any:
+        query = {k: v for k, v in (params or {}).items() if v is not None}
+        r = self._http.request(method, path, params=query, json=json, headers=headers)
+        if r.status_code >= 400:
+            raise PrintEasyError.from_response(r)
+        return None if r.status_code == 204 else r.json()

printeasy/_generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing PrintEasy API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

printeasy/_generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

printeasy/_generated/api/account/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

printeasy/_generated/api/account/get_whoami.py

@@ -0,0 +1,156 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.error import Error
+from ...models.whoami import Whoami
+from ...types import Response
+
+
+def _get_kwargs() -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/v1/whoami",
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Error | Whoami | None:
+    if response.status_code == 200:
+        response_200 = Whoami.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 401:
+        response_401 = Error.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = Error.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 429:
+        response_429 = Error.from_dict(response.json())
+
+        return response_429
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[Error | Whoami]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[Error | Whoami]:
+    """Identify the organization behind an API key
+
+     Returns the organization, mode, key id and plan of the API key that signs the request. Use it to
+    check that a key works.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Error | Whoami]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+) -> Error | Whoami | None:
+    """Identify the organization behind an API key
+
+     Returns the organization, mode, key id and plan of the API key that signs the request. Use it to
+    check that a key works.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Error | Whoami
+    """
+
+    return sync_detailed(
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[Error | Whoami]:
+    """Identify the organization behind an API key
+
+     Returns the organization, mode, key id and plan of the API key that signs the request. Use it to
+    check that a key works.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Error | Whoami]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+) -> Error | Whoami | None:
+    """Identify the organization behind an API key
+
+     Returns the organization, mode, key id and plan of the API key that signs the request. Use it to
+    check that a key works.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Error | Whoami
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+        )
+    ).parsed

printeasy/_generated/api/computers/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

printeasy/_generated/api/computers/delete_computer.py

@@ -0,0 +1,192 @@
+from http import HTTPStatus
+from typing import Any, cast
+from urllib.parse import quote
+from uuid import UUID
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.error import Error
+from ...types import Response
+
+
+def _get_kwargs(
+    id: UUID,
+) -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "delete",
+        "url": "/v1/computers/{id}".format(
+            id=quote(str(id), safe=""),
+        ),
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Any | Error | None:
+    if response.status_code == 204:
+        response_204 = cast(Any, None)
+        return response_204
+
+    if response.status_code == 400:
+        response_400 = Error.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = Error.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = Error.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = Error.from_dict(response.json())
+
+        return response_404
+
+    if response.status_code == 429:
+        response_429 = Error.from_dict(response.json())
+
+        return response_429
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[Any | Error]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> Response[Any | Error]:
+    """Delete a computer
+
+     Soft-deletes the computer and its printers, revokes its agent tokens and disconnects the agent. The
+    virtual test computer cannot be deleted.
+
+    Args:
+        id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Any | Error]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> Any | Error | None:
+    """Delete a computer
+
+     Soft-deletes the computer and its printers, revokes its agent tokens and disconnects the agent. The
+    virtual test computer cannot be deleted.
+
+    Args:
+        id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Any | Error
+    """
+
+    return sync_detailed(
+        id=id,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> Response[Any | Error]:
+    """Delete a computer
+
+     Soft-deletes the computer and its printers, revokes its agent tokens and disconnects the agent. The
+    virtual test computer cannot be deleted.
+
+    Args:
+        id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Any | Error]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> Any | Error | None:
+    """Delete a computer
+
+     Soft-deletes the computer and its printers, revokes its agent tokens and disconnects the agent. The
+    virtual test computer cannot be deleted.
+
+    Args:
+        id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Any | Error
+    """
+
+    return (
+        await asyncio_detailed(
+            id=id,
+            client=client,
+        )
+    ).parsed