snap-python 0.1.7__py3-none-any.whl → 0.2.0__py3-none-any.whl

snap_python/__init__.py

@@ -1,7 +1,7 @@
 import logging
 import os
 
-log_level = os.getenv("SNAP_PYTHON_LOG_LEVEL", "DEBUG").upper()
-numeric_level = getattr(logging, log_level, logging.DEBUG)
+log_level = os.getenv("SNAP_PYTHON_LOG_LEVEL", "INFO").upper()
+numeric_level = getattr(logging, log_level, logging.INFO)
 logger = logging.getLogger("snap_python")
 logger.setLevel(numeric_level)

snap_python/client.py

@@ -1,24 +1,82 @@
-import asyncio
 import logging
 from typing import AsyncGenerator
 
 import httpx
-from retry import retry
 
+from snap_python.components.changes import ChangeEndpoints
 from snap_python.components.config import ConfigEndpoints
+from snap_python.components.interfaces import InterfacesEndpoints
+from snap_python.components.logs import LogsEndpoints
 from snap_python.components.snaps import SnapsEndpoints
 from snap_python.components.store import StoreEndpoints
 from snap_python.schemas.changes import ChangesResponse
-from snap_python.utils import AbstractSnapsClient
+from snap_python.utils import (
+    IDEMPOTENT_HTTP_METHODS,
+    AbstractSnapsClient,
+    SnapdAPIError,
+    async_retry,
+    is_transient_exception,
+)
 
 SNAPD_SOCKET = "/run/snapd.socket"
 
 logger = logging.getLogger("snap_python.client")
-logger.setLevel(logging.DEBUG)
+
+
+def _is_retryable_request(exc: BaseException, args: tuple, kwargs: dict) -> bool:
+    """Retry predicate for :meth:`SnapClient.request` and :meth:`request_raw`.
+
+    Only idempotent methods are retried: replaying a POST/PUT/DELETE can
+    duplicate side effects (installing a snap twice, for instance).
+    """
+    method = kwargs.get("method")
+    if method is None and len(args) >= 2:
+        method = args[1]
+    if str(method).upper() not in IDEMPOTENT_HTTP_METHODS:
+        return False
+    return is_transient_exception(exc)
+
+
+def _snapd_error_from_response(response: httpx.Response) -> SnapdAPIError | None:
+    """Build a :class:`SnapdAPIError` from a snapd error envelope.
+
+    snapd reports failures as
+    ``{"type": "error", "status-code": N, "result": {"message", "kind", "value"}}``.
+    Returns ``None`` when the body is not such an envelope, so callers can fall
+    back to :meth:`httpx.Response.raise_for_status`.
+    """
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if not isinstance(body, dict) or body.get("type") != "error":
+        return None
+    result = body.get("result")
+    if not isinstance(result, dict):
+        return None
+
+    request = response.request
+    request_desc = (
+        f"{request.method} {request.url}" if request is not None else "snapd request"
+    )
+    detail = result.get("message") or "snapd returned an error"
+    return SnapdAPIError(
+        f"HTTP {response.status_code} for {request_desc}: {detail}",
+        status_code=response.status_code,
+        kind=result.get("kind"),
+        value=result.get("value"),
+        response=response,
+    )
 
 
 class SnapClient(AbstractSnapsClient):
-    """Core class for interacting with the Snap Store and Snapd."""
+    """Core class for interacting with the Snap Store and Snapd.
+
+    :param timeout: Timeout applied to every snapd request, in seconds or as an
+        :class:`httpx.Timeout`. ``None`` disables the timeout (httpx interprets
+        it that way), which is useful for large sideloads. Defaults to 60.0;
+        httpx's own 5 second default is too short for uploads.
+    """
 
     def __init__(
         self,
@@ -28,6 +86,7 @@ class SnapClient(AbstractSnapsClient):
         store_base_url: str = "https://api.snapcraft.io",
         store_headers: dict[str, str] = None,
         prompt_for_authentication: bool = False,
+        timeout: float | httpx.Timeout | None = 60.0,
     ):
         if tcp_location and snapd_socket_location:
             raise ValueError(
@@ -52,7 +111,7 @@ class SnapClient(AbstractSnapsClient):
         self.store_base_url = store_base_url
         self.store_headers = store_headers
         self.snapd_client = httpx.AsyncClient(
-            transport=self._transport, headers=self.snapd_headers
+            transport=self._transport, headers=self.snapd_headers, timeout=timeout
         )
         self.snaps = SnapsEndpoints(self)
         self.store = StoreEndpoints(
@@ -61,8 +120,25 @@ class SnapClient(AbstractSnapsClient):
             headers=self.store_headers,
         )
         self.config = ConfigEndpoints(self)
+        self.changes = ChangeEndpoints(self)
+        self.interfaces = InterfacesEndpoints(self)
+        self.logs = LogsEndpoints(self)
+
+    def endpoint_url(self, endpoint: str) -> str:
+        """
+        Build the absolute URL of a snapd ``/v2`` endpoint.
+
+        :param endpoint: Endpoint relative to ``/v2/``, for example ``"logs"``.
+        :type endpoint: str
+
+        :returns: The absolute URL, using the configured base URL and version.
+        :rtype: str
+        """
+        return f"{self._base_url}/{self.version}/{endpoint}"
 
-    @retry(httpx.HTTPError, tries=3, delay=1, backoff=1)
+    @async_retry(
+        httpx.HTTPError, tries=3, delay=1, backoff=1, retry_if=_is_retryable_request
+    )
     async def request(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
         r"""
         Sends an HTTP request to the specified endpoint using the given method and parameters.
@@ -76,21 +152,30 @@ class SnapClient(AbstractSnapsClient):
         :returns: The response object from the HTTP request.
         :rtype: httpx.Response
 
-        :raises httpx.HTTPStatusError: If the response contains an HTTP status code indicating an error.
+        :raises SnapdAPIError: If snapd answered with an error envelope; the
+            parsed ``kind`` and ``value`` are available on the exception.
+        :raises httpx.HTTPStatusError: If the response contains an HTTP status
+            code indicating an error and the body is not a snapd envelope.
         """
 
         response = await self.snapd_client.request(
-            method, f"{self._base_url}/{self.version}/{endpoint}", **kwargs
+            method, self.endpoint_url(endpoint), **kwargs
         )
+        if response.is_error:
+            snapd_error = _snapd_error_from_response(response)
+            if snapd_error is not None:
+                raise snapd_error
         response.raise_for_status()
         return response
 
-    @retry(httpx.HTTPError, tries=3, delay=1, backoff=1)
+    @async_retry(
+        httpx.HTTPError, tries=3, delay=1, backoff=1, retry_if=_is_retryable_request
+    )
     async def request_raw(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
         r"""
         Sends an HTTP request using the specified method and endpoint.
 
-        :param method: The HTTP method to use for the request (e.g., 'GET', 'POST').
+        :param method: The HTTP method to use for the request (e.g., 'POST').
         :type method: str
         :param endpoint: The endpoint URL to send the request to.
         :type endpoint: str
@@ -99,11 +184,18 @@ class SnapClient(AbstractSnapsClient):
         :returns: The response object resulting from the HTTP request.
         :rtype: httpx.Response
 
-        :raises httpx.HTTPStatusError: If the response contains an HTTP status code indicating an error.
+        :raises SnapdAPIError: If snapd answered with an error envelope; the
+            parsed ``kind`` and ``value`` are available on the exception.
+        :raises httpx.HTTPStatusError: If the response contains an HTTP status
+            code indicating an error and the body is not a snapd envelope.
         """
 
         response = await self.snapd_client.request(method, endpoint, **kwargs)
 
+        if response.is_error:
+            snapd_error = _snapd_error_from_response(response)
+            if snapd_error is not None:
+                raise snapd_error
         response.raise_for_status()
         return response
 
@@ -113,16 +205,46 @@ class SnapClient(AbstractSnapsClient):
 
         :returns: The response from the ping request.
         :rtype: httpx.Response
+
+        :raises httpx.HTTPStatusError: If snapd is not reachable or reports an
+            error status.
         """
         response = await self.snapd_client.get(f"{self._base_url}/")
+        response.raise_for_status()
 
         return response
 
-    @retry(httpx.HTTPError, tries=3, delay=0.5)
+    async def is_available(self) -> bool:
+        """
+        Check whether snapd is reachable and healthy.
+
+        :returns: True if snapd answered with a 2xx status, False otherwise.
+        :rtype: bool
+        """
+        try:
+            await self.ping()
+        except httpx.HTTPError as exc:
+            logger.debug("snapd is not available: %s", exc)
+            return False
+        return True
+
+    async def close(self) -> None:
+        """Close the underlying snapd and store HTTP clients."""
+        await self.snapd_client.aclose()
+        await self.store.close()
+
+    async def __aenter__(self) -> "SnapClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()
+
     async def get_changes_by_id(self, change_id: str) -> ChangesResponse:
         """
         Asynchronously retrieves changes by their ID.
 
+        Thin delegate to :meth:`snap_python.components.changes.ChangeEndpoints.get`.
+
         :param change_id: The ID of the change to retrieve.
         :type change_id: str
 
@@ -131,50 +253,50 @@ class SnapClient(AbstractSnapsClient):
 
         :raises httpx.HTTPStatusError: If the request results in an HTTP error.
         """
-
-        try:
-            response = await self.request("GET", f"changes/{change_id}")
-        except httpx.HTTPStatusError as e:
-            logger.warning(
-                "Bad response status code for get_changes_by_id: %s",
-                e.response.status_code,
-            )
-            response = e.response
-
-        return ChangesResponse.model_validate_json(response.content)
+        return await self.changes.get(change_id)
 
     async def get_changes_by_id_generator(
-        self, change_id: str
+        self,
+        change_id: str,
+        timeout: float | None = None,
+        poll_interval: float = 0.5,
     ) -> AsyncGenerator[ChangesResponse, None]:
         """
         Asynchronous generator to fetch changes by change ID.
 
-        This generator continuously requests changes from the server using the provided
-        change ID and yields the response as a ChangesResponse object. It includes error
-        handling for HTTP status errors and adds a small delay between requests to avoid
-        overwhelming the server.
+        Thin delegate to
+        :meth:`snap_python.components.changes.ChangeEndpoints.watch`: polls
+        snapd and yields every :class:`ChangesResponse` until the change is
+        ready. Error results are raised instead of being yielded silently.
 
         :param change_id: The ID of the change to fetch.
         :type change_id: str
+        :param timeout: Maximum number of seconds to poll. ``None`` polls until
+            the change is ready.
+        :type timeout: float | None
+        :param poll_interval: Seconds between two polls.
+        :type poll_interval: float
 
         :yields: The response object containing the changes.
         :rtype: ChangesResponse
 
-        :raises httpx.HTTPStatusError: If the request fails with an HTTP status error.
+        :raises SnapdAPIError: If the change reports an error or the timeout
+            expires.
+        :raises httpx.HTTPStatusError: If the request fails with an HTTP error.
         """
-        while True:
-            try:
-                response = await self.request("GET", f"changes/{change_id}")
-            except httpx.HTTPStatusError as e:
-                logger.warning(
-                    "Bad response status code for get_changes_by_id: %s",
-                    e.response.status_code,
-                )
-                response = e.response
-
-            change_response = ChangesResponse.model_validate_json(response.content)
+        async for change_response in self.changes.watch(
+            change_id, timeout=timeout, poll_interval=poll_interval
+        ):
             yield change_response
 
-            await asyncio.sleep(
-                0.01
-            )  # Add a delay to avoid spamming the server with requests
+    async def get_system_info(self) -> dict:
+        """
+        Retrieves system information from the snapd service.
+
+        :returns: A dictionary containing system information.
+        :rtype: dict
+
+        :raises httpx.HTTPStatusError: If the request results in an HTTP error.
+        """
+        response = await self.request("GET", "system-info")
+        return response.json()

snap_python/components/changes.py

@@ -0,0 +1,157 @@
+import asyncio
+import time
+from typing import AsyncGenerator, Literal
+
+import httpx
+
+from snap_python.schemas.changes import ChangesListResponse, ChangesResponse
+from snap_python.schemas.common import BaseErrorResult
+from snap_python.utils import AbstractSnapsClient, SnapdAPIError, async_retry
+
+#: Values ``GET /v2/changes`` accepts for ``select``.
+ChangeSelect = Literal["all", "in-progress", "ready"]
+
+
+class ChangeEndpoints:
+    """Endpoints under ``/v2/changes``.
+
+    :param client: Client used to talk to snapd.
+    """
+
+    def __init__(self, client: AbstractSnapsClient) -> None:
+        self._client = client
+        self.common_endpoint = "changes"
+
+    @async_retry(httpx.HTTPError, tries=3, delay=0.5)
+    async def get(self, change_id: str) -> ChangesResponse:
+        """
+        Retrieve a single change.
+
+        :param change_id: The ID of the change to retrieve.
+        :type change_id: str
+
+        :returns: The response object containing the change.
+        :rtype: ChangesResponse
+
+        :raises SnapdAPIError: If snapd does not know the change (404
+            ``cannot find change with id ...``).
+        :raises httpx.HTTPStatusError: If the request results in an HTTP error.
+        """
+        response = await self._client.request(
+            "GET", f"{self.common_endpoint}/{change_id}"
+        )
+        return ChangesResponse.model_validate_json(response.content)
+
+    async def list_changes(
+        self,
+        select: ChangeSelect | None = None,
+        for_snap: str | None = None,
+    ) -> ChangesListResponse:
+        """
+        Retrieve changes, optionally filtered by state and snap name.
+
+        :param select: ``"all"``, ``"in-progress"`` or ``"ready"``. None
+            (default) omits the parameter, so snapd applies its own default,
+            ``"in-progress"``. Any other value is rejected by snapd with a 400.
+        :type select: str, optional
+        :param for_snap: Only return changes recorded against this snap name.
+            snapd matches the ``snap-names`` change data, splitting
+            ``"<snap>.<app>"`` entries on the snap part. None (default) returns
+            changes for every snap. Sent as the ``for`` query parameter.
+        :type for_snap: str, optional
+
+        :returns: The response object containing the list of changes.
+        :rtype: ChangesListResponse
+
+        :raises SnapdAPIError: If snapd rejects the request, for example for an
+            unknown ``select`` value.
+        :raises httpx.HTTPStatusError: If the request results in an HTTP error.
+        """
+        params: dict[str, str] = {}
+        if select is not None:
+            params["select"] = select
+        if for_snap is not None:
+            params["for"] = for_snap
+
+        response = await self._client.request(
+            "GET", self.common_endpoint, params=params
+        )
+        return ChangesListResponse.model_validate_json(response.content)
+
+    async def abort(self, change_id: str) -> ChangesResponse:
+        """
+        Abort a pending change.
+
+        The request itself is synchronous: snapd flags the change and returns
+        its current info with HTTP 200 straight away. The abort then proceeds
+        asynchronously, so the returned change is usually still in
+        ``"Doing"``/``"Abort"`` state; poll it to observe completion.
+
+        :param change_id: The ID of the change to abort.
+        :type change_id: str
+
+        :returns: The response object containing the current change info.
+        :rtype: ChangesResponse
+
+        :raises SnapdAPIError: If snapd rejects the abort, for example with 400
+            ``cannot abort change <id> with nothing pending`` when the change
+            is already ready, or 404 for an unknown change.
+        :raises httpx.HTTPStatusError: If the request results in an HTTP error.
+        """
+        response = await self._client.request(
+            "POST",
+            f"{self.common_endpoint}/{change_id}",
+            json={"action": "abort"},
+        )
+        return ChangesResponse.model_validate_json(response.content)
+
+    async def watch(
+        self,
+        change_id: str,
+        timeout: float | None = None,
+        poll_interval: float = 0.5,
+    ) -> AsyncGenerator[ChangesResponse, None]:
+        """
+        Poll a change until it is ready.
+
+        :param change_id: The ID of the change to poll.
+        :type change_id: str
+        :param timeout: Maximum number of seconds to poll. None (default)
+            polls until the change is ready.
+        :type timeout: float | None
+        :param poll_interval: Seconds between two polls.
+        :type poll_interval: float
+
+        :yields: Every :class:`ChangesResponse`, the ready one last.
+        :rtype: ChangesResponse
+
+        :raises SnapdAPIError: If the change reports an error or the timeout
+            expires.
+        :raises httpx.HTTPStatusError: If a poll fails with an HTTP error.
+        """
+        deadline = None if timeout is None else time.monotonic() + timeout
+
+        while True:
+            change_response = await self.get(change_id)
+
+            if isinstance(change_response.result, BaseErrorResult):
+                raise SnapdAPIError(
+                    f"Error waiting for change {change_id}: "
+                    f"{change_response.result.message}"
+                )
+            if change_response.result.err:
+                raise SnapdAPIError(
+                    f"Error waiting for change {change_id}: "
+                    f"{change_response.result.err}"
+                )
+
+            yield change_response
+
+            if change_response.ready:
+                return
+
+            if deadline is not None and time.monotonic() >= deadline:
+                raise SnapdAPIError(
+                    f"Timed out after {timeout}s waiting for change {change_id}"
+                )
+            await asyncio.sleep(poll_interval)

snap_python/components/config.py

@@ -1,4 +1,3 @@
-import asyncio
 import logging
 
 import httpx
@@ -6,9 +5,9 @@ import httpx
 from snap_python.schemas.changes import ChangesResponse
 from snap_python.schemas.common import AsyncResponse
 from snap_python.schemas.config import ConfigResponse
-from snap_python.utils import AbstractSnapsClient
+from snap_python.utils import AbstractSnapsClient, wait_for_change
 
-logger = logging.getLogger("snap_python.components.snaps")
+logger = logging.getLogger("snap_python.components.config")
 
 
 class ConfigEndpoints:
@@ -33,7 +32,11 @@ class ConfigEndpoints:
         return ConfigResponse.model_validate_json(response.content)
 
     async def set_configuration(
-        self, snap: str, configuration: dict, wait: bool = True
+        self,
+        snap: str,
+        configuration: dict,
+        wait: bool = True,
+        timeout: float | None = None,
     ) -> AsyncResponse | ChangesResponse:
         # TODO: should check that snap supports configure hook before trying to set configuration
         response: httpx.Response = await self._client.request(
@@ -43,12 +46,6 @@ class ConfigEndpoints:
         async_response = AsyncResponse.model_validate_json(response.content)
         if not wait:
             return async_response
-        while True:
-            changes = await self._client.get_changes_by_id(async_response.change)
-
-            if changes.ready:
-                break
-
-            await asyncio.sleep(0.1)
-
-        return changes
+        return await wait_for_change(
+            self._client, async_response.change, timeout=timeout
+        )