Add addon availability API

Author: mdegat01

aiohasupervisor/exceptions.py

@@ -44,3 +44,47 @@ class SupervisorServiceUnavailableError(SupervisorError):
 
 class SupervisorResponseError(SupervisorError):
     """Unusable response received from Supervisor with the wrong type or encoding."""
+
+
+class AddonNotSupportedError(SupervisorError):
+    """Addon is not supported on this system."""
+
+
+class AddonNotSupportedArchitectureError(AddonNotSupportedError):
+    """Addon is not supported on this system due to its architecture."""
+
+    def __init__(
+        self, addon: str, architectures: str, job_id: str | None = None
+    ) -> None:
+        """Initialize exception."""
+        super().__init__(
+            f"Add-on {addon} not supported on this platform, "
+            f"supported architectures: {architectures}",
+            job_id,
+        )
+
+
+class AddonNotSupportedMachineTypeError(AddonNotSupportedError):
+    """Addon is not supported on this system due to its machine type."""
+
+    def __init__(
+        self, addon: str, machine_types: str, job_id: str | None = None
+    ) -> None:
+        """Initialize exception."""
+        super().__init__(
+            f"Add-on {addon} not supported on this machine, "
+            f"supported machine types: {machine_types}",
+            job_id,
+        )
+
+
+class AddonNotSupportedHomeAssistantVersionError(AddonNotSupportedError):
+    """Addon is not supported on this system due to its version of Home Assistant."""
+
+    def __init__(self, addon: str, version: str, job_id: str | None = None) -> None:
+        """Initialize exception."""
+        super().__init__(
+            f"Add-on {addon} not supported on this system, "
+            f"requires Home Assistant version {version} or greater",
+            job_id,
+        )

aiohasupervisor/store.py

@@ -1,9 +1,17 @@
 """Store client for supervisor."""
 
+import re
 from typing import Any
 
 from .client import _SupervisorComponentClient
 from .const import ResponseType
+from .exceptions import (
+    AddonNotSupportedArchitectureError,
+    AddonNotSupportedError,
+    AddonNotSupportedHomeAssistantVersionError,
+    AddonNotSupportedMachineTypeError,
+    SupervisorBadRequestError,
+)
 from .models.addons import (
     Repository,
     StoreAddon,
@@ -15,6 +23,19 @@
     StoreInfo,
 )
 
+RE_ADDON_UNAVAILABLE_ARCHITECTURE = re.compile(
+    r"^Add\-on (?P<addon>\w+) not supported on this platform, "
+    r"supported architectures: (?P<architectures>.*)$"
+)
+RE_ADDON_UNAVAILABLE_MACHINE_TYPE = re.compile(
+    r"^Add\-on (?P<addon>\w+) not supported on this machine, "
+    r"supported machine types: (?P<machine_types>.*)$"
+)
+RE_ADDON_UNAVAILABLE_HOME_ASSISTANT = re.compile(
+    r"^Add\-on (?P<addon>\w+) not supported on this system, "
+    r"requires Home Assistant version (?P<version>\S+) or greater$"
+)
+
 
 class StoreClient(_SupervisorComponentClient):
     """Handles store access in Supervisor."""
@@ -48,6 +69,37 @@ async def addon_documentation(self, addon: str) -> str:
         )
         return result.data
 
+    async def addon_availability(self, addon: str) -> None:
+        """Determine if latest version of addon can be installed on this system.
+
+        No return means it can be. If not, raises one of the following errors:
+        - AddonUnavailableHomeAssistantVersionError
+        - AddonUnavailableArchitectureError
+        - AddonUnavailableMachineTypeError
+
+        If Supervisor adds a new reason an add-on can be restricted from being
+        installed on some systems in the future, older versions of this client
+        will raise the generic AddonNotSupportedError for that reason.
+        """
+        try:
+            await self._client.get(
+                f"store/addons/{addon}/availability", response_type=ResponseType.NONE
+            )
+        except SupervisorBadRequestError as err:
+            if match := RE_ADDON_UNAVAILABLE_ARCHITECTURE.match(str(err)):
+                raise AddonNotSupportedArchitectureError(
+                    match.group("addon"), match.group("architectures"), err.job_id
+                ) from None
+            if match := RE_ADDON_UNAVAILABLE_HOME_ASSISTANT.match(str(err)):
+                raise AddonNotSupportedHomeAssistantVersionError(
+                    match.group("addon"), match.group("version"), err.job_id
+                ) from None
+            if match := RE_ADDON_UNAVAILABLE_MACHINE_TYPE.match(str(err)):
+                raise AddonNotSupportedMachineTypeError(
+                    match.group("addon"), match.group("machine_types"), err.job_id
+                ) from None
+            raise AddonNotSupportedError(str(err), err.job_id) from None
+
     async def install_addon(
         self, addon: str, options: StoreAddonInstall | None = None
     ) -> None:

tests/test_store.py

@@ -5,6 +5,12 @@
 from yarl import URL
 
 from aiohasupervisor import SupervisorClient
+from aiohasupervisor.exceptions import (
+    AddonNotSupportedArchitectureError,
+    AddonNotSupportedError,
+    AddonNotSupportedHomeAssistantVersionError,
+    AddonNotSupportedMachineTypeError,
+)
 from aiohasupervisor.models import StoreAddonUpdate, StoreAddRepository
 from aiohasupervisor.models.addons import StoreAddonInstall
 
@@ -169,6 +175,59 @@ async def test_store_addon_update(
     )
 
 
+async def test_store_addon_availability(
+    responses: aioresponses, supervisor_client: SupervisorClient
+) -> None:
+    """Test store addon availability API."""
+    responses.get(
+        f"{SUPERVISOR_URL}/store/addons/core_mosquitto/availability", status=200
+    )
+
+    assert (await supervisor_client.store.addon_availability("core_mosquitto")) is None
+
+
+@pytest.mark.parametrize(
+    ("error_msg", "exc_type"),
+    [
+        (
+            "Add-on core_mosquitto not supported on this platform, "
+            "supported architectures: i386",
+            AddonNotSupportedArchitectureError,
+        ),
+        (
+            "Add-on core_mosquitto not supported on this machine, "
+            "supported machine types: odroid-n2",
+            AddonNotSupportedMachineTypeError,
+        ),
+        (
+            "Add-on core_mosquitto not supported on this system, "
+            "requires Home Assistant version 2023.1.1 or greater",
+            AddonNotSupportedHomeAssistantVersionError,
+        ),
+        (
+            "Add-on core_mosquitto not supported on this system, "
+            "requires <something new> to be <something else>",
+            AddonNotSupportedError,
+        ),
+    ],
+)
+async def test_store_addon_availability_error(
+    responses: aioresponses,
+    supervisor_client: SupervisorClient,
+    error_msg: str,
+    exc_type: type[AddonNotSupportedError],
+) -> None:
+    """Test store addon availability API error."""
+    responses.get(
+        f"{SUPERVISOR_URL}/store/addons/core_mosquitto/availability",
+        status=400,
+        body=f'{{"result": "error", "message": "{error_msg}"}}',
+    )
+
+    with pytest.raises(exc_type):
+        await supervisor_client.store.addon_availability("core_mosquitto")
+
+
 async def test_store_reload(
     responses: aioresponses, supervisor_client: SupervisorClient
 ) -> None: