snap-python 0.0.5__tar.gz → 0.1.1__tar.gz

snap_python-0.1.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.3
+Name: snap-python
+Version: 0.1.1
+Summary: Interact with snapd and snapstore(s) from Python
+License: MIT
+Author: Alexander Lukens
+Author-email: alexdlukens@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.27.2,<0.28.0)
+Requires-Dist: pydantic (>=2.9.2,<3.0.0)
+Requires-Dist: retry (>=0.9.2,<0.10.0)
+Project-URL: Documentation, https://alexdlukens.github.io/snap-python/
+Project-URL: Repository, https://github.com/alexdlukens/snap-python
+Description-Content-Type: text/markdown
+
+# snap-python
+
+snap-python provides an API client to interact with snapd
+
+[Click here to read the documentation](https://alexdlukens.github.io/snap-python/)
+
+## Installation
+
+To install snap-python, you can use pip:
+
+```
+pip install snap-python
+```
+
+## Usage
+
+Here is a simple example of how to use snap-python:
+
+```python
+# uses asyncio, must be run in an event loop
+>>> import asyncio
+>>> from snap_python.client import SnapClient
+>>> sc = SnapClient()
+>>> installed_snaps = asyncio.run(sc.snaps.list_installed_snaps())
+>>> [snap.name for snap in installed_snaps.result]
+[..., 'vlc', 'snapcraft', 'firefox', 'store-tui', 'gtk-common-themes', 'thunderbird', ...]
+```
+
+Get details for installed snap `vlc`
+
+```python
+
+# uses asyncio, must be run in an event loop
+>>> import asyncio
+>>> from snap_python.client import SnapClient
+>>> sc = SnapClient()
+>>> vlc_snap = asyncio.run(sc.snaps.get_snap_info("vlc"))
+>>> vlc_snap.result.version
+'3.0.20-1-g2617de71b6'
+```
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for more details.
+

snap_python-0.1.1/README.md

@@ -0,0 +1,44 @@
+# snap-python
+
+snap-python provides an API client to interact with snapd
+
+[Click here to read the documentation](https://alexdlukens.github.io/snap-python/)
+
+## Installation
+
+To install snap-python, you can use pip:
+
+```
+pip install snap-python
+```
+
+## Usage
+
+Here is a simple example of how to use snap-python:
+
+```python
+# uses asyncio, must be run in an event loop
+>>> import asyncio
+>>> from snap_python.client import SnapClient
+>>> sc = SnapClient()
+>>> installed_snaps = asyncio.run(sc.snaps.list_installed_snaps())
+>>> [snap.name for snap in installed_snaps.result]
+[..., 'vlc', 'snapcraft', 'firefox', 'store-tui', 'gtk-common-themes', 'thunderbird', ...]
+```
+
+Get details for installed snap `vlc`
+
+```python
+
+# uses asyncio, must be run in an event loop
+>>> import asyncio
+>>> from snap_python.client import SnapClient
+>>> sc = SnapClient()
+>>> vlc_snap = asyncio.run(sc.snaps.get_snap_info("vlc"))
+>>> vlc_snap.result.version
+'3.0.20-1-g2617de71b6'
+```
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for more details.

{snap_python-0.0.5 → snap_python-0.1.1}/pyproject.toml

@@ -1,11 +1,12 @@
 [tool.poetry]
 name = "snap-python"
-version = "0.0.5"
-description = "An api to interact with snapd and snap stores"
+version = "0.1.1"
+description = "Interact with snapd and snapstore(s) from Python"
 authors = ["Alexander Lukens <alexdlukens@gmail.com>"]
 license = "MIT"
 readme = "README.md"
-repository = "https://github.com/alexlukens/snap-python"
+repository = "https://github.com/alexdlukens/snap-python"
+documentation = "https://alexdlukens.github.io/snap-python/"
 
 [tool.poetry.dependencies]
 python = "^3.10"
@@ -23,7 +24,14 @@ ipykernel = "^6.29.5"
 pytest-cov = "^6.0.0"
 sphinx = "^8.1.3"
 sphinx-rtd-theme = "^3.0.2"
+toml = "^0.10.2"
 
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "--cov=snap_python --cov-report=html"
+testpaths = "tests"

{snap_python-0.0.5 → snap_python-0.1.1}/src/snap_python/client.py

@@ -44,15 +44,15 @@ class SnapClient(AbstractSnapsClient):
         if store_headers is None:
             store_headers = {"Snap-Device-Series": "16", "X-Ubuntu-Series": "16"}
 
-        snapd_headers = {}
+        self.snapd_headers = {}
         if prompt_for_authentication:
-            snapd_headers = {"X-Allow-Interaction": "true"}
+            self.snapd_headers = {"X-Allow-Interaction": "true"}
 
         self.version = version
         self.store_base_url = store_base_url
         self.store_headers = store_headers
         self.snapd_client = httpx.AsyncClient(
-            transport=self._transport, headers=snapd_headers
+            transport=self._transport, headers=self.snapd_headers
         )
         self.snaps = SnapsEndpoints(self)
         self.store = StoreEndpoints(
@@ -61,19 +61,23 @@ class SnapClient(AbstractSnapsClient):
             headers=self.store_headers,
         )
         self.config = ConfigEndpoints(self)
+        self.snapd_client = httpx.AsyncClient(transport=self._transport)
 
     @retry(httpx.HTTPError, tries=3, delay=1, backoff=1)
     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.
-        Args:
-            method (str): The HTTP method to use for the request (e.g., 'GET', 'POST').
-            endpoint (str): The API endpoint to send the request to.
-            **kwargs: Additional keyword arguments to pass to the request.
-        Returns:
-            httpx.Response: The response object from the HTTP request.
-        Raises:
-            httpx.HTTPStatusError: If the response contains an HTTP status code indicating an error.
+
+        :param method: The HTTP method to use for the request (e.g., 'GET', 'POST').
+        :type method: str
+        :param endpoint: The API endpoint to send the request to.
+        :type endpoint: str
+        :param `**kwargs`: Additional keyword arguments to pass to the request.
+
+        :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.
         """
 
         response = await self.snapd_client.request(
@@ -84,16 +88,19 @@ class SnapClient(AbstractSnapsClient):
 
     @retry(httpx.HTTPError, tries=3, delay=1, backoff=1)
     async def request_raw(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
-        """
+        r"""
         Sends an HTTP request using the specified method and endpoint.
-        Args:
-            method (str): The HTTP method to use for the request (e.g., 'GET', 'POST').
-            endpoint (str): The endpoint URL to send the request to.
-            **kwargs: Additional keyword arguments to pass to the request.
-        Returns:
-            httpx.Response: The response object resulting from the HTTP request.
-        Raises:
-            httpx.HTTPStatusError: If the response contains an HTTP status code indicating an error.
+
+        :param method: The HTTP method to use for the request (e.g., 'GET', 'POST').
+        :type method: str
+        :param endpoint: The endpoint URL to send the request to.
+        :type endpoint: str
+        :param `**kwargs`: Additional keyword arguments to pass to the request.
+
+        :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.
         """
 
         response = await self.snapd_client.request(method, endpoint, **kwargs)
@@ -102,39 +109,69 @@ class SnapClient(AbstractSnapsClient):
         return response
 
     async def ping(self) -> httpx.Response:
-        """Reserved for human-readable content describing the service.
+        """
+        Reserved for human-readable content describing the service.
 
-        Returns:
-            httpx.Response: _description_
+        :returns: The response from the ping request.
+        :rtype: httpx.Response
         """
         response = await self.snapd_client.get(f"{self._base_url}/")
 
         return response
 
+    @retry(httpx.HTTPError, tries=3, delay=0.5)
     async def get_changes_by_id(self, change_id: str) -> ChangesResponse:
+        """
+        Asynchronously retrieves changes by their ID.
+
+        :param change_id: The ID of the change to retrieve.
+        :type change_id: str
+
+        :returns: The response object containing the changes.
+        :rtype: ChangesResponse
+
+        :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(
-                f"Bad response status code for get_changes_by_id: {e.response.status_code}"
+                "Bad response status code for get_changes_by_id: %s",
+                e.response.status_code,
             )
             response = e.response
-            pass
 
         return ChangesResponse.model_validate_json(response.content)
 
     async def get_changes_by_id_generator(
         self, change_id: str
     ) -> 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.
+
+        :param change_id: The ID of the change to fetch.
+        :type change_id: str
+
+        :yields: The response object containing the changes.
+        :rtype: ChangesResponse
+
+        :raises httpx.HTTPStatusError: If the request fails with an HTTP status error.
+        """
         while True:
             try:
                 response = await self.request("GET", f"changes/{change_id}")
             except httpx.HTTPStatusError as e:
                 logger.warning(
-                    f"Bad response status code for get_changes_by_id: {e.response.status_code}"
+                    "Bad response status code for get_changes_by_id: %s",
+                    e.response.status_code,
                 )
                 response = e.response
-                pass
 
             change_response = ChangesResponse.model_validate_json(response.content)
             yield change_response

snap_python-0.1.1/src/snap_python/components/snaps.py

@@ -0,0 +1,333 @@
+import asyncio
+import logging
+from pathlib import Path
+
+import httpx
+
+from snap_python.schemas.changes import ChangesResponse
+from snap_python.schemas.common import AsyncResponse
+from snap_python.schemas.snaps import (
+    InstalledSnapListResponse,
+    SingleInstalledSnapResponse,
+)
+from snap_python.utils import AbstractSnapsClient, SnapdAPIError, going_to_reload_daemon
+
+logger = logging.getLogger("snap_python.components.snaps")
+
+
+class SnapsEndpoints:
+    def __init__(self, client: AbstractSnapsClient) -> None:
+        self._client = client
+        self.common_endpoint = "snaps"
+
+    async def list_installed_snaps(self) -> InstalledSnapListResponse:
+        """
+        Asynchronously retrieves a list of installed snaps.
+
+        :returns: The response containing the list of installed snaps.
+        :rtype: InstalledSnapListResponse
+
+        :raises httpx.HTTPStatusError: If the response status code does not indicate success.
+        """
+
+        response: httpx.Response = await self._client.request(
+            "GET", self.common_endpoint
+        )
+
+        response = InstalledSnapListResponse.model_validate_json(response.content)
+        if response.status_code > 299:
+            raise httpx.HTTPStatusError(
+                request=response.request,
+                response=response,
+                message=f"Invalid status code in response: {response.status_code}",
+            )
+        return response
+
+    async def get_snap_info(self, snap: str) -> SingleInstalledSnapResponse:
+        """
+        Retrieves information about a specific snap.
+
+        :param snap: The name of the snap to retrieve information for.
+        :type snap: str
+
+        :returns: The response containing information about the snap.
+        :rtype: SingleInstalledSnapResponse
+
+        :raises httpx.HTTPStatusError: If the response status code does not indicate success.
+        """
+        try:
+            response: httpx.Response = await self._client.request(
+                "GET", f"{self.common_endpoint}/{snap}"
+            )
+        except httpx.HTTPStatusError as e:
+            logger.debug(
+                "Bad status code from get_snap_info on snap %s: %s",
+                snap,
+                e.response.status_code,
+            )
+            response = e.response
+
+        return SingleInstalledSnapResponse.model_validate_json(response.content)
+
+    async def is_snap_installed(self, snap: str) -> bool:
+        """
+        Check if a snap package is installed.
+
+        :param snap: The name of the snap package to check.
+        :type snap: str
+
+        :returns: True if the snap package is installed, False otherwise.
+        :rtype: bool
+        """
+
+        snap_info = await self.get_snap_info(snap)
+        if snap_info.status == "OK":
+            return True
+        return False
+
+    async def install_snap(
+        self,
+        snap: str,
+        channel: str = "stable",
+        classic: bool = False,
+        dangerous: bool = False,
+        devmode: bool = False,
+        jailmode: bool = False,
+        revision: int = None,
+        filename: str = None,
+        wait: bool = False,
+    ) -> AsyncResponse | ChangesResponse:
+        """
+        Install or sideload a snap.
+
+        To sideload a snap, provide the filename parameter with the path to the snap file.
+
+        :param snap: Name of the snap to install.
+        :type snap: str
+        :param channel: Channel to install, defaults to "stable".
+        :type channel: str, optional
+        :param classic: Install with classic confinement, defaults to False.
+        :type classic: bool, optional
+        :param dangerous: Install the given snap files even if there are no pre-acknowledged signatures for them, meaning they are not verified and could be dangerous if true (optional, implied by devmode), defaults to False.
+        :type dangerous: bool, optional
+        :param devmode: Install with devmode, defaults to False.
+        :type devmode: bool, optional
+        :param jailmode: Install snap with jailmode, defaults to False.
+        :type jailmode: bool, optional
+        :param revision: Install a specific revision of the snap, defaults to None.
+        :type revision: int, optional
+        :param filename: Path to snap to sideload, defaults to None.
+        :type filename: str, optional
+        :param wait: Whether to wait for snap to install. If not waiting, will return async response with change id, defaults to False.
+        :type wait: bool, optional
+
+        :raises FileNotFoundError: If the specified snap file does not exist.
+        :raises ValueError: If attempting to sideload without the dangerous flag set to True.
+        :raises SnapdAPIError: If there is an error during the snap install.
+
+        :returns: If wait is True, will return ChangesResponse. Otherwise, will return AsyncResponse.
+        :rtype: AsyncResponse | ChangesResponse
+        """
+        request_data = {
+            "action": "install",
+            "channel": channel,
+            "classic": classic,
+            "dangerous": dangerous,
+            "devmode": devmode,
+            "jailmode": jailmode,
+        }
+        if revision:
+            request_data["revision"] = revision
+        if filename:
+            # sideload
+            if not Path(filename).exists():
+                raise FileNotFoundError(f"File {filename} does not exist")
+            if request_data.get("dangerous") is not True:
+                raise ValueError(
+                    "Cannot sideload snap without dangerous flag set to True"
+                )
+            raw_response: httpx.Response = await self._client.request(
+                "POST",
+                f"{self.common_endpoint}",
+                data=request_data,
+                files={"snap": open(filename, "rb")},
+            )
+        else:
+            # install from default snap store
+            raw_response: httpx.Response = await self._client.request(
+                "POST", f"{self.common_endpoint}/{snap}", json=request_data
+            )
+        response = AsyncResponse.model_validate_json(raw_response.content)
+        if wait:
+            changes_id = response.change
+            previous_changes = None
+            while True:
+                try:
+                    changes = await self._client.get_changes_by_id(changes_id)
+                    logger.debug("Progress: %s", changes.result.overall_progress)
+                except httpx.HTTPError:
+                    if going_to_reload_daemon(previous_changes):
+                        logger.debug("Waiting for daemon to reload")
+                        changes = previous_changes
+
+                if changes.ready:
+                    break
+                if changes.result.err:
+                    raise SnapdAPIError(f"Error in snap install: {changes.result.err}")
+                await asyncio.sleep(0.1)
+                previous_changes = changes
+            return changes
+        return response
+
+    async def remove_snap(
+        self,
+        snap: str,
+        purge: bool = False,
+        terminate: bool = False,
+        wait: bool = False,
+    ) -> AsyncResponse | ChangesResponse:
+        """
+        Asynchronously removes a snap package.
+
+        :param snap: The name of the snap package to remove.
+        :type snap: str
+        :param purge: If True, purges the snap package. Defaults to False.
+        :type purge: bool, optional
+        :param terminate: If True, terminates the snap package. Defaults to False.
+        :type terminate: bool, optional
+        :param wait: If True, waits for the removal process to complete. Defaults to False.
+        :type wait: bool, optional
+
+        :returns: The response from the snapd API, either an asynchronous response or a changes response if waiting for completion.
+        :rtype: AsyncResponse | ChangesResponse
+
+        :raises SnapdAPIError: If there is an error in the snap removal process.
+        """
+        request_data = {
+            "action": "remove",
+            "purge": purge,
+            "terminate": terminate,
+        }
+
+        raw_response: httpx.Response = await self._client.request(
+            "POST", f"{self.common_endpoint}/{snap}", json=request_data
+        )
+        response = AsyncResponse.model_validate_json(raw_response.content)
+
+        if wait:
+            changes_id = response.change
+            previous_changes = None
+            while True:
+                try:
+                    changes = await self._client.get_changes_by_id(changes_id)
+                except httpx.HTTPError:
+                    if going_to_reload_daemon(previous_changes):
+                        logger.debug("Waiting for daemon to reload")
+                        await asyncio.sleep(0.1)
+                        continue
+                if changes.ready:
+                    break
+                if changes.result.err:
+                    raise SnapdAPIError(f"Error in snap remove: {changes.result.err}")
+                await asyncio.sleep(0.1)
+                previous_changes = changes
+            return changes
+
+        return response
+
+    async def refresh_snap(
+        self,
+        snap: str,
+        channel: str = "stable",
+        classic: bool = False,
+        dangerous: bool = False,
+        devmode: bool = False,
+        ignore_validation: bool = False,
+        jailmode: bool = False,
+        revision: int = None,
+        filename: str = None,
+        wait: bool = False,
+    ) -> AsyncResponse | ChangesResponse:
+        """
+        Refreshes a snap package.
+
+        :param snap: The name of the snap package to refresh.
+        :type snap: str
+        :param channel: The channel to refresh the snap from. Defaults to "stable".
+        :type channel: str, optional
+        :param classic: Whether to use classic confinement. Defaults to False.
+        :type classic: bool, optional
+        :param dangerous: Whether to allow installation of unasserted snaps. Defaults to False.
+        :type dangerous: bool, optional
+        :param devmode: Whether to use development mode. Defaults to False.
+        :type devmode: bool, optional
+        :param ignore_validation: Whether to ignore validation. Defaults to False.
+        :type ignore_validation: bool, optional
+        :param jailmode: Whether to use jail mode. Defaults to False.
+        :type jailmode: bool, optional
+        :param revision: The specific revision to refresh to. Defaults to None.
+        :type revision: int, optional
+        :param filename: The path to the snap file for sideloading. Defaults to None.
+        :type filename: str, optional
+        :param wait: Whether to wait for the refresh operation to complete. Defaults to False.
+        :type wait: bool, optional
+
+        :returns: The response from the refresh operation.
+        :rtype: AsyncResponse | ChangesResponse
+
+        :raises FileNotFoundError: If the specified snap file does not exist.
+        :raises ValueError: If attempting to sideload without the dangerous flag set to True.
+        :raises SnapdAPIError: If there is an error during the snap refresh.
+        """
+        request_data = {
+            "action": "refresh",
+            "channel": channel,
+            "classic": classic,
+            "dangerous": dangerous,
+            "devmode": devmode,
+            "ignore_validation": ignore_validation,
+            "jailmode": jailmode,
+        }
+        if revision:
+            request_data["revision"] = revision
+        if filename:
+            # sideload
+            if not Path(filename).exists():
+                raise FileNotFoundError(f"File {filename} does not exist")
+            if request_data.get("dangerous") is not True:
+                raise ValueError(
+                    "Cannot sideload snap without dangerous flag set to True"
+                )
+            raw_response: httpx.Response = await self._client.request(
+                "POST",
+                f"{self.common_endpoint}",
+                data=request_data,
+                files={"snap": open(filename, "rb")},
+            )
+        else:
+            # install from default snap store
+            raw_response: httpx.Response = await self._client.request(
+                "POST", f"{self.common_endpoint}/{snap}", json=request_data
+            )
+        response = AsyncResponse.model_validate_json(raw_response.content)
+        if wait:
+            changes_id = response.change
+            previous_changes = None
+            while True:
+                try:
+                    changes = await self._client.get_changes_by_id(changes_id)
+                    logger.debug("Progress: %s", changes.result.overall_progress)
+                except httpx.HTTPError:
+                    if going_to_reload_daemon(previous_changes):
+                        logger.debug("Waiting for daemon to reload")
+                        await asyncio.sleep(0.1)
+                        continue
+
+                if changes.ready:
+                    break
+                if changes.result.err:
+                    raise SnapdAPIError(f"Error in snap remove: {changes.result.err}")
+                await asyncio.sleep(0.1)
+                previous_changes = changes
+            return changes
+        return response

{snap_python-0.0.5 → snap_python-0.1.1}/src/snap_python/components/store.py

@@ -11,6 +11,7 @@ from snap_python.schemas.store.categories import (
 from snap_python.schemas.store.info import VALID_SNAP_INFO_FIELDS, InfoResponse
 from snap_python.schemas.store.search import (
     VALID_SEARCH_CATEGORY_FIELDS,
+    ArchSearchResponse,
     SearchResponse,
 )
 
@@ -36,6 +37,19 @@ class StoreEndpoints:
             self.store_client.headers.update(headers)
 
     async def get_snap_details(self, snap_name: str, fields: list[str] | None = None):
+        """
+        Get details of a snap.
+
+        :param snap_name: The name of the snap.
+        :type snap_name: str
+        :param fields: The fields to include in the response.
+        :type fields: list[str], optional
+
+        :returns: The snap details.
+        :rtype: dict
+
+        :raises ValueError: If invalid fields are provided.
+        """
         query = {}
         if fields is not None:
             if not all(field in VALID_SEARCH_CATEGORY_FIELDS for field in fields):
@@ -51,6 +65,19 @@ class StoreEndpoints:
         return response.json()
 
     async def get_snap_info(self, snap_name: str, fields: list[str] | None = None):
+        """
+        Get information about a snap.
+
+        :param snap_name: The name of the snap.
+        :type snap_name: str
+        :param fields: The fields to include in the response.
+        :type fields: list[str], optional
+
+        :returns: The snap information.
+        :rtype: InfoResponse
+
+        :raises ValueError: If invalid fields are provided.
+        """
         query = {}
         if fields is not None:
             if not all(field in VALID_SNAP_INFO_FIELDS for field in fields):
@@ -68,6 +95,19 @@ class StoreEndpoints:
     async def get_categories(
         self, type: str | None = None, fields: list[str] | None = None
     ) -> CategoryResponse:
+        """
+        Get categories of snaps.
+
+        :param type: The type of categories.
+        :type type: str, optional
+        :param fields: The fields to include in the response.
+        :type fields: list[str], optional
+
+        :returns: The categories.
+        :rtype: CategoryResponse
+
+        :raises ValueError: If invalid fields are provided.
+        """
         query = {}
         if fields is not None:
             if not all(field in VALID_CATEGORY_FIELDS for field in fields):
@@ -85,6 +125,19 @@ class StoreEndpoints:
     async def get_category_by_name(
         self, name: str, fields: list[str] | None = None
     ) -> SingleCategoryResponse:
+        """
+        Get a category by name.
+
+        :param name: The name of the category.
+        :type name: str
+        :param fields: The fields to include in the response.
+        :type fields: list[str], optional
+
+        :returns: The category.
+        :rtype: SingleCategoryResponse
+
+        :raises ValueError: If invalid fields are provided.
+        """
         query = {}
         if fields is not None:
             if not all(field in VALID_CATEGORY_FIELDS for field in fields):
@@ -113,10 +166,39 @@ class StoreEndpoints:
         publisher: str | None = None,
         headers: dict[str, str] | None = None,
     ) -> SearchResponse:
-        """from https://api.snapcraft.io/docs/search.html#snaps_find
-        and https://snapcraft.io/docs/snapd-api#heading--find
         """
+        Search for snaps in the store.
+
+        :param query: The search query.
+        :type query: str, optional
+        :param fields: The fields to include in the response.
+        :type fields: str, optional
+        :param name_startswith: Filter snaps by name prefix.
+        :type name_startswith: str, optional
+        :param architecture: Filter snaps by architecture.
+        :type architecture: str, optional
+        :param common_id: Filter snaps by common ID.
+        :type common_id: str, optional
+        :param category: Filter snaps by category.
+        :type category: str, optional
+        :param channel: Filter snaps by channel.
+        :type channel: str, optional
+        :param confiement: Filter snaps by confinement.
+        :type confiement: str, optional
+        :param featured: Filter snaps by featured status.
+        :type featured: bool, optional
+        :param private: Filter snaps by private status.
+        :type private: bool, optional
+        :param publisher: Filter snaps by publisher.
+        :type publisher: str, optional
+        :param headers: Additional headers to include in the request.
+        :type headers: dict[str, str], optional
+
+        :returns: The search response.
+        :rtype: SearchResponse
 
+        :raises ValueError: If invalid fields are provided.
+        """
         route = "/snaps/find"
         query_dict: dict = {
             "q": query,
@@ -159,9 +241,67 @@ class StoreEndpoints:
 
     @retry.retry(Exception, tries=3, delay=2, backoff=2)
     async def retry_get_snap_info(self, snap_name: str, fields: list[str]):
+        """
+        Retry getting snap information.
+
+        :param snap_name: The name of the snap.
+        :type snap_name: str
+        :param fields: The fields to include in the response.
+        :type fields: list[str]
+
+        :returns: The snap information.
+        :rtype: InfoResponse
+        """
         return await self.get_snap_info(snap_name=snap_name, fields=fields)
 
     async def get_top_snaps_from_category(self, category: str) -> SearchResponse:
+        """
+        Get top snaps from a category.
+
+        :param category: The category name.
+        :type category: str
+
+        :returns: The search response.
+        :rtype: SearchResponse
+        """
         return await self.find(
             category=category, fields=["title", "store-url", "summary"]
         )
+
+    async def get_all_snaps_for_arch(self, arch: str) -> ArchSearchResponse:
+        """
+        Get all snaps for a given architecture.
+
+        :param arch: The architecture.
+        :type arch: str
+
+        :returns: The search response.
+        :rtype: ArchSearchResponse
+
+        :raises ValueError: If invalid architecture is provided.
+        """
+        # use the old "/api/v1/snaps/names" to get all snaps for a given architecture
+
+        # ensure valid arch
+        if arch not in [
+            "amd64",
+            "arm64",
+            "armhf",
+            "i386",
+            "ppc64el",
+            "s390x",
+            "riscv64",
+        ]:
+            raise ValueError(f"Invalid architecture: {arch}")
+
+        route = "/api/v1/snaps/names"
+        extra_headers = {"X-Ubuntu-Architecture": arch}
+
+        response = await self.store_client.get(
+            f"{self._raw_base_url}{route}", headers=extra_headers, timeout=60
+        )
+        response.raise_for_status()
+
+        response_json = response.json()
+        response_json["arch"] = arch
+        return ArchSearchResponse.model_validate(response_json)

{snap_python-0.0.5 → snap_python-0.1.1}/src/snap_python/schemas/store/search.py

@@ -1,6 +1,13 @@
 from typing import Any, Dict, List, Optional
 
-from pydantic import AliasChoices, AwareDatetime, BaseModel, ConfigDict, Field
+from pydantic import (
+    AliasChoices,
+    AliasPath,
+    AwareDatetime,
+    BaseModel,
+    ConfigDict,
+    Field,
+)
 
 from snap_python.schemas.common import Revision
 from snap_python.schemas.snaps import InstalledSnap, Snap, StoreSnap, StoreSnapFields
@@ -120,3 +127,21 @@ class SearchResponse(BaseModel):
 
     error_list: Optional[List[ErrorListItem]] = Field(None, alias="error-list")
     results: List[SearchResult]
+
+
+class ArchSearchItem(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    aliases: Optional[list[dict[str, str]]]
+    apps: list[str]
+    package_name: str
+    summary: str
+    title: str
+    version: str
+
+
+class ArchSearchResponse(BaseModel):
+    results: list[ArchSearchItem] = Field(
+        alias=AliasPath("_embedded", "clickindex:package")
+    )
+    arch: str

{snap_python-0.0.5 → snap_python-0.1.1}/src/snap_python/utils.py

@@ -5,13 +5,21 @@ import httpx
 from snap_python.schemas.changes import ChangesResponse
 
 
+class SnapdAPIError(Exception):
+    """
+    General Exception raised for errors in the Snapd API.
+    """
+
+    pass
+
+
 class AbstractSnapsClient(ABC):  # pragma: no cover
     @abstractmethod
-    async def request(self) -> httpx.Response:
+    async def request(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
         pass
 
     @abstractmethod
-    async def request_raw(self) -> httpx.Response:
+    async def request_raw(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
         pass
 
     @abstractmethod
@@ -20,6 +28,16 @@ class AbstractSnapsClient(ABC):  # pragma: no cover
 
 
 def going_to_reload_daemon(changes: ChangesResponse | None) -> bool:
+    """
+    Determines if a daemon reload is required based on the provided changes.
+
+    :param changes: An instance of ChangesResponse or None.
+    :type changes: ChangesResponse | None
+
+    :returns: True if a daemon reload or restart is required, False otherwise.
+    :rtype: bool
+    """
+
     if changes is None or not isinstance(changes, ChangesResponse):
         return False
 

snap_python-0.0.5/PKG-INFO

@@ -1,53 +0,0 @@
-Metadata-Version: 2.1
-Name: snap-python
-Version: 0.0.5
-Summary: An api to interact with snapd and snap stores
-Home-page: https://github.com/alexlukens/snap-python
-License: MIT
-Author: Alexander Lukens
-Author-email: alexdlukens@gmail.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: httpx (>=0.27.2,<0.28.0)
-Requires-Dist: pydantic (>=2.9.2,<3.0.0)
-Requires-Dist: retry (>=0.9.2,<0.10.0)
-Project-URL: Repository, https://github.com/alexlukens/snap-python
-Description-Content-Type: text/markdown
-
-# snap_python
-
-snap_python provides an API client to interact with snapd
-
-## Installation
-
-To install snap_python, you can use pip:
-
-```
-pip install snap_python
-```
-
-## Usage
-
-Here is a simple example of how to use snap_python:
-
-```python
-# TODO
-```
-
-## Create a Release
-
-```bash
-git tag -a v0.x.x -m "Release v0.x.x"
-gh release create v0.x.x --title "Release v0.x.x"
-```
-
-The automation will build a wheel and push it to pypi
-
-## License
-
-This project is licensed under the MIT License. See the LICENSE file for more details.

snap_python-0.0.5/README.md

@@ -1,32 +0,0 @@
-# snap_python
-
-snap_python provides an API client to interact with snapd
-
-## Installation
-
-To install snap_python, you can use pip:
-
-```
-pip install snap_python
-```
-
-## Usage
-
-Here is a simple example of how to use snap_python:
-
-```python
-# TODO
-```
-
-## Create a Release
-
-```bash
-git tag -a v0.x.x -m "Release v0.x.x"
-gh release create v0.x.x --title "Release v0.x.x"
-```
-
-The automation will build a wheel and push it to pypi
-
-## License
-
-This project is licensed under the MIT License. See the LICENSE file for more details.

snap_python-0.0.5/src/snap_python/components/snaps.py

@@ -1,184 +0,0 @@
-import asyncio
-import logging
-from pathlib import Path
-
-import httpx
-
-from snap_python.schemas.changes import ChangesResponse
-from snap_python.schemas.common import AsyncResponse
-from snap_python.schemas.snaps import (
-    InstalledSnapListResponse,
-    SingleInstalledSnapResponse,
-)
-from snap_python.utils import AbstractSnapsClient, going_to_reload_daemon
-
-logger = logging.getLogger("snap_python.components.snaps")
-
-
-class SnapsEndpoints:
-    def __init__(self, client: AbstractSnapsClient) -> None:
-        self._client = client
-        self.common_endpoint = "snaps"
-
-    async def list_installed_snaps(self) -> InstalledSnapListResponse:
-        response: httpx.Response = await self._client.request(
-            "GET", self.common_endpoint
-        )
-
-        response = InstalledSnapListResponse.model_validate_json(response.content)
-        if response.status_code > 299:
-            raise httpx.HTTPStatusError(
-                request=response.request,
-                response=response,
-                message=f"Invalid status code in response: {response.status_code}",
-            )
-        return response
-
-    async def get_snap_info(self, snap: str) -> SingleInstalledSnapResponse:
-        try:
-            response: httpx.Response = await self._client.request(
-                "GET", f"{self.common_endpoint}/{snap}"
-            )
-        except httpx.HTTPStatusError as e:
-            logger.debug(
-                "Bad status code from get_snap_info on snap %s: %s",
-                snap,
-                e.response.status_code,
-            )
-            response = e.response
-
-        return SingleInstalledSnapResponse.model_validate_json(response.content)
-
-    async def is_snap_installed(self, snap: str) -> bool:
-        snap_info = await self.get_snap_info(snap)
-        if snap_info.status == "OK":
-            return True
-        return False
-
-    async def install_snap(
-        self,
-        snap: str,
-        channel: str = "stable",
-        classic: bool = False,
-        dangerous: bool = False,
-        devmode: bool = False,
-        ignore_validation: bool = False,
-        jailmode: bool = False,
-        revision: int = None,
-        filename: str = None,
-        wait: bool = False,
-    ) -> AsyncResponse | ChangesResponse:
-        """Install or sideload a snap
-
-        To sideload a snap, provide the filename parameter with the path to the snap file
-
-
-        Args:
-            snap (str): name of the snap to install
-            channel (str, optional): Channel to install. Defaults to "stable".
-            classic (bool, optional): Install with classic confinement. Defaults to False.
-            dangerous (bool, optional): install the given snap files even if there are no pre-acknowledged signatures for them, meaning they are not verified and could be dangerous if true (optional, implied by devmode). Defaults to False.
-            devmode (bool, optional): Install with devmode. Defaults to False.
-            ignore_validation (bool, optional): _description_. Defaults to False.
-            jailmode (bool, optional): Install snap with jailmode. Defaults to False.
-            revision (int, optional): install a specific revision of the snap. Defaults to None.
-            filename (str, optional): Path to snap to sideload. Defaults to None.
-            wait (bool, optional): Whether to wait for snap to install. If not waiting, will return async response with change id. Defaults to False.
-
-        Raises:
-            Exception: If error occurs during snap install
-
-        Returns:
-            AsyncResponse | ChangesResponse: If wait is True, will return ChangesResponse. Otherwise, will return AsyncResponse
-        """
-        request_data = {
-            "action": "install",
-            "channel": channel,
-            "classic": classic,
-            "dangerous": dangerous,
-            "devmode": devmode,
-            "ignore_validation": ignore_validation,
-            "jailmode": jailmode,
-        }
-        if revision:
-            request_data["revision"] = revision
-        if filename:
-            # sideload
-            if not Path(filename).exists():
-                raise FileNotFoundError(f"File {filename} does not exist")
-            if request_data.get("dangerous") is not True:
-                raise ValueError(
-                    "Cannot sideload snap without dangerous flag set to True"
-                )
-            raw_response: httpx.Response = await self._client.request(
-                "POST",
-                f"{self.common_endpoint}",
-                data=request_data,
-                files={"snap": open(filename, "rb")},
-            )
-        else:
-            # install from default snap store
-            raw_response: httpx.Response = await self._client.request(
-                "POST", f"{self.common_endpoint}/{snap}", json=request_data
-            )
-        response = AsyncResponse.model_validate_json(raw_response.content)
-        if wait:
-            changes_id = response.change
-            previous_changes = None
-            while True:
-                try:
-                    changes = await self._client.get_changes_by_id(changes_id)
-                    logger.debug(f"Progress: {changes.result.overall_progress}")
-                except httpx.HTTPError as e:
-                    if going_to_reload_daemon(previous_changes):
-                        logger.debug("Waiting for daemon to reload")
-                        await asyncio.sleep(0.1)
-                        continue
-
-                if changes.ready:
-                    break
-                if changes.result.err:
-                    raise Exception(f"Error in snap install: {changes.result.err}")
-                await asyncio.sleep(0.1)
-                previous_changes = changes
-            return changes
-        return response
-
-    async def remove_snap(
-        self,
-        snap: str,
-        purge: bool = False,
-        terminate: bool = False,
-        wait: bool = False,
-    ) -> AsyncResponse | ChangesResponse:
-        request_data = {
-            "action": "remove",
-            "purge": purge,
-            "terminate": terminate,
-        }
-
-        raw_response: httpx.Response = await self._client.request(
-            "POST", f"{self.common_endpoint}/{snap}", json=request_data
-        )
-        response = AsyncResponse.model_validate_json(raw_response.content)
-
-        if wait:
-            changes_id = response.change
-            previous_changes = None
-            while True:
-                try:
-                    changes = await self._client.get_changes_by_id(changes_id)
-                except httpx.HTTPError as e:
-                    if going_to_reload_daemon(previous_changes):
-                        logger.debug("Waiting for daemon to reload")
-                        await asyncio.sleep(0.1)
-                        continue
-                if changes.ready:
-                    break
-                if changes.result.err:
-                    raise Exception(f"Error in snap remove: {changes.result.err}")
-                await asyncio.sleep(0.1)
-                previous_changes = changes
-            return changes
-
-        return response