Add model mapper

Author: CoMPaTech

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.6] - 2025-10-11
+
+### Added
+
+- Model name (devmodel) to SKU (product code) mapper for model_id and model_name matching in Home Assistant
+
 ## [0.5.5] - 2025-10-05
 
 ### Changed

airos/exceptions.py

@@ -43,3 +43,7 @@ class AirOSNotSupportedError(AirOSException):
 
 class AirOSUrlNotFoundError(AirOSException):
     """Raised when url not available for device."""
+
+
+class AirOSMultipleMatchesFoundException(AirOSException):
+    """Raised when multiple devices found for lookup."""

airos/model_map.py

@@ -0,0 +1,117 @@
+"""List of airOS products."""
+
+from .exceptions import AirOSMultipleMatchesFoundException
+
+MODELS: dict[str, str] = {
+    "Wave MLO5": "Wave-MLO5",
+    "airMAX Rocket Prism 5AC": "RP-5AC-Gen2",
+    "airFiber 5XHD": "AF-5XHD",
+    "airMAX Lite AP GPS": "LAP-GPS",
+    "airMAX PowerBeam 5AC": "PBE-5AC-Gen2",
+    "airMAX PowerBeam 5AC ISO": "PBE-5AC-ISO-Gen2",
+    "airMAX PowerBeam 5AC 620": "PBE-5AC-620",
+    "airMAX LiteBeam 5AC": "LBE-5AC-GEN2",
+    "airMAX LiteBeam 5AC Long-Range": "LBE-5AC-LR",
+    "airMAX NanoBeam 5AC": "NBE-5AC-GEN2",
+    "airMAX NanoStation 5AC": "NS-5AC",
+    "airMAX NanoStation 5AC Loco": "Loco5AC",
+    "LTU Rocket": "LTU-Rocket",
+    "LTU Instant (5-pack)": "LTU-Instant",
+    "LTU Pro": "LTU-PRO",
+    "LTU Long-Range": "LTU-LR",
+    "LTU Extreme-Range": "LTU-XR",
+    "airMAX NanoBeam 2AC": "NBE-2AC-13",
+    "airMAX PowerBeam 2AC 400": "PBE-2AC-400",
+    "airMAX Rocket AC Lite": "R5AC-LITE",
+    "airMAX LiteBeam M5": "LBE-M5-23",
+    "airMAX PowerBeam 5AC 500": "PBE-5AC-500",
+    "airMAX PrismStation 5AC": "PS-5AC",
+    "airMAX IsoStation 5AC": "IS-5AC",
+    "airMAX Lite AP": "LAP-120",
+    "airMAX PowerBeam M5 400": "PBE-M5-400",
+    "airMAX PowerBeam M5 300 ISO": "PBE-M5-300-ISO",
+    "airMAX PowerBeam M5 300": "PBE-M5-300",
+    "airMAX PowerBeam M2 400": "PBE-M2-400",
+    "airMAX Bullet AC": "B-DB-AC",
+    "airMAX Bullet AC IP67": "BulletAC-IP67",
+    "airMAX Bullet M2": "BulletM2-HP",
+    "airMAX IsoStation M5": "IS-M5",
+    "airMAX NanoStation M5": "NSM5",
+    "airMAX NanoStation M5 loco": "LocoM5",
+    "airMAX NanoStation M2 loco": "LocoM2",
+    "UISP Horn": "UISP-Horn",
+    "UISP Dish": "UISP-Dish",
+    "UISP Dish Mini": "UISP-Dish-Mini",
+    "airMAX AC 5 GHz, 31 dBi RocketDish": "RD-5G31-AC",
+    "airMAX 5 GHz, 30 dBi RocketDish LW": "RD-5G30-LW",
+    "airMAX AC 5 GHz, 30/34 dBi RocketDish": "RD-5G",
+    "airPRISM 3x30° HD Sector": "AP-5AC-90-HD",
+    "airMAX 5 GHz, 16/17 dBi Sector": "AM-5G1",
+    "airMAX PrismStation Horn": "Horn-5",
+    "airMAX 5 GHz, 10 dBi Omni": "AMO-5G10",
+    "airMAX 5 GHz, 13 dBi, Omni": "AMO-5G13",
+    "airMAX Sector 2.4 GHz Titanium": "AM-V2G-Ti",
+    "airMAX AC 5 GHz, 21 dBi, 60º Sector": "AM-5AC21-60",
+    "airMAX AC 5 GHz, 22 dBi, 45º Sector": "AM-5AC22-45",
+    "airMAX 2.4 GHz, 16 dBi, 90º Sector": "AM-2G16-90",
+    "airMAX 900 MHz, 13 dBi, 120º Sector": "AM-9M13-120",
+    "airMAX 900 MHz, 16 dBi Yagi": "AMY-9M16x2",
+    "airMAX NanoBeam M5": "NBE-M5-16",
+    "airMAX Rocket Prism 2AC": "R2AC-PRISM",
+    "airFiber 5 Mid-Band": "AF-5",
+    "airFiber 5 High-Band": "AF-5U",
+    "airFiber 24": "AF-24",
+    "airFiber 24 Hi-Density": "AF-24HD",
+    "airFiber 2X": "AF-2X",
+    "airFiber 11": "AF-11",
+    "airFiber 11 Low-Band Backhaul Radio with Dish Antenna": "AF11-Complete-LB",
+    "airFiber 11 High-Band Backhaul Radio with Dish Antenna": "AF11-Complete-HB",
+    "airMAX LiteBeam 5AC Extreme-Range": "LBE-5AC-XR",
+    "airMAX PowerBeam M5 400 ISO": "PBE-M5-400-ISO",
+    "airMAX NanoStation M2": "NSM2",
+    "airFiber X 5 GHz, 23 dBi, Slant 45": "AF-5G23-S45",
+    "airFiber X 5 GHz, 30 dBi, Slant 45": "AF-5G30-S45",
+    "airFiber X 5 GHz, 34 dBi, Slant 45": "AF-5G34-S45",
+    "airMAX 5 GHz, 19/20 dBi Sector": "AM-5G2",
+    "airMAX 2.4 GHz, 10 dBi Omni": "AMO-2G10",
+    "airMAX 2.4 GHz, 15 dBi, 120º Sector": "AM-2G15-120",
+}
+
+
+class UispAirOSProductMapper:
+    """Utility class to map product model names to SKUs and vice versa."""
+
+    def __init__(self) -> None:
+        """Provide reversed map for SKUs."""
+        self._SKUS = {v: k for k, v in MODELS.items()}
+
+    def get_sku_by_devmodel(self, devmodel: str) -> str:
+        """Retrieves the SKU for a given device model name."""
+        if devmodel in MODELS:
+            return MODELS[devmodel]
+
+        match_key = None
+        matches_found = 0
+
+        lower_devmodel = devmodel.lower()
+
+        for model_name in MODELS:
+            if lower_devmodel in model_name.lower():
+                match_key = model_name
+                matches_found += 1
+
+        if match_key is None or matches_found == 0:
+            raise KeyError(f"No product found for devmodel: {devmodel}")
+
+        if match_key and matches_found == 1:
+            return MODELS[match_key]
+
+        raise AirOSMultipleMatchesFoundException(
+            f"Partial model '{devmodel}' matched multiple ({matches_found}) products."
+        )
+
+    def get_devmodel_by_sku(self, sku: str) -> str:
+        """Retrieves the full device model name for an exact SKU match."""
+        if sku in self._SKUS:
+            return self._SKUS[sku]
+        raise KeyError(f"No product found for SKU: {sku}")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "airos"
-version         = "0.5.5"
+version         = "0.5.6"
 license         = "MIT"
 description     = "Ubiquiti airOS module(s) for Python 3."
 readme          = "README.md"
@@ -341,12 +341,6 @@ enable = [
   #"useless-suppression",  # temporarily every now and then to clean them up
   "use-symbolic-message-instead",
 ]
-per-file-ignores = [
-  # redefined-outer-name: Tests reference fixtures in the test function
-  # use-implicit-booleaness-not-comparison: Tests need to validate that a list
-  # or a dict is returned
-  "/tests/:redefined-outer-name,use-implicit-booleaness-not-comparison",
-]
 
 [tool.pylint.REPORTS]
 score = false

tests/test_model_map.py

@@ -0,0 +1,59 @@
+"""Unit tests for the UispAirOSProductMapper class in model_map.py."""
+
+import re
+
+import pytest
+
+from airos.exceptions import AirOSMultipleMatchesFoundException
+from airos.model_map import UispAirOSProductMapper
+
+
+class TestUispAirOSProductMapper:
+    """Unit tests for the UispAirOSProductMapper class."""
+
+    mapper = UispAirOSProductMapper()
+
+    def test_get_sku_by_devmodel_exact_match(self):
+        """Test to return the correct SKU for a full, exact model name."""
+        sku = self.mapper.get_sku_by_devmodel("Wave MLO5")
+        assert sku == "Wave-MLO5"
+
+    def test_get_sku_by_devmodel_partial_single_match(self):
+        """Test to return the correct SKU for a partial model name that matches only one product."""
+        sku = self.mapper.get_sku_by_devmodel("NanoBeam 5AC")
+        assert sku == "NBE-5AC-GEN2"
+
+    def test_get_sku_by_devmodel_case_insensitivity(self):
+        """Test to work regardless of the case of the input model name."""
+        sku = self.mapper.get_sku_by_devmodel("nanostation 5ac loco")
+        assert sku == "Loco5AC"
+
+    def test_get_sku_by_devmodel_not_found_raises_keyerror(self):
+        """Test to raise KeyError when no match (exact or partial) is found."""
+        with pytest.raises(
+            KeyError, match="No product found for devmodel: NonExistent"
+        ):
+            self.mapper.get_sku_by_devmodel("NonExistent Model 123")
+
+    def test_get_sku_by_devmodel_multiple_matches_raises_exception_dynamic(self):
+        """Test to raise AirOSMultipleMatchesFoundException when partial match is ambiguous."""
+        with pytest.raises(AirOSMultipleMatchesFoundException) as excinfo:
+            self.mapper.get_sku_by_devmodel("Rocket")
+
+        exception_message = str(excinfo.value)
+        expected_matches = 7
+
+        match = re.search(r"matched multiple \((\d+)\) products", exception_message)
+        assert match is not None
+        actual_matches_int = int(match.group(1))
+        assert actual_matches_int == expected_matches
+
+    def test_get_devmodel_by_sku_exact_match(self):
+        """Test to return the full model name for an exact SKU."""
+        model = self.mapper.get_devmodel_by_sku("Loco5AC")
+        assert model == "airMAX NanoStation 5AC Loco"
+
+    def test_get_devmodel_by_sku_not_found_raises_keyerror(self):
+        """Test to raise KeyError when the exact SKU is not found."""
+        with pytest.raises(KeyError, match="No product found for SKU: FAKE-SKU"):
+            self.mapper.get_devmodel_by_sku("FAKE-SKU")