snap-python 0.0.1__py3-none-any.whl

snap_python/client.py

@@ -0,0 +1,86 @@
+import logging
+
+import httpx
+
+from snap_python.components.snaps import SnapsEndpoints
+from snap_python.components.store import StoreEndpoints
+from snap_python.schemas.changes import ChangesResponse
+from snap_python.utils import AbstractSnapsClient
+
+SNAPD_SOCKET = "/run/snapd.socket"
+
+logger = logging.getLogger("snap_python.client")
+logger.setLevel(logging.DEBUG)
+
+
+class SnapClient(AbstractSnapsClient):
+    def __init__(
+        self,
+        version: str = "v2",
+        snapd_socket_location: str = None,
+        tcp_location: str = None,
+        store_base_url: str = "https://api.snapcraft.io",
+        store_headers: dict[str, str] = None,
+    ):
+        if tcp_location and snapd_socket_location:
+            raise ValueError(
+                "Only one of snapd_socket_location or tcp_location can be provided."
+            )
+        if tcp_location is not None:
+            self._base_url = tcp_location
+            self._transport = httpx.AsyncHTTPTransport()
+        else:
+            self._base_url = "http://localhost"
+            self._transport = httpx.AsyncHTTPTransport(
+                uds=snapd_socket_location or SNAPD_SOCKET
+            )
+
+        if store_headers is None:
+            store_headers = {"Snap-Device-Series": "16", "X-Ubuntu-Series": "16"}
+
+        self.version = version
+        self.store_base_url = store_base_url
+        self.store_headers = store_headers
+        self.snapd_client = httpx.AsyncClient(transport=self._transport)
+        self.snaps = SnapsEndpoints(self)
+        self.store = StoreEndpoints(
+            base_url=self.store_base_url,
+            version=self.version,
+            headers=self.store_headers,
+        )
+
+    async def request(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
+        response = await self.snapd_client.request(
+            method, f"{self._base_url}/{self.version}/{endpoint}", **kwargs
+        )
+        logger.debug(f"response: {response.content}")
+        response.raise_for_status()
+        return response
+
+    async def request_raw(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
+        response = await self.snapd_client.request(method, endpoint, **kwargs)
+
+        response.raise_for_status()
+        return response
+
+    async def ping(self) -> httpx.Response:
+        """Reserved for human-readable content describing the service.
+
+        Returns:
+            httpx.Response: _description_
+        """
+        response = await self.snapd_client.get(f"{self._base_url}/")
+
+        return response
+
+    async def get_changes_by_id(self, change_id: str) -> ChangesResponse:
+        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}"
+            )
+            response = e.response
+            pass
+
+        return ChangesResponse.model_validate_json(response.content)

snap_python/components/snaps.py

@@ -0,0 +1,92 @@
+import asyncio
+
+import httpx
+
+from snap_python.schemas.changes import ChangesResponse
+from snap_python.schemas.common import AsyncResponse
+from snap_python.schemas.snaps import SnapListResponse
+from snap_python.utils import AbstractSnapsClient
+
+
+class SnapsEndpoints:
+    def __init__(self, client: AbstractSnapsClient) -> None:
+        self._client = client
+        self.common_endpoint = "snaps"
+
+    async def list_installed_snaps(self) -> SnapListResponse:
+        response: httpx.Response = await self._client.request(
+            "GET", self.common_endpoint
+        )
+
+        response = SnapListResponse.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 install_snap(
+        self,
+        snap: str,
+        channel: str = "stable",
+        classic: bool = False,
+        devmode: bool = False,
+        ignore_validation: bool = False,
+        jailmode: bool = False,
+        revision: int = None,
+        wait: bool = False,
+    ) -> AsyncResponse | ChangesResponse:
+        request_data = {
+            "action": "install",
+            "channel": channel,
+            "classic": classic,
+            "devmode": devmode,
+            "ignore_validation": ignore_validation,
+            "jailmode": jailmode,
+        }
+        if revision:
+            request_data["revision"] = revision
+        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
+            while True:
+                changes = await self._client.get_changes_by_id(changes_id)
+                if changes.ready:
+                    break
+                if changes.result.err:
+                    raise Exception(f"Error in snap install: {changes.result.err}")
+                await asyncio.sleep(2.0)
+            return changes
+        return response
+
+    async def remove_snap(
+        self, snap: str, purge: bool, terminate: bool, 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
+            while True:
+                changes = await self._client.get_changes_by_id(changes_id)
+                if changes.ready:
+                    break
+                if changes.result.err:
+                    raise Exception(f"Error in snap remove: {changes.result.err}")
+                await asyncio.sleep(2.0)
+            return changes
+
+        return response

snap_python/components/store.py

@@ -0,0 +1,167 @@
+import functools
+
+import retry
+from httpx import AsyncClient
+
+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.search import (
+    VALID_SEARCH_CATEGORY_FIELDS,
+    SearchResponse,
+)
+
+
+class StoreEndpoints:
+    """Query snap store that is available at <base_url> for information about snaps.
+    Calls made directly with store to enable querying the non-default snap store for information.
+    Snapd only supports the store at snapcraft.io
+
+    Certain functionality is not available in snapd, such as querying for/by categories
+    """
+
+    def __init__(
+        self, base_url: str, version: str, headers: dict[str, str] = None
+    ) -> None:
+        self.store_client = AsyncClient()
+        self.store_client.request = functools.partial(
+            self.store_client.request, timeout=5
+        )
+        self.base_url = f"{base_url}/{version}"
+        self._raw_base_url = base_url
+        if headers is not None:
+            self.store_client.headers.update(headers)
+
+    async def get_snap_details(self, snap_name: str, fields: list[str] | None = None):
+        query = {}
+        if fields is not None:
+            if not all(field in VALID_SEARCH_CATEGORY_FIELDS for field in fields):
+                raise ValueError(
+                    f"Invalid fields. Allowed fields: {VALID_SEARCH_CATEGORY_FIELDS}"
+                )
+            query["fields"] = ",".join(fields)
+        route = f"/api/v1/snaps/details/{snap_name}"
+        response = await self.store_client.get(
+            f"{self._raw_base_url}{route}", params=query
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def get_snap_info(self, snap_name: str, fields: list[str] | None = None):
+        query = {}
+        if fields is not None:
+            if not all(field in VALID_SNAP_INFO_FIELDS for field in fields):
+                raise ValueError(
+                    f"Invalid fields. Allowed fields: {VALID_SNAP_INFO_FIELDS}"
+                )
+            query["fields"] = ",".join(fields)
+        route = f"/v2/snaps/info/{snap_name}"
+        response = await self.store_client.get(
+            f"{self._raw_base_url}{route}", params=query
+        )
+        response.raise_for_status()
+        return InfoResponse.model_validate_json(response.content)
+
+    async def get_categories(
+        self, type: str | None = None, fields: list[str] | None = None
+    ) -> CategoryResponse:
+        query = {}
+        if fields is not None:
+            if not all(field in VALID_CATEGORY_FIELDS for field in fields):
+                raise ValueError(
+                    f"Invalid fields. Allowed fields: {VALID_CATEGORY_FIELDS}"
+                )
+            query["fields"] = ",".join(fields)
+        if type is not None:
+            query["type"] = type
+        route = "/snaps/categories"
+        response = await self.store_client.get(f"{self.base_url}{route}", params=query)
+        response.raise_for_status()
+        return CategoryResponse.model_validate_json(response.content)
+
+    async def get_category_by_name(
+        self, name: str, fields: list[str] | None = None
+    ) -> SingleCategoryResponse:
+        query = {}
+        if fields is not None:
+            if not all(field in VALID_CATEGORY_FIELDS for field in fields):
+                raise ValueError(
+                    f"Invalid fields. Allowed fields: {VALID_CATEGORY_FIELDS}"
+                )
+            query["fields"] = ",".join(fields)
+
+        route = f"/snaps/category/{name}"
+        response = await self.store_client.get(f"{self.base_url}{route}", params=query)
+        response.raise_for_status()
+        return SingleCategoryResponse.model_validate_json(response.content)
+
+    async def find(
+        self,
+        query: str | None = None,
+        fields: str | None = None,
+        name_startswith: str | None = None,
+        architecture: str | None = None,
+        common_id: str | None = None,
+        category: str | None = None,
+        channel: str | None = None,
+        confiement: str | None = None,
+        featured: bool = False,
+        private: bool = False,
+        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
+        """
+
+        route = "/snaps/find"
+        query_dict: dict = {
+            "q": query,
+            "name_startswith": name_startswith,
+            "architecture": architecture,
+            "common_id": common_id,
+            "category": category,
+            "channel": channel,
+            "confinement": confiement,
+            "featured": featured,
+            "private": private,
+            "publisher": publisher,
+        }
+        if fields is not None:
+            if not all(field in VALID_SEARCH_CATEGORY_FIELDS for field in fields):
+                bad_fields = [
+                    field
+                    for field in fields
+                    if field not in VALID_SEARCH_CATEGORY_FIELDS
+                ]
+                raise ValueError(
+                    f"Invalid fields: ({bad_fields}). Allowed fields: {VALID_SEARCH_CATEGORY_FIELDS}"
+                )
+            query_dict["fields"] = ",".join(fields)
+        extra_headers = headers or {}
+        query_dict = {
+            k: v for k, v in query_dict.items() if (v is not None) and (v != "")
+        }
+
+        # snap store expects "true" or "false" for boolean values
+        for key in ["featured", "private"]:
+            if key in query_dict:
+                query_dict[key] = str(query_dict[key]).lower()
+
+        response = await self.store_client.get(
+            f"{self.base_url}{route}", params=query_dict, headers=extra_headers
+        )
+        response.raise_for_status()
+        return SearchResponse.model_validate_json(response.content)
+
+    @retry.retry(Exception, tries=3, delay=2, backoff=2)
+    async def retry_get_snap_info(self, snap_name: str, fields: list[str]):
+        return await self.get_snap_info(snap_name=snap_name, fields=fields)
+
+    async def get_top_snaps_from_category(self, category: str) -> SearchResponse:
+        return await self.find(
+            category=category, fields=["title", "store-url", "summary"]
+        )

snap_python/schemas/changes.py

@@ -0,0 +1,51 @@
+from pydantic import AliasChoices, AwareDatetime, BaseModel, Field
+
+from snap_python.schemas.common import BaseErrorResult, BaseResponse
+
+
+class Task(BaseModel):
+    id: str
+    kind: str
+    summary: str
+    status: str
+    progress: dict
+    spawn_time: AwareDatetime = Field(
+        validation_alias=AliasChoices("spawn-time", "spawn_time"),
+        serialization_alias="spawn-time",
+    )
+    ready_time: AwareDatetime | None = Field(
+        validation_alias=AliasChoices("ready-time", "ready_time"),
+        serialization_alias="ready-time",
+        default=None,
+    )
+    data: dict | None = None
+
+
+class ChangesResult(BaseModel):
+    id: str
+    kind: str
+    summary: str
+    status: str
+    tasks: list[Task]
+    ready: bool
+    spawn_time: AwareDatetime = Field(
+        validation_alias=AliasChoices("spawn-time", "spawn_time"),
+        serialization_alias="spawn-time",
+    )
+    ready_time: AwareDatetime | None = Field(
+        validation_alias=AliasChoices("ready-time", "ready_time"),
+        serialization_alias="ready-time",
+        default=None,
+    )
+    err: str | None = None
+    data: dict | None = None
+
+
+class ChangesResponse(BaseResponse):
+    result: ChangesResult | BaseErrorResult
+
+    @property
+    def ready(self) -> bool:
+        if isinstance(self.result, BaseErrorResult):
+            return False
+        return self.result.ready

snap_python/schemas/common.py

@@ -0,0 +1,64 @@
+from enum import Enum
+from typing import Literal, Optional
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+
+class BaseErrorResult(BaseModel):
+    message: str
+
+
+class BaseResponse(BaseModel):
+    status_code: int = Field(
+        validation_alias=AliasChoices("status-code", "status_code"),
+        serialization_alias="status-code",
+    )
+    type: Literal["sync", "async", "error"]
+    status: str
+
+
+class SnapBaseVersion(Enum):
+    core16 = "core16"
+    core18 = "core18"
+    core20 = "core20"
+    core22 = "core22"
+    core24 = "core24"
+    bare = "bare"
+
+
+class SnapConfinement(Enum):
+    strict = "strict"
+    classic = "classic"
+    devmode = "devmode"
+    jailmode = "jailmode"
+
+
+class SnapApp(BaseModel):
+    snap: str | None = None
+    name: str
+    desktop_file: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("desktop-file", "desktop_file"),
+        serialization_alias="desktop-file",
+    )
+    daemon: str | None = None
+    enabled: bool | None = None
+    active: bool | None = None
+    common_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("common-id", "common_id"),
+        serialization_alias="common-id",
+    )
+
+
+class Media(BaseModel):
+    model_config = ConfigDict(extra="forbid", exclude_unset=True)
+
+    height: Optional[float] = None
+    type: str
+    url: str
+    width: Optional[float] = None
+
+
+class AsyncResponse(BaseResponse):
+    change: str

snap_python/schemas/snaps.py

@@ -0,0 +1,64 @@
+from pydantic import AliasChoices, AwareDatetime, BaseModel, ConfigDict, Field
+
+from snap_python.schemas.common import (
+    BaseResponse,
+    Media,
+    SnapApp,
+    SnapBaseVersion,
+    SnapConfinement,
+)
+
+
+class Snap(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    apps: list[SnapApp] = Field(default_factory=list)
+    base: SnapBaseVersion | None = None
+    channel: str
+    confinement: SnapConfinement
+    contact: str
+    description: str
+    developer: str
+    devmode: bool
+    icon: str | None = None
+    id: str
+    ignore_validation: bool = Field(
+        validation_alias=AliasChoices("ignore-validation", "ignore_validation"),
+        serialization_alias="ignore-validation",
+    )
+    install_date: AwareDatetime = Field(
+        validation_alias=AliasChoices("install-date", "install_date"),
+        serialization_alias="install-date",
+    )
+    installed_size: int = Field(
+        validation_alias=AliasChoices("installed-size", "installed_size"),
+        serialization_alias="installed-size",
+    )
+    jailmode: bool
+    license: str = "unset"
+    links: dict[str, list[str]] | None = None
+    media: list[Media] = Field(default_factory=list)
+    mounted_from: str = Field(
+        validation_alias=AliasChoices("mounted-from", "mounted_from"),
+        serialization_alias="mounted-from",
+    )
+    name: str
+    private: bool
+    publisher: dict[str, str]
+    revision: str
+    status: str
+    summary: str
+    title: str | None = None
+    tracking_channel: str = Field(
+        validation_alias=AliasChoices("tracking-channel", "tracking_channel"),
+        serialization_alias="tracking-channel",
+    )
+    type: str
+    version: str
+    website: str | None = None
+
+
+class SnapListResponse(BaseResponse):
+    result: list[Snap]
+
+    def __len__(self):
+        return len(self.result)

snap_python/schemas/store/categories.py

@@ -0,0 +1,42 @@
+# generated by datamodel-codegen:
+#   filename:  category_schema.json
+#   timestamp: 2024-09-17T00:34:03+00:00
+
+from typing import List, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+VALID_CATEGORY_FIELDS = ["name", "type", "title", "summary", "description", "media"]
+
+
+class Media(BaseModel):
+    model_config = ConfigDict(extra="forbid", exclude_unset=True)
+
+    height: Optional[float] = None
+    type: str
+    url: str
+    width: Optional[float] = None
+
+
+class Category(BaseModel):
+    model_config = ConfigDict(extra="forbid", exclude_unset=True)
+
+    description: Optional[str] = None
+    media: Optional[Media] = None
+    name: Optional[str] = None
+    summary: Optional[str] = None
+    title: Optional[str] = None
+    type: Optional[str] = None
+    featured: Optional[bool] = None
+
+
+class CategoryResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid", exclude_unset=True)
+
+    categories: Optional[List[Category]] = None
+
+
+class SingleCategoryResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid", exclude_unset=True)
+
+    category: Category