Rename quirk IDs to exposed features

- `exposes_features` is used by the device.
- `exposed_features` is used by the MatchRules to create discovery matches.

Author: TheJulianJES

tests/test_cluster_handlers.py

@@ -525,10 +525,10 @@ async def test_out_cluster_handler_config(
 def test_cluster_handler_registry() -> None:
     """Test ZIGBEE cluster handler Registry."""
 
-    # get all quirk ID from zigpy quirks registry
-    cluster_quirk_id_map: dict[int, set[str | None]] = {}
+    # get all exposed features from zigpy quirks registry
+    cluster_exposed_feature_map: dict[int, set[str | None]] = {}
     for cluster_id in CLUSTERS_BY_ID:
-        cluster_quirk_id_map[cluster_id] = {None}
+        cluster_exposed_feature_map[cluster_id] = {None}
 
     # loop over custom clusters in v2 quirks registry
     for quirks in _DEVICE_REGISTRY.registry_v2.values():
@@ -538,14 +538,14 @@ def test_cluster_handler_registry() -> None:
                 rm.add for rm in quirk_reg_entry.replaces_metadata
             }
             for metadata in all_metadata:
-                cluster_quirk_id_map[metadata.cluster.cluster_id] = {None}
+                cluster_exposed_feature_map[metadata.cluster.cluster_id] = {None}
 
     # loop over custom clusters in v1 quirks registry
     for manufacturer in _DEVICE_REGISTRY.registry_v1.values():
         for model_quirk_list in manufacturer.values():
             for quirk in model_quirk_list:
                 qid: set[str] | str = getattr(quirk, ATTR_QUIRK_ID, set())
-                quirk_ids: set[str] = {qid} if isinstance(qid, str) else set(qid)
+                exposed_features: set[str] = {qid} if isinstance(qid, str) else set(qid)
 
                 device_description: dict[str, dict[str, Any]] = getattr(
                     quirk, "replacement", None
@@ -560,9 +560,9 @@ def test_cluster_handler_registry() -> None:
                     for cluster_id in cluster_ids:
                         if not isinstance(cluster_id, int):
                             cluster_id = cluster_id.cluster_id
-                        if cluster_id not in cluster_quirk_id_map:
-                            cluster_quirk_id_map[cluster_id] = {None}
-                        cluster_quirk_id_map[cluster_id].update(quirk_ids)
+                        if cluster_id not in cluster_exposed_feature_map:
+                            cluster_exposed_feature_map[cluster_id] = {None}
+                        cluster_exposed_feature_map[cluster_id].update(exposed_features)
 
     for (
         cluster_id,
@@ -573,16 +573,17 @@ def test_cluster_handler_registry() -> None:
         assert 0 <= cluster_id <= 0xFFFF
 
         # test all registered clusters are used in zigpy or quirks
-        assert cluster_id in cluster_quirk_id_map
+        assert cluster_id in cluster_exposed_feature_map
 
         assert isinstance(cluster_handler_classes, dict)
-        for quirk_id, cluster_handler in cluster_handler_classes.items():
-            # test cluster handler is not quirk specific or only has a single quirk ID
-            assert quirk_id is None or isinstance(quirk_id, str)
+        for ch_exposed_feature, cluster_handler in cluster_handler_classes.items():
+            # test cluster handler is not quirk specific
+            # or only has a single exposed feature
+            assert ch_exposed_feature is None or isinstance(ch_exposed_feature, str)
             assert issubclass(cluster_handler, ClusterHandler)
 
-            # test cluster handler quirk ID is used in quirk with that cluster
-            assert quirk_id in cluster_quirk_id_map[cluster_id]
+            # test cluster handler exposed feature is used in quirk with that cluster
+            assert ch_exposed_feature in cluster_exposed_feature_map[cluster_id]
 
 
 def test_epch_unclaimed_cluster_handlers(cluster_handler) -> None:
@@ -820,7 +821,7 @@ async def test_ep_cluster_handlers_configure(cluster_handler) -> None:
     )
     zha_dev = mock.MagicMock(spec=Device)
     zha_dev.unique_id = "00:11:22:33:44:55:66:77"
-    type(zha_dev).quirk_id = mock.PropertyMock(return_value=set())
+    type(zha_dev).exposes_features = mock.PropertyMock(return_value=set())
     endpoint = Endpoint.new(endpoint_mock, zha_dev)
 
     claimed = {ch_1.id: ch_1, ch_2.id: ch_2, ch_3.id: ch_3}
@@ -1023,7 +1024,7 @@ class TestZigbeeClusterHandler(ClusterHandler):
     )
 
     mock_zha_device = mock.AsyncMock(spec=Device)
-    mock_zha_device.quirk_id = set()
+    mock_zha_device.exposes_features = set()
     mock_zha_device.unique_id = "aa:bb:cc:dd:11:22:33:44"
 
     zha_endpoint = Endpoint(zigpy_ep, mock_zha_device)
@@ -1068,14 +1069,14 @@ class TestZigbeeClusterHandler(ColorClusterHandler):
     )
 
     mock_zha_device = mock.AsyncMock(spec=Device)
-    mock_zha_device.quirk_id = set()
+    mock_zha_device.exposes_features = set()
     mock_zha_device.unique_id = "aa:bb:cc:dd:11:22:33:44"
 
     zha_endpoint = Endpoint(zigpy_ep, mock_zha_device)
 
     with patch.dict(
         CLUSTER_HANDLER_REGISTRY[cluster.cluster_id],
-        {"__test_quirk_id": TestZigbeeClusterHandler},
+        {"__exposed_feature_id": TestZigbeeClusterHandler},
     ):
         zha_endpoint.add_all_cluster_handlers()
 
@@ -1085,10 +1086,10 @@ class TestZigbeeClusterHandler(ColorClusterHandler):
     )
 
 
-async def test_quirk_id_cluster_handler(
+async def test_exposed_feature_cluster_handler(
     zha_gateway: Gateway,
 ) -> None:  # pylint: disable=unused-argument
-    """Test setting up a cluster handler that matches a standard cluster."""
+    """Test setting up a cluster handler with an exposed feature."""
 
     class TestZigbeeClusterHandler(ColorClusterHandler):
         """Test cluster handler that matches a standard cluster."""
@@ -1109,12 +1110,12 @@ class TestZigbeeClusterHandler(ColorClusterHandler):
 
     mock_zha_device = mock.AsyncMock(spec=Device)
     mock_zha_device.unique_id = "aa:bb:cc:dd:11:22:33:44"
-    mock_zha_device.quirk_id = {"__test_quirk_id"}
+    mock_zha_device.exposes_features = {"__exposed_feature_id"}
     zha_endpoint = Endpoint(zigpy_ep, mock_zha_device)
 
     with patch.dict(
         CLUSTER_HANDLER_REGISTRY[cluster.cluster_id],
-        {"__test_quirk_id": TestZigbeeClusterHandler},
+        {"__exposed_feature_id": TestZigbeeClusterHandler},
     ):
         zha_endpoint.add_all_cluster_handlers()
 

tests/test_registries.py

@@ -25,7 +25,7 @@
 MANUFACTURER = "mock manufacturer"
 MODEL = "mock model"
 QUIRK_CLASS = "mock.test.quirk.class"
-QUIRK_ID = "quirk_id"
+EXPOSED_FEATURE = "EXPOSED_FEATURE_ID"
 
 
 @pytest.fixture
@@ -97,14 +97,19 @@ def cluster_handlers(cluster_handler):
             MatchRule(models="no match", aux_cluster_handlers="aux_cluster_handler"),
             False,
         ),
-        (MatchRule(quirk_ids=QUIRK_ID), True),
-        (MatchRule(quirk_ids="no match"), False),
+        (MatchRule(exposed_features=EXPOSED_FEATURE), True),
+        (MatchRule(exposed_features="no match"), False),
         (
-            MatchRule(quirk_ids=QUIRK_ID, aux_cluster_handlers="aux_cluster_handler"),
+            MatchRule(
+                exposed_features=EXPOSED_FEATURE,
+                aux_cluster_handlers="aux_cluster_handler",
+            ),
             True,
         ),
         (
-            MatchRule(quirk_ids="no match", aux_cluster_handlers="aux_cluster_handler"),
+            MatchRule(
+                exposed_features="no match", aux_cluster_handlers="aux_cluster_handler"
+            ),
             False,
         ),
         # match everything
@@ -114,7 +119,7 @@ def cluster_handlers(cluster_handler):
                 cluster_handler_names={"on_off", "level"},
                 manufacturers=MANUFACTURER,
                 models=MODEL,
-                quirk_ids=QUIRK_ID,
+                exposed_features=EXPOSED_FEATURE,
             ),
             True,
         ),
@@ -167,39 +172,41 @@ def cluster_handlers(cluster_handler):
         (
             MatchRule(
                 cluster_handler_names="on_off",
-                quirk_ids={"random quirk", QUIRK_ID},
+                exposed_features={"random quirk", EXPOSED_FEATURE},
             ),
             True,
         ),
         (
             MatchRule(
                 cluster_handler_names="on_off",
-                quirk_ids={"random quirk", "another quirk"},
+                exposed_features={"random quirk", "another quirk"},
             ),
             False,
         ),
         (
             MatchRule(
-                cluster_handler_names="on_off", quirk_ids=lambda x: x == QUIRK_ID
+                cluster_handler_names="on_off",
+                exposed_features=lambda x: x == EXPOSED_FEATURE,
             ),
             True,
         ),
         (
             MatchRule(
-                cluster_handler_names="on_off", quirk_ids=lambda x: x != QUIRK_ID
+                cluster_handler_names="on_off",
+                exposed_features=lambda x: x != EXPOSED_FEATURE,
             ),
             False,
         ),
         (
-            MatchRule(cluster_handler_names="on_off", quirk_ids=QUIRK_ID),
+            MatchRule(cluster_handler_names="on_off", exposed_features=EXPOSED_FEATURE),
             True,
         ),
     ],
 )
 def test_registry_matching(rule, matched, cluster_handlers) -> None:
     """Test strict rule matching."""
     assert (
-        rule.strict_matched(MANUFACTURER, MODEL, cluster_handlers, {QUIRK_ID})
+        rule.strict_matched(MANUFACTURER, MODEL, cluster_handlers, {EXPOSED_FEATURE})
         is matched
     )
 
@@ -288,16 +295,16 @@ def test_registry_matching(rule, matched, cluster_handlers) -> None:
         (MatchRule(manufacturers=MANUFACTURER), True),
         (MatchRule(models=MODEL), True),
         (MatchRule(models="no match"), False),
-        (MatchRule(quirk_ids=QUIRK_ID), True),
-        (MatchRule(quirk_ids="no match"), False),
+        (MatchRule(exposed_features=EXPOSED_FEATURE), True),
+        (MatchRule(exposed_features="no match"), False),
         # match everything
         (
             MatchRule(
                 generic_ids={"cluster_handler_0x0006", "cluster_handler_0x0008"},
                 cluster_handler_names={"on_off", "level"},
                 manufacturers=MANUFACTURER,
                 models=MODEL,
-                quirk_ids=QUIRK_ID,
+                exposed_features=EXPOSED_FEATURE,
             ),
             True,
         ),
@@ -306,7 +313,8 @@ def test_registry_matching(rule, matched, cluster_handlers) -> None:
 def test_registry_loose_matching(rule, matched, cluster_handlers) -> None:
     """Test loose rule matching."""
     assert (
-        rule.loose_matched(MANUFACTURER, MODEL, cluster_handlers, {QUIRK_ID}) is matched
+        rule.loose_matched(MANUFACTURER, MODEL, cluster_handlers, {EXPOSED_FEATURE})
+        is matched
     )
 
 
@@ -370,12 +378,12 @@ def entity_registry():
 
 
 @pytest.mark.parametrize(
-    ("manufacturer", "model", "quirk_id", "match_name"),
+    ("manufacturer", "model", "exposes_features", "match_name"),
     [
         ("random manufacturer", "random model", "random.class", "OnOff"),
         ("random manufacturer", MODEL, "random.class", "OnOffModel"),
         (MANUFACTURER, "random model", "random.class", "OnOffManufacturer"),
-        ("random manufacturer", "random model", QUIRK_ID, "OnOffQuirk"),
+        ("random manufacturer", "random model", EXPOSED_FEATURE, "OnOffQuirk"),
         (MANUFACTURER, MODEL, "random.class", "OnOffModelManufacturer"),
         (MANUFACTURER, "some model", "random.class", "OnOffMultimodel"),
     ],
@@ -385,7 +393,7 @@ def test_weighted_match(
     entity_registry: PlatformEntityRegistry,
     manufacturer,
     model,
-    quirk_id,
+    exposes_features,
     match_name,
 ) -> None:
     """Test weightedd match."""
@@ -426,7 +434,7 @@ class OnOffModelManufacturer:  # pylint: disable=unused-variable
         """OnOff model and manufacturer cluster handler."""
 
     @entity_registry.strict_match(
-        s.component, cluster_handler_names="on_off", quirk_ids=QUIRK_ID
+        s.component, cluster_handler_names="on_off", exposed_features=EXPOSED_FEATURE
     )
     class OnOffQuirk:  # pylint: disable=unused-variable
         """OnOff quirk cluster handler."""
@@ -435,7 +443,7 @@ class OnOffQuirk:  # pylint: disable=unused-variable
     ch_level = cluster_handler("level", 8)
 
     match, claimed = entity_registry.get_entity(
-        s.component, manufacturer, model, [ch_on_off, ch_level], {quirk_id}
+        s.component, manufacturer, model, [ch_on_off, ch_level], {exposes_features}
     )
 
     assert match.__name__ == match_name
@@ -463,7 +471,7 @@ class SmartEnergySensor2:
         "manufacturer",
         "model",
         cluster_handlers=[ch_se, ch_illuminati],
-        quirk_ids={"quirk_id"},
+        exposes_features={"exposed_feature_id"},
     )
 
     assert s.binary_sensor in match
@@ -493,7 +501,7 @@ class SmartEnergySensor3:
         "manufacturer",
         "model",
         cluster_handlers={ch_se, ch_illuminati},
-        quirk_ids={"quirk_id"},
+        exposes_features={"exposed_feature_id"},
     )
 
     assert s.binary_sensor in match
@@ -541,21 +549,23 @@ def quirk_class_validator(value):
                 quirk_class_validator(v)
             return
 
-        if value not in all_quirk_ids:
-            raise ValueError(f"Quirk ID '{value}' does not exist.")
+        if value not in all_exposed_features:
+            raise ValueError(f"Exposed feature '{value}' does not exist.")
 
     # get all quirk ID from zigpy quirks registry
-    all_quirk_ids: set[str] = set()
+    all_exposed_features: set[str] = set()
     for manufacturer in zigpy_quirks._DEVICE_REGISTRY.registry_v1.values():
         for model_quirk_list in manufacturer.values():
             for quirk in model_quirk_list:
                 qid: set[str] | str = getattr(quirk, ATTR_QUIRK_ID, set())
-                device_quirk_ids: set[str] = {qid} if isinstance(qid, str) else set(qid)
-                all_quirk_ids.update(device_quirk_ids)
+                device_exposed_features: set[str] = (
+                    {qid} if isinstance(qid, str) else set(qid)
+                )
+                all_exposed_features.update(device_exposed_features)
 
     # validate all quirk IDs used in component match rules
     for rule, _ in iter_all_rules():
-        quirk_class_validator(rule.quirk_ids)
+        quirk_class_validator(rule.exposed_features)
 
 
 def test_entity_names() -> None:

zha/application/discovery.py

@@ -408,7 +408,7 @@ def discover_by_device_type(
                 endpoint.device.manufacturer,
                 endpoint.device.model,
                 cluster_handlers,
-                endpoint.device.quirk_ids,
+                endpoint.device.exposes_features,
             )
             if entity_class is None:
                 return
@@ -437,7 +437,7 @@ def probe_single_cluster(
             endpoint.device.manufacturer,
             endpoint.device.model,
             [cluster_handler],
-            endpoint.device.quirk_ids,
+            endpoint.device.exposes_features,
         )
         if entity_class is None:
             return
@@ -500,15 +500,16 @@ def handle_on_off_output_cluster_exception(
                 cluster_id, {None: ClusterHandler}
             )
 
-            # get first quirk id from device that matches a registered cluster handler
-            cluster_quirk_id: str | None = None
-            for qid in endpoint.device.quirk_ids:
-                if qid in cluster_handler_classes:
-                    cluster_quirk_id = qid
+            # get first exposed feature from device
+            # that matches a registered cluster handler
+            cluster_exposed_feature: str | None = None
+            for exposed_features in endpoint.device.exposes_features:
+                if exposed_features in cluster_handler_classes:
+                    cluster_exposed_feature = exposed_features
                     break
 
             cluster_handler_class = cluster_handler_classes.get(
-                cluster_quirk_id, ClusterHandler
+                cluster_exposed_feature, ClusterHandler
             )
 
             cluster_handler = cluster_handler_class(cluster, endpoint)
@@ -540,14 +541,14 @@ def discover_multi_entities(
                 device.manufacturer,
                 device.model,
                 cluster_handlers,
-                device.quirk_ids,
+                device.exposes_features,
             )
         else:
             matches, claimed = PLATFORM_ENTITIES.get_multi_entity(
                 device.manufacturer,
                 device.model,
                 endpoint.unclaimed_cluster_handlers(),
-                device.quirk_ids,
+                device.exposes_features,
             )
 
         endpoint.claim_cluster_handlers(claimed)