pymenderio 0.1.0__py3-none-any.whl

pymenderio/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+
+"""
+pymenderio - Python client library for the Mender API.
+
+For a complete public SDK reference (methods, classes, and errors), see API.md.
+
+Example usage:
+
+    from pymenderio import MenderClient
+
+    # Sync usage with mender-cli config and token defaults
+    with MenderClient.from_mender_cli() as client:
+        devices = client.devices.list(status="accepted")
+"""
+
+from pymenderio.client import AsyncMenderClient, MenderClient
+from pymenderio.exceptions import (
+    AuthenticationError,
+    ConflictError,
+    MenderError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MenderClient",
+    "AsyncMenderClient",
+    "MenderError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+]

pymenderio/_http.py

@@ -0,0 +1,417 @@
+# SPDX-License-Identifier: MIT
+
+"""Internal HTTP client wrapper with transparent pagination and error handling."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, TypeVar, cast
+
+import httpx
+
+from pymenderio.exceptions import (
+    AuthenticationError,
+    ConflictError,
+    MenderError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+T = TypeVar("T")
+
+# Maximum items per page (Mender API limit)
+_PER_PAGE = 500
+
+
+def _parse_link_header(link_header: str) -> dict[str, str]:
+    """Parse RFC 5988 Link header into a dict of rel -> url."""
+    links: dict[str, str] = {}
+    for part in link_header.split(","):
+        match = re.match(r'\s*<([^>]+)>;\s*rel="([^"]+)"', part.strip())
+        if match:
+            url, rel = match.groups()
+            links[rel] = url
+    return links
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise appropriate MenderError based on HTTP status code."""
+    if response.status_code < 400:
+        return
+
+    # Try to extract error details from response body
+    request_id: str | None = response.headers.get("X-Request-Id")
+    body: dict[str, Any] | None = None
+    try:
+        raw_body: Any = response.json()
+        if isinstance(raw_body, dict):
+            body = cast(dict[str, Any], raw_body)
+
+        if body is not None:
+            raw_message = body.get("error")
+            message = raw_message if isinstance(raw_message, str) else (response.reason_phrase or "Unknown error")
+
+            # Also check for request_id in the JSON body
+            if not request_id:
+                raw_request_id = body.get("request_id")
+                if isinstance(raw_request_id, str):
+                    request_id = raw_request_id
+        else:
+            message = response.reason_phrase or "Unknown error"
+    except Exception:
+        message = response.reason_phrase or "Unknown error"
+
+    if response.status_code == 401:
+        raise AuthenticationError(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response_body=body,
+        )
+    elif response.status_code == 404:
+        raise NotFoundError(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response_body=body,
+        )
+    elif response.status_code == 409:
+        raise ConflictError(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response_body=body,
+        )
+    elif response.status_code == 422:
+        raise ValidationError(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response_body=body,
+        )
+    elif response.status_code == 429:
+        raise RateLimitError(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response_body=body,
+        )
+    elif response.status_code >= 500:
+        raise ServerError(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response_body=body,
+        )
+    else:
+        raise MenderError(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response_body=body,
+        )
+
+
+class HTTPClient:
+    """
+    Synchronous HTTP client wrapper for Mender API.
+
+    Handles:
+    - Bearer token authentication
+    - Transparent pagination (fetches all pages, returns complete list)
+    - Error translation to MenderError hierarchy
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        verify: bool = True,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+            verify=verify,
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> HTTPClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Make a single HTTP request."""
+        response = self._client.request(
+            method,
+            path,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            headers=headers,
+        )
+        _raise_for_status(response)
+        return response
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a GET request."""
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a POST request."""
+        return self.request("POST", path, json=json, data=data, files=files, params=params)
+
+    def put(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+    ) -> httpx.Response:
+        """Make a PUT request."""
+        return self.request("PUT", path, json=json)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+    ) -> httpx.Response:
+        """Make a PATCH request."""
+        return self.request("PATCH", path, json=json)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a DELETE request."""
+        return self.request("DELETE", path, params=params)
+
+    def get_list(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> list[Any]:
+        """
+        Fetch a paginated list endpoint, returning all items.
+
+        Pagination is handled transparently - all pages are fetched
+        and merged into a single list.
+        """
+        params = dict(params) if params else {}
+        params["per_page"] = _PER_PAGE
+        params["page"] = 1
+
+        all_items: list[Any] = []
+
+        while True:
+            response = self.get(path, params=params)
+            items = response.json()
+
+            if not isinstance(items, list):
+                # Some endpoints return a wrapper object
+                raise MenderError(f"Expected list response, got {type(items)}")
+
+            all_items.extend(cast(list[Any], items))  # type: ignore[redundant-cast]
+
+            # Check for next page via Link header
+            link_header = response.headers.get("Link", "")
+            links = _parse_link_header(link_header)
+
+            if "next" not in links:
+                break
+
+            params["page"] += 1
+
+        return all_items
+
+
+class AsyncHTTPClient:
+    """
+    Asynchronous HTTP client wrapper for Mender API.
+
+    Handles:
+    - Bearer token authentication
+    - Transparent pagination (fetches all pages, returns complete list)
+    - Error translation to MenderError hierarchy
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        verify: bool = True,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+            verify=verify,
+            timeout=timeout,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHTTPClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Make a single HTTP request."""
+        response = await self._client.request(
+            method,
+            path,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            headers=headers,
+        )
+        _raise_for_status(response)
+        return response
+
+    async def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a GET request."""
+        return await self.request("GET", path, params=params)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a POST request."""
+        return await self.request("POST", path, json=json, data=data, files=files, params=params)
+
+    async def put(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+    ) -> httpx.Response:
+        """Make a PUT request."""
+        return await self.request("PUT", path, json=json)
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+    ) -> httpx.Response:
+        """Make a PATCH request."""
+        return await self.request("PATCH", path, json=json)
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a DELETE request."""
+        return await self.request("DELETE", path, params=params)
+
+    async def get_list(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> list[Any]:
+        """
+        Fetch a paginated list endpoint, returning all items.
+
+        Pagination is handled transparently - all pages are fetched
+        and merged into a single list.
+        """
+        params = dict(params) if params else {}
+        params["per_page"] = _PER_PAGE
+        params["page"] = 1
+
+        all_items: list[Any] = []
+
+        while True:
+            response = await self.get(path, params=params)
+            items = response.json()
+
+            if not isinstance(items, list):
+                raise MenderError(f"Expected list response, got {type(items)}")
+
+            all_items.extend(cast(list[Any], items))  # type: ignore[redundant-cast]
+
+            # Check for next page via Link header
+            link_header = response.headers.get("Link", "")
+            links = _parse_link_header(link_header)
+
+            if "next" not in links:
+                break
+
+            params["page"] += 1
+
+        return all_items

pymenderio/api/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+
+"""API client modules for pymenderio."""
+
+from pymenderio.api.artifacts import ArtifactsAPI, AsyncArtifactsAPI
+from pymenderio.api.deployments import AsyncDeploymentsAPI, DeploymentsAPI
+from pymenderio.api.deviceconfigure import AsyncDeviceconfigureAPI, DeviceconfigureAPI
+from pymenderio.api.deviceconnect import AsyncDeviceconnectAPI, DeviceconnectAPI
+from pymenderio.api.devicemonitor import AsyncDevicemonitorAPI, DevicemonitorAPI
+from pymenderio.api.devices import AsyncDevicesAPI, DevicesAPI
+from pymenderio.api.filters import AsyncFiltersAPI, FiltersAPI
+from pymenderio.api.inventory import AsyncInventoryAPI, InventoryAPI
+from pymenderio.api.iot_manager import AsyncIotManagerAPI, IotManagerAPI
+from pymenderio.api.releases import AsyncReleasesAPI, ReleasesAPI
+from pymenderio.api.tenantadm import AsyncTenantadmAPI, TenantadmAPI
+from pymenderio.api.useradm import AsyncUseradmAPI, UseradmAPI
+
+__all__ = [
+    "DevicesAPI",
+    "AsyncDevicesAPI",
+    "DeploymentsAPI",
+    "AsyncDeploymentsAPI",
+    "ArtifactsAPI",
+    "AsyncArtifactsAPI",
+    "DeviceconnectAPI",
+    "AsyncDeviceconnectAPI",
+    "DeviceconfigureAPI",
+    "AsyncDeviceconfigureAPI",
+    "DevicemonitorAPI",
+    "AsyncDevicemonitorAPI",
+    "IotManagerAPI",
+    "AsyncIotManagerAPI",
+    "ReleasesAPI",
+    "AsyncReleasesAPI",
+    "InventoryAPI",
+    "AsyncInventoryAPI",
+    "FiltersAPI",
+    "AsyncFiltersAPI",
+    "TenantadmAPI",
+    "AsyncTenantadmAPI",
+    "UseradmAPI",
+    "AsyncUseradmAPI",
+]