feat: add UIProfileDefinition model and related classes, and implement UI profile fetching in generate_enums

Author: iMicknl

pyoverkiz/client.py

@@ -65,6 +65,7 @@
     ServerConfig,
     Setup,
     State,
+    UIProfileDefinition,
 )
 from pyoverkiz.obfuscate import obfuscate_sensitive_data
 from pyoverkiz.serializers import prepare_payload
@@ -698,11 +699,19 @@ async def get_reference_ui_classifiers(self) -> list[str]:
         return await self.__get("reference/ui/classifiers")
 
     @retry_on_auth_error
-    async def get_reference_ui_profile(self, profile_name: str) -> JSON:
-        """Get a description of a given UI profile (or form-factor variant)."""
-        return await self.__get(
+    async def get_reference_ui_profile(self, profile_name: str) -> UIProfileDefinition:
+        """Get a description of a given UI profile (or form-factor variant).
+
+        Returns a profile definition containing:
+        - name: Profile name
+        - commands: Available commands with parameters and descriptions
+        - states: Available states with value types and descriptions
+        - form_factor: Whether profile is tied to a specific physical device type
+        """
+        response = await self.__get(
             f"reference/ui/profile/{urllib.parse.quote_plus(profile_name)}"
         )
+        return UIProfileDefinition(**humps.decamelize(response))
 
     @retry_on_auth_error
     async def get_reference_ui_profile_names(self) -> list[str]:

pyoverkiz/models.py

@@ -1047,3 +1047,154 @@ def __init__(self, id: int, prefix: str, name: str, label: str, **_: Any):
         self.prefix = prefix
         self.name = name
         self.label = label
+
+
+@define(init=False, kw_only=True)
+class ValuePrototype:
+    """Value prototype defining parameter/state value constraints."""
+
+    type: str
+    min_value: int | float | None = None
+    max_value: int | float | None = None
+    enum_values: list[str] | None = None
+    description: str | None = None
+
+    def __init__(
+        self,
+        type: str,
+        min_value: int | float | None = None,
+        max_value: int | float | None = None,
+        enum_values: list[str] | None = None,
+        description: str | None = None,
+        **_: Any,
+    ):
+        """Initialize ValuePrototype from API data."""
+        self.type = type
+        self.min_value = min_value
+        self.max_value = max_value
+        self.enum_values = enum_values
+        self.description = description
+
+
+@define(init=False, kw_only=True)
+class CommandParameter:
+    """Command parameter definition."""
+
+    optional: bool
+    sensitive: bool
+    value_prototypes: list[ValuePrototype]
+
+    def __init__(
+        self,
+        optional: bool,
+        sensitive: bool,
+        value_prototypes: list[dict] | None = None,
+        **_: Any,
+    ):
+        """Initialize CommandParameter from API data."""
+        self.optional = optional
+        self.sensitive = sensitive
+        self.value_prototypes = (
+            [ValuePrototype(**vp) for vp in value_prototypes]
+            if value_prototypes
+            else []
+        )
+
+
+@define(init=False, kw_only=True)
+class CommandPrototype:
+    """Command prototype defining parameters."""
+
+    parameters: list[CommandParameter]
+
+    def __init__(self, parameters: list[dict] | None = None, **_: Any):
+        """Initialize CommandPrototype from API data."""
+        self.parameters = (
+            [CommandParameter(**p) for p in parameters] if parameters else []
+        )
+
+
+@define(init=False, kw_only=True)
+class UIProfileCommand:
+    """UI profile command definition."""
+
+    name: str
+    prototype: CommandPrototype | None = None
+    description: str | None = None
+
+    def __init__(
+        self,
+        name: str,
+        prototype: dict | None = None,
+        description: str | None = None,
+        **_: Any,
+    ):
+        """Initialize UIProfileCommand from API data."""
+        self.name = name
+        self.prototype = CommandPrototype(**prototype) if prototype else None
+        self.description = description
+
+
+@define(init=False, kw_only=True)
+class StatePrototype:
+    """State prototype defining value constraints."""
+
+    value_prototypes: list[ValuePrototype]
+
+    def __init__(self, value_prototypes: list[dict] | None = None, **_: Any):
+        """Initialize StatePrototype from API data."""
+        self.value_prototypes = (
+            [ValuePrototype(**vp) for vp in value_prototypes]
+            if value_prototypes
+            else []
+        )
+
+
+@define(init=False, kw_only=True)
+class UIProfileState:
+    """UI profile state definition."""
+
+    name: str
+    prototype: StatePrototype | None = None
+    description: str | None = None
+
+    def __init__(
+        self,
+        name: str,
+        prototype: dict | None = None,
+        description: str | None = None,
+        **_: Any,
+    ):
+        """Initialize UIProfileState from API data."""
+        self.name = name
+        self.prototype = StatePrototype(**prototype) if prototype else None
+        self.description = description
+
+
+@define(init=False, kw_only=True)
+class UIProfileDefinition:
+    """UI profile definition from the reference API.
+
+    Describes device capabilities through available commands and states.
+    """
+
+    name: str
+    commands: list[UIProfileCommand]
+    states: list[UIProfileState]
+    form_factor: bool
+
+    def __init__(
+        self,
+        name: str,
+        commands: list[dict] | None = None,
+        states: list[dict] | None = None,
+        form_factor: bool = False,
+        **_: Any,
+    ):
+        """Initialize UIProfileDefinition from API data."""
+        self.name = name
+        self.commands = (
+            [UIProfileCommand(**cmd) for cmd in commands] if commands else []
+        )
+        self.states = [UIProfileState(**s) for s in states] if states else []
+        self.form_factor = form_factor

tests/test_ui_profile.py

@@ -0,0 +1,146 @@
+"""Tests for UIProfileDefinition models."""
+
+from pyoverkiz.models import (
+    CommandParameter,
+    UIProfileCommand,
+    UIProfileDefinition,
+    UIProfileState,
+    ValuePrototype,
+)
+
+
+def test_value_prototype_with_range():
+    """Test ValuePrototype with min/max range."""
+    vp = ValuePrototype(type="INT", min_value=0, max_value=100)
+    assert vp.type == "INT"
+    assert vp.min_value == 0
+    assert vp.max_value == 100
+    assert vp.enum_values is None
+
+
+def test_value_prototype_with_enum():
+    """Test ValuePrototype with enum values."""
+    vp = ValuePrototype(
+        type="STRING", enum_values=["low", "high"], description="Fan speed mode"
+    )
+    assert vp.type == "STRING"
+    assert vp.enum_values == ["low", "high"]
+    assert vp.description == "Fan speed mode"
+
+
+def test_command_parameter():
+    """Test CommandParameter with value prototypes."""
+    param = CommandParameter(
+        optional=False,
+        sensitive=False,
+        value_prototypes=[{"type": "INT", "min_value": 0, "max_value": 100}],
+    )
+    assert param.optional is False
+    assert param.sensitive is False
+    assert len(param.value_prototypes) == 1
+    assert param.value_prototypes[0].type == "INT"
+
+
+def test_ui_profile_command():
+    """Test UIProfileCommand with prototype."""
+    cmd = UIProfileCommand(
+        name="setFanSpeedLevel",
+        prototype={
+            "parameters": [
+                {
+                    "optional": False,
+                    "sensitive": False,
+                    "value_prototypes": [
+                        {"type": "INT", "min_value": 0, "max_value": 100}
+                    ],
+                }
+            ]
+        },
+        description="Set the device fan speed level",
+    )
+    assert cmd.name == "setFanSpeedLevel"
+    assert cmd.description == "Set the device fan speed level"
+    assert cmd.prototype is not None
+    assert len(cmd.prototype.parameters) == 1
+
+
+def test_ui_profile_state():
+    """Test UIProfileState with prototype."""
+    state = UIProfileState(
+        name="core:TemperatureState",
+        prototype={
+            "value_prototypes": [
+                {"type": "FLOAT", "min_value": -100.0, "max_value": 100.0}
+            ]
+        },
+        description="Current room temperature",
+    )
+    assert state.name == "core:TemperatureState"
+    assert state.description == "Current room temperature"
+    assert state.prototype is not None
+    assert len(state.prototype.value_prototypes) == 1
+
+
+def test_ui_profile_definition():
+    """Test complete UIProfileDefinition."""
+    profile = UIProfileDefinition(
+        name="AirFan",
+        commands=[
+            {
+                "name": "setFanSpeedLevel",
+                "prototype": {
+                    "parameters": [
+                        {
+                            "optional": False,
+                            "sensitive": False,
+                            "value_prototypes": [
+                                {"type": "INT", "min_value": 0, "max_value": 100}
+                            ],
+                        }
+                    ]
+                },
+                "description": "Set fan speed",
+            }
+        ],
+        states=[
+            {
+                "name": "core:FanSpeedState",
+                "prototype": {
+                    "value_prototypes": [
+                        {"type": "INT", "min_value": 0, "max_value": 100}
+                    ]
+                },
+                "description": "Current fan speed",
+            }
+        ],
+        form_factor=False,
+    )
+
+    assert profile.name == "AirFan"
+    assert len(profile.commands) == 1
+    assert len(profile.states) == 1
+    assert profile.form_factor is False
+
+    # Verify command structure
+    cmd = profile.commands[0]
+    assert cmd.name == "setFanSpeedLevel"
+    assert cmd.description == "Set fan speed"
+    assert cmd.prototype is not None
+    assert len(cmd.prototype.parameters) == 1
+
+    # Verify state structure
+    state = profile.states[0]
+    assert state.name == "core:FanSpeedState"
+    assert state.description == "Current fan speed"
+    assert state.prototype is not None
+    assert len(state.prototype.value_prototypes) == 1
+
+
+def test_ui_profile_definition_minimal():
+    """Test UIProfileDefinition with minimal data."""
+    profile = UIProfileDefinition(name="MinimalProfile")
+
+    assert profile.name == "MinimalProfile"
+    assert profile.commands == []
+    assert profile.states == []
+    assert profile.form_factor is False