snap-python 0.1.0__tar.gz → 0.1.2__tar.gz

snap_python-0.1.2/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.3
+Name: snap-python
+Version: 0.1.2
+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.2/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.1.0 → snap_python-0.1.2}/pyproject.toml

@@ -1,11 +1,12 @@
 [tool.poetry]
 name = "snap-python"
-version = "0.1.0"
-description = "An api to interact with snapd and snap stores"
+version = "0.1.2"
+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,6 +24,7 @@ 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"]

{snap_python-0.1.0 → snap_python-0.1.2}/src/snap_python/client.py

@@ -65,16 +65,19 @@ class SnapClient(AbstractSnapsClient):
 
     @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(
@@ -85,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)
@@ -103,10 +109,11 @@ 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}/")
 
@@ -116,12 +123,14 @@ class SnapClient(AbstractSnapsClient):
     async def get_changes_by_id(self, change_id: str) -> ChangesResponse:
         """
         Asynchronously retrieves changes by their ID.
-        Args:
-            change_id (str): The ID of the change to retrieve.
-        Returns:
-            ChangesResponse: The response object containing the changes.
-        Raises:
-            httpx.HTTPStatusError: If the request results in an HTTP error.
+
+        :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:
@@ -140,16 +149,19 @@ class SnapClient(AbstractSnapsClient):
     ) -> 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.
-        Args:
-            change_id (str): The ID of the change to fetch.
-        Yields:
-            ChangesResponse: The response object containing the changes.
-        Raises:
-            httpx.HTTPStatusError: If the request fails with an HTTP status error.
+
+        :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:

{snap_python-0.1.0 → snap_python-0.1.2}/src/snap_python/components/snaps.py

@@ -21,6 +21,15 @@ class SnapsEndpoints:
         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
         )
@@ -35,6 +44,17 @@ class SnapsEndpoints:
         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}"
@@ -50,6 +70,16 @@ class SnapsEndpoints:
         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
@@ -67,27 +97,36 @@ class SnapsEndpoints:
         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
+        """
+        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.
-            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.
+        :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:
-            SnapdAPIError: If error occurs during snap install
+        :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:
-            AsyncResponse | ChangesResponse: If wait is True, will return ChangesResponse. Otherwise, will return AsyncResponse
+        :returns: If wait is True, will return ChangesResponse. Otherwise, will return AsyncResponse.
+        :rtype: AsyncResponse | ChangesResponse
         """
         request_data = {
             "action": "install",
@@ -149,15 +188,20 @@ class SnapsEndpoints:
     ) -> AsyncResponse | ChangesResponse:
         """
         Asynchronously removes a snap package.
-        Args:
-            snap (str): The name of the snap package to remove.
-            purge (bool, optional): If True, purges the snap package. Defaults to False.
-            terminate (bool, optional): If True, terminates the snap package. Defaults to False.
-            wait (bool, optional): If True, waits for the removal process to complete. Defaults to False.
-        Returns:
-            AsyncResponse | ChangesResponse: The response from the snapd API, either an asynchronous response or a changes response if waiting for completion.
-        Raises:
-            SnapdAPIError: If there is an error in the snap removal process.
+
+        :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",
@@ -206,23 +250,34 @@ class SnapsEndpoints:
     ) -> AsyncResponse | ChangesResponse:
         """
         Refreshes a snap package.
-        Args:
-            snap (str): The name of the snap package to refresh.
-            channel (str, optional): The channel to refresh the snap from. Defaults to "stable".
-            classic (bool, optional): Whether to use classic confinement. Defaults to False.
-            dangerous (bool, optional): Whether to allow installation of unasserted snaps. Defaults to False.
-            devmode (bool, optional): Whether to use development mode. Defaults to False.
-            ignore_validation (bool, optional): Whether to ignore validation. Defaults to False.
-            jailmode (bool, optional): Whether to use jail mode. Defaults to False.
-            revision (int, optional): The specific revision to refresh to. Defaults to None.
-            filename (str, optional): The path to the snap file for sideloading. Defaults to None.
-            wait (bool, optional): Whether to wait for the refresh operation to complete. Defaults to False.
-        Returns:
-            AsyncResponse | ChangesResponse: The response from the refresh operation.
-        Raises:
-            FileNotFoundError: If the specified snap file does not exist.
-            ValueError: If attempting to sideload without the dangerous flag set to True.
-            SnapdAPIError: If there is an error during the snap refresh.
+
+        :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",

{snap_python-0.1.0 → snap_python-0.1.2}/src/snap_python/components/store.py

@@ -1,14 +1,22 @@
 import functools
+import uuid
 
 import retry
-from httpx import AsyncClient
+from httpx import AsyncClient, Response
 
 from snap_python.schemas.store.categories import (
     VALID_CATEGORY_FIELDS,
     CategoryResponse,
     SingleCategoryResponse,
 )
-from snap_python.schemas.store.info import VALID_SNAP_INFO_FIELDS, InfoResponse
+from snap_python.schemas.store.info import (
+    VALID_SNAP_INFO_FIELDS,
+    InfoResponse,
+)
+from snap_python.schemas.store.refresh import (
+    VALID_SNAP_REFRESH_FIELDS,
+    RefreshRevisionResponse,
+)
 from snap_python.schemas.store.search import (
     VALID_SEARCH_CATEGORY_FIELDS,
     ArchSearchResponse,
@@ -37,6 +45,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,7 +72,22 @@ class StoreEndpoints:
         response.raise_for_status()
         return response.json()
 
-    async def get_snap_info(self, snap_name: str, fields: list[str] | None = None):
+    async def get_snap_info(
+        self, snap_name: str, fields: list[str] | None = None
+    ) -> InfoResponse:
+        """
+        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):
@@ -69,6 +105,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):
@@ -86,6 +135,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):
@@ -114,10 +176,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,
@@ -160,14 +251,45 @@ 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
@@ -193,3 +315,84 @@ class StoreEndpoints:
         response_json = response.json()
         response_json["arch"] = arch
         return ArchSearchResponse.model_validate(response_json)
+
+    async def snap_refresh(
+        self, snap_name: str, payload: dict, extra_headers: dict = None
+    ) -> Response:
+        """Query the Store's "snap_refresh" endpoint.
+
+        Useful for more than refreshing a snap. Notably some snap information is only retrievable from this endpoint. E.g. old revision information
+
+        :param snap_name: The name of the snap.
+        :type snap_name: str
+        """
+        route = "/snaps/refresh"
+        if extra_headers is None:
+            extra_headers = {}
+        query = {}
+        response = await self.store_client.post(
+            f"{self.base_url}{route}", json=payload, headers=extra_headers, params=query
+        )
+
+        if not response.is_success:
+            # TODO: Add logging here
+            pass
+        return response
+
+    async def get_snap_revision_info(
+        self, snap_name: str, revision: int, arch: str, fields=None
+    ) -> RefreshRevisionResponse:
+        """Get information about a snap revision.
+
+        :param snap_name: The name of the snap.
+        :type snap_name: str
+        :param revision: The revision of the snap.
+        :type revision: int
+        :param arch: The architecture of the snap to retrieve details about (e.g. amd64, arm64, riscv64, etc).
+        :type arch: str
+
+        :returns: The snap revision information.
+        :rtype: RefreshRevisionResponse
+        """
+
+        # cast revision to int
+        revision = int(revision)
+        extra_headers = {"Snap-Device-Architecture": arch}
+        snap_info = await self.get_snap_info(snap_name=snap_name)
+
+        # I don't think this matters for the "context" field, so using info from the first available
+        channel_map_item = snap_info.channel_map[0]
+
+        payload = {
+            "context": [
+                {
+                    "tracking-channel": "stable",
+                    "snap-id": snap_info.snap_id,
+                    "revision": channel_map_item.revision,
+                    "instance-key": str(uuid.uuid4()),
+                }
+            ],
+            "actions": [
+                {
+                    "action": "download",
+                    "name": snap_name,
+                    "revision": revision,
+                    "instance-key": str(uuid.uuid4()),
+                }
+            ],
+        }
+
+        if fields is not None:
+            if not all(field in VALID_SNAP_REFRESH_FIELDS for field in fields):
+                raise ValueError(
+                    f"Invalid fields. Allowed fields: {VALID_SNAP_REFRESH_FIELDS}"
+                )
+        payload["fields"] = fields
+
+        response = await self.snap_refresh(
+            snap_name=snap_name,
+            payload=payload,
+            extra_headers=extra_headers,
+        )
+        response.raise_for_status()
+        return RefreshRevisionResponse.model_validate_json(response.content)

{snap_python-0.1.0 → snap_python-0.1.2}/src/snap_python/schemas/store/info.py

@@ -4,7 +4,7 @@
 
 from typing import List, Optional
 
-from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, AwareDatetime, BaseModel, ConfigDict, Field
 
 from snap_python.schemas.snaps import StoreSnap
 
@@ -47,7 +47,11 @@ class Channel(BaseModel):
 
     architecture: str
     name: str
-    released_at: Optional[AwareDatetime] = Field(None, alias="released-at")
+    released_at: Optional[AwareDatetime] = Field(
+        None,
+        alias=AliasChoices("released-at", "released_at"),
+        serialization_alias="released-at",
+    )
     risk: str
     track: str
 
@@ -56,7 +60,9 @@ class Delta(BaseModel):
     model_config = ConfigDict(extra="forbid", exclude_unset=True)
 
     format: str
-    sha3_384: str = Field(..., alias="sha3-384")
+    sha3_384: Optional[str] = Field(
+        None, alias=AliasChoices("sha3-384", "sha3_384"), serialization_alias="sha3-384"
+    )
     size: float
     source: float
     target: float
@@ -67,7 +73,9 @@ class Download(BaseModel):
     model_config = ConfigDict(extra="forbid", exclude_unset=True)
 
     deltas: List[Delta]
-    sha3_384: str = Field(..., alias="sha3-384")
+    sha3_384: Optional[str] = Field(
+        None, alias=AliasChoices("sha3-384", "sha3_384"), serialization_alias="sha3-384"
+    )
     size: float
     url: str
 
@@ -80,7 +88,9 @@ class Epoch(BaseModel):
 
 
 class Download1(BaseModel):
-    sha3_384: Optional[str] = Field(None, alias="sha3-384")
+    sha3_384: Optional[str] = Field(
+        None, alias=AliasChoices("sha3-384", "sha3_384"), serialization_alias="sha3-384"
+    )
     size: Optional[int] = None
     url: Optional[str] = None
 
@@ -89,7 +99,11 @@ class Resource(BaseModel):
     model_config = ConfigDict(extra="forbid", exclude_unset=True)
 
     architectures: Optional[List[str]] = None
-    created_at: Optional[str] = Field(None, alias="created-at")
+    created_at: Optional[str] = Field(
+        None,
+        alias=AliasChoices("created-at", "created_at"),
+        serialization_alias="created-at",
+    )
     description: Optional[str] = None
     download: Optional[Download1] = None
     name: Optional[str] = None
@@ -104,14 +118,26 @@ class ChannelMapItem(BaseModel):
     architectures: Optional[List[str]] = None
     base: Optional[str] = None
     channel: Channel
-    common_ids: Optional[List[str]] = Field(None, alias="common-ids")
+    common_ids: Optional[List[str]] = Field(
+        None,
+        alias=AliasChoices("common-ids", "common_ids"),
+        serialization_alias="common-ids",
+    )
     confinement: Optional[str] = None
-    created_at: Optional[AwareDatetime] = Field(None, alias="created-at")
+    created_at: Optional[AwareDatetime] = Field(
+        None,
+        alias=AliasChoices("created-at", "created_at"),
+        serialization_alias="created-at",
+    )
     download: Optional[Download] = None
     epoch: Optional[Epoch] = None
     resources: Optional[List[Resource]] = None
     revision: Optional[int] = None
-    snap_yaml: Optional[str] = Field(None, alias="snap-yaml")
+    snap_yaml: Optional[str] = Field(
+        None,
+        alias=AliasChoices("snap-yaml", "snap_yaml"),
+        serialization_alias="snap-yaml",
+    )
     type: Optional[str] = None
     version: Optional[str] = None
 
@@ -126,9 +152,23 @@ class ErrorListItem(BaseModel):
 class InfoResponse(BaseModel):
     model_config = ConfigDict(extra="forbid", exclude_unset=True)
 
-    channel_map: List[ChannelMapItem] = Field(..., alias="channel-map")
-    default_track: Optional[str] = Field(None, alias="default-track")
-    error_list: Optional[List[ErrorListItem]] = Field(None, alias="error-list")
+    channel_map: List[ChannelMapItem] = Field(
+        ...,
+        alias=AliasChoices("channel-map", "channel_map"),
+        serialization_alias="channel-map",
+    )
+    default_track: Optional[str] = Field(
+        None,
+        alias=AliasChoices("default-track", "default_track"),
+        serialization_alias="default-track",
+    )
+    error_list: Optional[List[ErrorListItem]] = Field(
+        None,
+        alias=AliasChoices("error-list", "error_list"),
+        serialization_alias="error-list",
+    )
     name: str
     snap: StoreSnap
-    snap_id: str = Field(..., alias="snap-id")
+    snap_id: str = Field(
+        ..., alias=AliasChoices("snap-id", "snap_id"), serialization_alias="snap-id"
+    )

snap_python-0.1.2/src/snap_python/schemas/store/refresh.py

@@ -0,0 +1,109 @@
+from typing import List, Optional
+
+from pydantic import AliasChoices, AwareDatetime, BaseModel, ConfigDict, Field
+
+from snap_python.schemas.snaps import Snap
+from snap_python.schemas.store.info import Download, ErrorListItem, Resource
+
+VALID_SNAP_REFRESH_FIELDS = [
+    "architectures",
+    "base",
+    "common-ids",
+    "confinement",
+    "contact",
+    "created-at",
+    "description",
+    "download",
+    "epoch",
+    "gated-snap-ids",
+    "license",
+    "links",
+    "media",
+    "name",
+    "prices",
+    "private",
+    "publisher",
+    "resources",
+    "revision",
+    "snap-id",
+    "snap-yaml",
+    "summary",
+    "title",
+    "type",
+    "version",
+    "website",
+]
+
+
+class SnapRefreshFields(BaseModel):
+    architectures: Optional[list[str]] = None
+    base: Optional[str] = None
+    common_ids: Optional[list[str]] = Field(
+        None, alias=AliasChoices("common-ids", "common_ids")
+    )
+    confinement: Optional[str] = None
+    created_at: Optional[AwareDatetime] = Field(
+        None,
+        alias=AliasChoices("created-at", "created_at"),
+        serialization_alias="created-at",
+    )
+    download: Optional[Download] = None
+    epoch: Optional[dict[str, list[int]]] = None
+    gated_snap_ids: Optional[list[str]] = Field(
+        None, alias=AliasChoices("gated-snap-ids", "gated_snap_ids")
+    )
+    license: Optional[str] = None
+    prices: Optional[dict[str, str]] = None
+    resources: list[Resource] = Field(default_factory=list)
+    revision: Optional[int] = None
+    snap_id: Optional[str] = Field(
+        None, alias=AliasChoices("snap-id", "snap_id"), serialization_alias="snap-id"
+    )
+    snap_yaml: Optional[str] = Field(
+        None,
+        alias=AliasChoices("snap-yaml", "snap_yaml"),
+        serialization_alias="snap-yaml",
+    )
+    type: Optional[str] = None
+    version: Optional[str] = None
+
+
+class StoreRefreshSnap(Snap, SnapRefreshFields):
+    pass
+
+
+class RefreshResultData(BaseModel):
+    model_config = ConfigDict(extra="forbid", exclude_unset=True)
+
+    default_track: Optional[str] = Field(
+        None,
+        alias=AliasChoices("default-track", "default_track"),
+        serialization_alias="default-track",
+    )
+
+    name: str
+    snap: StoreRefreshSnap
+    instance_key: str = Field(
+        ...,
+        alias=AliasChoices("instance-key", "instance_key"),
+        serialization_alias="instance-key",
+    )
+    released_at: Optional[AwareDatetime] = Field(
+        None,
+        alias=AliasChoices("released-at", "released_at"),
+        serialization_alias="released-at",
+    )
+    result: str
+
+    snap_id: str = Field(
+        ..., alias=AliasChoices("snap-id", "snap_id"), serialization_alias="snap-id"
+    )
+
+
+class RefreshRevisionResponse(BaseModel):
+    error_list: Optional[List[ErrorListItem]] = Field(
+        None,
+        alias=AliasChoices("error-list", "error_list"),
+        serialization_alias="error-list",
+    )
+    results: List[RefreshResultData]

{snap_python-0.1.0 → snap_python-0.1.2}/src/snap_python/schemas/store/search.py

@@ -142,6 +142,6 @@ class ArchSearchItem(BaseModel):
 
 class ArchSearchResponse(BaseModel):
     results: list[ArchSearchItem] = Field(
-        alias=AliasPath("_embedded", "clickindex:package")
+        alias=AliasChoices(AliasPath("_embedded", "clickindex:package"), "results")
     )
     arch: str

snap_python-0.1.2/src/snap_python/scrape.py

@@ -0,0 +1,130 @@
+import pathlib
+
+from snap_python.client import SnapClient
+from snap_python.schemas.store.info import ChannelMapItem
+from snap_python.schemas.store.refresh import VALID_SNAP_REFRESH_FIELDS
+
+
+def get_highest_revision(channel_map: list[ChannelMapItem]) -> ChannelMapItem:
+    """Find the ChannelMapItem with the highest revision number from a list of ChannelMapItems.
+
+    Find the highest revision in a provided channel map
+
+    Parameters:
+        channel_map (list[ChannelMapItem]): A list of ChannelMapItem objects to search through.
+
+    Returns:
+        ChannelMapItem: The item with the highest revision number
+
+    Example:
+
+        >>> items = [ChannelMapItem(revision=1), ChannelMapItem(revision=5), ChannelMapItem(revision=3)]
+        >>> highest = get_highest_revision(items)
+        >>> highest.revision
+        5
+
+    """
+
+    print(channel_map)
+    return max(channel_map, key=lambda x: x.revision)
+
+
+async def download_snap_file(
+    snap_client: SnapClient,
+    snap_revision_download: str,
+    snap_revision_download_path: pathlib.Path,
+):
+    """Asynchronously downloads a snap file from the Snap Store.
+
+    This function streams the snap file from the specified URL and writes it to
+    the specified path on disk.
+
+    Parameters:
+        snap_client (SnapClient): The client for interacting with the Snap Store.
+        snap_revision_download (str): The URL to download the snap file from.
+        snap_revision_download_path (pathlib.Path): The path where the downloaded snap file will be saved.
+
+    Returns:
+        None
+
+    """
+
+    store_client = snap_client.store.store_client
+    async with store_client.stream(
+        "GET", snap_revision_download, follow_redirects=True
+    ) as response:
+        with open(snap_revision_download_path, "wb") as f:
+            async for chunk in response.aiter_bytes():
+                f.write(chunk)
+
+
+async def get_all_snap_content(
+    snap_client: SnapClient,
+    snap_name: str,
+    output_dir: pathlib.Path | str,
+    start_revision: int = 1,
+    with_snap_files: bool = False,
+):
+    """
+    Asynchronously fetches and downloads all content for a specified snap package across multiple revisions.
+
+    This function retrieves metadata for each revision of a snap package and optionally downloads
+    the snap files themselves. All content is organized into directories by revision number.
+
+    Parameters:
+        snap_client (SnapClient): Initialized Snap client instance for API interactions.
+        snap_name (str): Name of the snap package to process.
+        output_dir (pathlib.Path | str): Directory where snap content will be saved.
+        start_revision (int, optional): First revision to process. Defaults to 1.
+        with_snap_files (bool, optional): Whether to download the actual snap package files. Defaults to False.
+
+    Returns:
+        None
+
+    Notes:
+        - Creates a directory structure where each revision has its own subdirectory
+        - Saves metadata as data.json in each revision directory
+        - When with_snap_files=True, also downloads the snap package file for each revision
+
+    """
+    if not isinstance(output_dir, pathlib.Path):
+        output_dir = pathlib.Path(output_dir)
+
+    if not output_dir.exists():
+        output_dir.mkdir(parents=True)
+
+    current_snap_info = await snap_client.store.get_snap_info(
+        snap_name, fields=["name", "channel-map", "revision"]
+    )
+    current_snap_channel = get_highest_revision(current_snap_info.channel_map)
+
+    print(
+        f"Processing snap {snap_name} from revision {start_revision} to {current_snap_channel.revision}"
+    )
+
+    for revision in range(1, current_snap_channel.revision + 1):
+        print(f"Processing revision {revision}")
+        revision_dir = output_dir / str(revision)
+        revision_dir.mkdir(exist_ok=True)
+        # get snap revision info
+        snap_revision_info = await snap_client.store.get_snap_revision_info(
+            snap_name, revision, arch="amd64", fields=VALID_SNAP_REFRESH_FIELDS
+        )
+
+        snap_revision_data = snap_revision_info.results[0]
+
+        with open(revision_dir / "data.json", "w") as f:
+            f.write(snap_revision_data.model_dump_json(indent=2))
+
+        # download snap revision
+        snap_revision_download = snap_revision_data.snap.download.url
+
+        # download the file
+        snap_revision_download_path = (
+            revision_dir / snap_revision_download.split("/")[-1]
+        )
+
+        if with_snap_files:
+            await download_snap_file(
+                snap_client, snap_revision_download, snap_revision_download_path
+            )

{snap_python-0.1.0 → snap_python-0.1.2}/src/snap_python/utils.py

@@ -6,6 +6,10 @@ from snap_python.schemas.changes import ChangesResponse
 
 
 class SnapdAPIError(Exception):
+    """
+    General Exception raised for errors in the Snapd API.
+    """
+
     pass
 
 
@@ -24,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.1.0/PKG-INFO

@@ -1,52 +0,0 @@
-Metadata-Version: 2.3
-Name: snap-python
-Version: 0.1.0
-Summary: An api to interact with snapd and snap stores
-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.1.0/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.