feat: add Device.get_command_definition() helper (#766)

Author: iMicknl

pyoverkiz/models.py

@@ -440,6 +440,14 @@ def select_first_command(self, commands: list[str | OverkizCommand]) -> str | No
             return None
         return self.definition.commands.select(commands)
 
+    def get_command_definition(
+        self, command: str | OverkizCommand
+    ) -> CommandDefinition | None:
+        """Return the CommandDefinition for a command, or None if unavailable."""
+        if self.definition is None:
+            return None
+        return self.definition.commands.get(str(command))
+
     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])

tests/test_models.py

@@ -981,3 +981,56 @@ def test_persisted_action_group_id_property_returns_str(self):
         result = group.id
         assert isinstance(result, str)
         assert result == "abc-123"
+
+
+def test_get_command_definition_found():
+    """Device.get_command_definition() returns CommandDefinition when command exists."""
+    from pyoverkiz.models import CommandDefinition
+
+    device = _make_device(
+        {
+            **RAW_DEVICES,
+            "definition": {
+                **RAW_DEVICES["definition"],
+                "commands": [{"commandName": "open", "nparams": 0}],
+            },
+        }
+    )
+    cd = device.get_command_definition("open")
+    assert cd is not None
+    assert isinstance(cd, CommandDefinition)
+    assert cd.nparams == 0
+
+
+def test_get_command_definition_not_found():
+    """Device.get_command_definition() returns None when command doesn't exist."""
+    device = _make_device(
+        {
+            **RAW_DEVICES,
+            "definition": {
+                **RAW_DEVICES["definition"],
+                "commands": [],
+            },
+        }
+    )
+    assert device.get_command_definition("open") is None
+
+
+def test_get_command_definition_no_definition():
+    """Device.get_command_definition() returns None when device has no definition."""
+    from pyoverkiz.enums import ProductType
+    from pyoverkiz.models import States
+
+    device = Device(
+        attributes=States(),
+        available=True,
+        enabled=True,
+        label="Test",
+        device_url="io://1234-5678-9012/1",
+        controllable_name="test",
+        definition=None,
+        type=ProductType.ACTUATOR,
+        widget="SomeWidget",
+        ui_class="RollerShutter",
+    )
+    assert device.get_command_definition("open") is None