Improve Device helpers (#1932)

Small changes to the helpers to have better naming and more aligned to
what Home Assistant needs

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: iMicknl

docs/device-control.md

@@ -45,12 +45,20 @@ from pyoverkiz.enums import OverkizState
 devices = await client.get_devices()
 device = devices[0]
 
-# Get the value of the first matching state
-slats_orientation = device.get_state_value([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.CORE_SLATE_ORIENTATION])
+# Get the value of a single state
+slats_orientation = device.get_state_value(OverkizState.CORE_SLATS_ORIENTATION)
 print(f"Orientation: {slats_orientation}")
 
-# Check if a state has a non-None value
-if device.has_state_value([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.CORE_SLATE_ORIENTATION]):
+# Get the value of the first matching state from a list (fallback pattern)
+slats_orientation = device.select_first_state_value([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.CORE_SLATE_ORIENTATION])
+print(f"Orientation: {slats_orientation}")
+
+# Check if a single state has a non-None value
+if device.has_state_value(OverkizState.CORE_SLATS_ORIENTATION):
+    print("Device has a slats orientation")
+
+# Check if any of the states have non-None values
+if device.has_any_state_value([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.CORE_SLATE_ORIENTATION]):
     print("Device has a slats orientation")
 ```
 
@@ -60,8 +68,14 @@ if device.has_state_value([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.COR
 devices = await client.get_devices()
 device = devices[0]
 
-# Get the state definition for querying type, valid values, etc.
-state_def = device.get_state_definition([OverkizState.CORE_OPEN_CLOSED, OverkizState.CORE_SLATS_OPEN_CLOSED])
+# Get the state definition for a single state
+state_def = device.get_state_definition(OverkizState.CORE_OPEN_CLOSED)
+if state_def:
+    print(f"Type: {state_def.type}")
+    print(f"Valid values: {state_def.values}")
+
+# Get the first matching state definition from a list
+state_def = device.select_first_state_definition([OverkizState.CORE_OPEN_CLOSED, OverkizState.CORE_SLATS_OPEN_CLOSED])
 if state_def:
     print(f"Type: {state_def.type}")
     print(f"Valid values: {state_def.values}")
@@ -75,12 +89,16 @@ from pyoverkiz.enums import OverkizCommand
 devices = await client.get_devices()
 device = devices[0]
 
+# Check if device supports a single command
+if device.supports_command(OverkizCommand.OPEN):
+    print("Device supports open command")
+
 # Check if device supports any of the given commands
-if device.has_supported_command([OverkizCommand.OPEN, OverkizCommand.CLOSE]):
+if device.supports_any_command([OverkizCommand.OPEN, OverkizCommand.CLOSE]):
     print("Device supports open/close commands")
 
 # Get the first supported command from a list
-supported_cmd = device.get_supported_command_name(
+supported_cmd = device.select_first_command(
     [OverkizCommand.SET_CLOSURE, OverkizCommand.OPEN, OverkizCommand.CLOSE]
 )
 if supported_cmd:
@@ -93,9 +111,14 @@ if supported_cmd:
 devices = await client.get_devices()
 device = devices[0]
 
-# Get the value of device attributes (like firmware)
-firmware = device.get_attribute_value([
+# Get the value of a single attribute
+firmware = device.get_attribute_value(OverkizAttribute.CORE_FIRMWARE_REVISION)
+print(f"Firmware: {firmware}")
+
+# Get the value of the first matching attribute from a list
+firmware = device.select_first_attribute_value([
     OverkizAttribute.CORE_FIRMWARE_REVISION,
+    OverkizAttribute.CORE_MANUFACTURER,
 ])
 print(f"Firmware: {firmware}")
 ```

pyoverkiz/models.py

@@ -287,30 +287,50 @@ def widget(self) -> UIWidget:
             return UIWidget(self.definition.widget_name)
         raise ValueError(f"Device {self.device_url} has no widget defined")
 
-    def get_supported_command_name(
-        self, commands: list[str | OverkizCommand]
-    ) -> str | None:
-        """Return the first command name that exists in this device's definition."""
-        return self.definition.commands.select(commands)
+    def supports_command(self, command: str | OverkizCommand) -> bool:
+        """Check if device supports a command."""
+        return str(command) in self.definition.commands
 
-    def has_supported_command(self, commands: list[str | OverkizCommand]) -> bool:
-        """Return True if any of the given commands exist in this device's definition."""
+    def supports_any_command(self, commands: list[str | OverkizCommand]) -> bool:
+        """Check if device supports any of the commands."""
         return self.definition.commands.has_any(commands)
 
-    def get_state_value(self, states: list[str]) -> StateType | None:
-        """Return the value of the first state that exists with a non-None value."""
+    def select_first_command(self, commands: list[str | OverkizCommand]) -> str | None:
+        """Return first supported command name from list, or None."""
+        return self.definition.commands.select(commands)
+
+    def get_state_value(self, state: str) -> StateType | None:
+        """Get value of a single state, or None if not found or None."""
+        return self.states.select_value([state])
+
+    def select_first_state_value(self, states: list[str]) -> StateType | None:
+        """Return value of first state with non-None value from list, or None."""
         return self.states.select_value(states)
 
-    def has_state_value(self, states: list[str]) -> bool:
-        """Return True if any of the given states exist with a non-None value."""
+    def has_state_value(self, state: str) -> bool:
+        """Check if a state exists with a non-None value."""
+        return self.states.has_any([state])
+
+    def has_any_state_value(self, states: list[str]) -> bool:
+        """Check if any of the states exist with non-None values."""
         return self.states.has_any(states)
 
-    def get_state_definition(self, states: list[str]) -> StateDefinition | None:
-        """Return the first StateDefinition that matches, from the device definition."""
+    def get_state_definition(self, state: str) -> StateDefinition | None:
+        """Get StateDefinition for a single state name, or None."""
+        return self.definition.get_state_definition([state])
+
+    def select_first_state_definition(
+        self, states: list[str]
+    ) -> StateDefinition | None:
+        """Return first matching StateDefinition from list, or None."""
         return self.definition.get_state_definition(states)
 
-    def get_attribute_value(self, attributes: list[str]) -> StateType:
-        """Return the value of the first attribute that exists with a non-None value."""
+    def get_attribute_value(self, attribute: str) -> StateType | None:
+        """Get value of a single attribute, or None if not found or None."""
+        return self.attributes.select_value([attribute])
+
+    def select_first_attribute_value(self, attributes: list[str]) -> StateType | None:
+        """Return value of first attribute with non-None value from list, or None."""
         return self.attributes.select_value(attributes)
 
 

tests/test_models.py

@@ -200,47 +200,92 @@ def test_none_states(self):
         device = Device(**hump_device)
         assert not device.states.get(STATE)
 
-    def test_get_supported_command_name(self):
-        """Device.get_supported_command_name() delegates to commands.select()."""
+    def test_select_first_command(self):
+        """Device.select_first_command() returns first supported command from list."""
         hump_device = humps.decamelize(RAW_DEVICES)
         device = Device(**hump_device)
-        assert (
-            device.get_supported_command_name(["nonexistent", "open", "close"])
-            == "open"
-        )
-        assert device.get_supported_command_name(["nonexistent"]) is None
+        assert device.select_first_command(["nonexistent", "open", "close"]) == "open"
+        assert device.select_first_command(["nonexistent"]) is None
+
+    def test_supports_command(self):
+        """Device.supports_command() checks if device supports a single command."""
+        hump_device = humps.decamelize(RAW_DEVICES)
+        device = Device(**hump_device)
+        assert device.supports_command("open")
+        assert not device.supports_command("nonexistent")
 
-    def test_has_supported_command(self):
-        """Device.has_supported_command() delegates to commands.has_any()."""
+    def test_supports_any_command(self):
+        """Device.supports_any_command() checks if device supports any command."""
         hump_device = humps.decamelize(RAW_DEVICES)
         device = Device(**hump_device)
-        assert device.has_supported_command(["nonexistent", "open"])
-        assert not device.has_supported_command(["nonexistent"])
+        assert device.supports_any_command(["nonexistent", "open"])
+        assert not device.supports_any_command(["nonexistent"])
 
     def test_get_state_value(self):
-        """Device.get_state_value() returns the value of the first matching state."""
+        """Device.get_state_value() returns value of a single state."""
+        hump_device = humps.decamelize(RAW_DEVICES)
+        device = Device(**hump_device)
+        value = device.get_state_value("core:ClosureState")
+        assert value == 100
+        assert device.get_state_value("nonexistent") is None
+
+    def test_select_first_state_value(self):
+        """Device.select_first_state_value() returns value of first matching state from list."""
         hump_device = humps.decamelize(RAW_DEVICES)
         device = Device(**hump_device)
-        value = device.get_state_value(["nonexistent", "core:ClosureState"])
+        value = device.select_first_state_value(["nonexistent", "core:ClosureState"])
         assert value == 100
 
     def test_has_state_value(self):
-        """Device.has_state_value() returns True if any state exists with non-None value."""
+        """Device.has_state_value() checks if a single state exists with non-None value."""
+        hump_device = humps.decamelize(RAW_DEVICES)
+        device = Device(**hump_device)
+        assert device.has_state_value("core:ClosureState")
+        assert not device.has_state_value("nonexistent")
+
+    def test_has_any_state_value(self):
+        """Device.has_any_state_value() checks if any state exists with non-None value."""
         hump_device = humps.decamelize(RAW_DEVICES)
         device = Device(**hump_device)
-        assert device.has_state_value(["nonexistent", "core:ClosureState"])
-        assert not device.has_state_value(["nonexistent"])
+        assert device.has_any_state_value(["nonexistent", "core:ClosureState"])
+        assert not device.has_any_state_value(["nonexistent"])
 
     def test_get_state_definition(self):
-        """Device.get_state_definition() returns the first matching StateDefinition."""
+        """Device.get_state_definition() returns StateDefinition for a single state."""
+        hump_device = humps.decamelize(RAW_DEVICES)
+        device = Device(**hump_device)
+        state_def = device.get_state_definition("core:ClosureState")
+        assert state_def is not None
+        assert state_def.qualified_name == "core:ClosureState"
+        assert device.get_state_definition("nonexistent") is None
+
+    def test_select_first_state_definition(self):
+        """Device.select_first_state_definition() returns first matching StateDefinition from list."""
         hump_device = humps.decamelize(RAW_DEVICES)
         device = Device(**hump_device)
-        state_def = device.get_state_definition(["nonexistent", "core:ClosureState"])
+        state_def = device.select_first_state_definition(
+            ["nonexistent", "core:ClosureState"]
+        )
         assert state_def is not None
         assert state_def.qualified_name == "core:ClosureState"
 
-    def test_get_attribute_value_returns_first_match(self):
-        """Device.get_attribute_value() returns the value of the first matching attribute."""
+    def test_get_attribute_value(self):
+        """Device.get_attribute_value() returns value of a single attribute."""
+        test_device = {
+            **RAW_DEVICES,
+            "attributes": [
+                {"name": "core:Manufacturer", "type": 3, "value": "VELUX"},
+                {"name": "core:Model", "type": 3, "value": "WINDOW 100"},
+            ],
+        }
+        hump_device = humps.decamelize(test_device)
+        device = Device(**hump_device)
+        value = device.get_attribute_value("core:Model")
+        assert value == "WINDOW 100"
+        assert device.get_attribute_value("nonexistent") is None
+
+    def test_select_first_attribute_value_returns_first_match(self):
+        """Device.select_first_attribute_value() returns value of first matching attribute from list."""
         test_device = {
             **RAW_DEVICES,
             "attributes": [
@@ -250,28 +295,28 @@ def test_get_attribute_value_returns_first_match(self):
         }
         hump_device = humps.decamelize(test_device)
         device = Device(**hump_device)
-        value = device.get_attribute_value(
+        value = device.select_first_attribute_value(
             ["nonexistent", "core:Model", "core:Manufacturer"]
         )
         assert value == "WINDOW 100"
 
-    def test_get_attribute_value_returns_none_when_no_match(self):
-        """Device.get_attribute_value() returns None when no attribute matches."""
+    def test_select_first_attribute_value_returns_none_when_no_match(self):
+        """Device.select_first_attribute_value() returns None when no attribute matches."""
         hump_device = humps.decamelize(RAW_DEVICES)
         device = Device(**hump_device)
-        value = device.get_attribute_value(["nonexistent", "also_nonexistent"])
+        value = device.select_first_attribute_value(["nonexistent", "also_nonexistent"])
         assert value is None
 
-    def test_get_attribute_value_empty_attributes(self):
-        """Device.get_attribute_value() returns None for devices with no attributes."""
+    def test_select_first_attribute_value_empty_attributes(self):
+        """Device.select_first_attribute_value() returns None for devices with no attributes."""
         test_device = {**RAW_DEVICES, "attributes": []}
         hump_device = humps.decamelize(test_device)
         device = Device(**hump_device)
-        value = device.get_attribute_value(["core:Manufacturer"])
+        value = device.select_first_attribute_value(["core:Manufacturer"])
         assert value is None
 
-    def test_get_attribute_value_with_none_values(self):
-        """Device.get_attribute_value() skips attributes with None values."""
+    def test_select_first_attribute_value_with_none_values(self):
+        """Device.select_first_attribute_value() skips attributes with None values."""
         test_device = {
             **RAW_DEVICES,
             "attributes": [
@@ -281,7 +326,7 @@ def test_get_attribute_value_with_none_values(self):
         }
         hump_device = humps.decamelize(test_device)
         device = Device(**hump_device)
-        value = device.get_attribute_value(["core:Model", "core:Manufacturer"])
+        value = device.select_first_attribute_value(["core:Model", "core:Manufacturer"])
         assert value == "VELUX"