snap-python 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

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,
@@ -64,7 +72,9 @@ 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.
 
@@ -305,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/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/schemas/store/refresh.py

@@ -0,0 +1,122 @@
+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 RefreshResultError(BaseModel):
+    code: str
+    message: str
+    extra: Optional[dict] = None
+
+
+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"
+    )
+    error: RefreshResultError | None = None
+
+    @property
+    def is_error(self) -> bool:
+        if self.error:
+            return True
+        return False
+
+
+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/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/scrape.py

@@ -0,0 +1,129 @@
+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
+
+    """
+
+    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.1.dist-info → snap_python-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: snap-python
-Version: 0.1.1
+Version: 0.1.3
 Summary: Interact with snapd and snapstore(s) from Python
 License: MIT
 Author: Alexander Lukens

{snap_python-0.1.1.dist-info → snap_python-0.1.3.dist-info}/RECORD

@@ -3,21 +3,23 @@ snap_python/client.py,sha256=rZAfzcQNhdtTyjQml1N-9-nAianFyEwOaI4H_0FMaFE,6612
 snap_python/components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 snap_python/components/config.py,sha256=IO_gCrumphEZioINFmXxb8I5OVsKC9cgSa28sQbZ700,1775
 snap_python/components/snaps.py,sha256=FQ362L83jmhu3MLKszOU1w5jGP8l5-WNBlUTLnR6IW8,13176
-snap_python/components/store.py,sha256=8E613XeKWt9kc7bAtKPhYq1PULmxZU0RnrULKW2HGQQ,10778
+snap_python/components/store.py,sha256=8r1WUOBu2vPpDXGSSgK9f1HKU3Rfl6wAPu6siTnEcPU,13803
 snap_python/schemas/changes.py,sha256=7SYUFXAQq9arl7hAA3YQ0YubMurPJtknTOVxP8ryqew,1919
 snap_python/schemas/common.py,sha256=GLtC9aBo3O8vLKX9PNvzE-_DKN02OGpwsS7Ik2WK9-8,2608
 snap_python/schemas/config.py,sha256=xXTGhk6TpwI8RlR6_qnfWlBHrBnTwr3hRCO5qCnN-6U,107
 snap_python/schemas/snaps.py,sha256=cO0UwghFZwfIlJtAjYDdNgfLKwU7953B9bgolpXcUL0,2980
 snap_python/schemas/store/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 snap_python/schemas/store/categories.py,sha256=PewotRqoPs7cMKtlZKsHVNfnJoItmNKMekS1Be-46l0,1082
-snap_python/schemas/store/info.py,sha256=TuqG5wZc89e_Epai1xkcpA1nXNMKBOKng0B40xm_PfU,3333
+snap_python/schemas/store/info.py,sha256=K2y1NOrSLZEszGJur5L0W_1ap4P038cK4ThSjLcyQLA,4407
 snap_python/schemas/store/json/category_by_name_schema.json,sha256=3-95m6V2WXaPCu_DZw-STa9YHPEbr7CI8fbhjaq881s,1674
 snap_python/schemas/store/json/category_schema.json,sha256=c4h_eyyBbChOiNby3hYfjAh9i_1MDbPJnHHU4rGOGss,1898
 snap_python/schemas/store/json/snaps_find_schema.json,sha256=TfKpnievs5QOc7ah97ATMCQTOEfKspONTZnwSwq_0fI,8866
 snap_python/schemas/store/json/snaps_info_schema.json,sha256=udoOovb6Ea7EnE_R9RuZ1CpY1wOJ3-K8xP4-8zKHgrQ,15888
-snap_python/schemas/store/search.py,sha256=u92aFLLuvDwpfMNHlZo7O2-k-kj7cgzAOtvxxsvi6mU,3718
+snap_python/schemas/store/refresh.py,sha256=HAlt-rKfy7vmZSCujMXtW9HHXlVYbHGFwy_BKfD1uCU,3190
+snap_python/schemas/store/search.py,sha256=-Fd1G821-V6JVxvbcgfnzXy8VQoWnS9MR1oLdRurqu0,3743
+snap_python/scrape.py,sha256=ZDJAROp8jwossaAA78gBFTKQzrfnO11RgyyOZqevNd0,4576
 snap_python/utils.py,sha256=cmUooPg5DzNL197Xxvu7LGD4Gwk3xxsT68wbVytRtV0,1240
-snap_python-0.1.1.dist-info/LICENSE,sha256=lYXNZszxC_l2rlBvrHYs-esDegxWh8MKtjrdxA24uOk,1072
-snap_python-0.1.1.dist-info/METADATA,sha256=CKofDQQsSyKxoIVDf4ELXETRIva_1w6Hxoe--UJh0S8,1883
-snap_python-0.1.1.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-snap_python-0.1.1.dist-info/RECORD,,
+snap_python-0.1.3.dist-info/LICENSE,sha256=lYXNZszxC_l2rlBvrHYs-esDegxWh8MKtjrdxA24uOk,1072
+snap_python-0.1.3.dist-info/METADATA,sha256=rnVfkQFtCUJNz5018Yh4_VOwZTTeo1SveVswcZka7bI,1883
+snap_python-0.1.3.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+snap_python-0.1.3.dist-info/RECORD,,

{snap_python-0.1.1.dist-info → snap_python-0.1.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.0.1
+Generator: poetry-core 2.1.1
 Root-Is-Purelib: true
 Tag: py3-none-any