Improve enum structure (#1925)

## Breaking
- Various `UIClass` and `UIWidget` enums have been renamed to proper
UPPER_SNAKE_CASE.

## Enhancements
- `UIClass`, `UIWidget` and `UIProfile` are now auto-generated.
- Enums that include an `Unknown` value now inherit from a shared base
class (`UnknownEnumMixin`) to reduce code repetition
- Add SDK functions to retrieve device information, including
controllable types, devices, `ui_classes`, `ui_classifiers`,
`ui_profile`, and `ui_widgets`

---------

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

Author: 3 people

pyoverkiz/client.py

@@ -62,9 +62,11 @@
     Option,
     OptionParameter,
     Place,
+    ProtocolType,
     ServerConfig,
     Setup,
     State,
+    UIProfileDefinition,
 )
 from pyoverkiz.obfuscate import obfuscate_sensitive_data
 from pyoverkiz.serializers import prepare_payload
@@ -652,6 +654,76 @@ async def get_setup_option_parameter(
 
         return None
 
+    @retry_on_auth_error
+    async def get_reference_controllable(self, controllable_name: str) -> JSON:
+        """Get a controllable definition."""
+        return await self.__get(
+            f"reference/controllable/{urllib.parse.quote_plus(controllable_name)}"
+        )
+
+    @retry_on_auth_error
+    async def get_reference_controllable_types(self) -> JSON:
+        """Get details about all supported controllable types."""
+        return await self.__get("reference/controllableTypes")
+
+    @retry_on_auth_error
+    async def search_reference_devices_model(self, payload: JSON) -> JSON:
+        """Search reference device models using a POST payload."""
+        return await self.__post("reference/devices/search", payload)
+
+    @retry_on_auth_error
+    async def get_reference_protocol_types(self) -> list[ProtocolType]:
+        """Get details about supported protocol types on that server instance.
+
+        Returns a list of protocol type definitions, each containing:
+        - id: Numeric protocol identifier
+        - prefix: URL prefix used in device addresses
+        - name: Internal protocol name
+        - label: Human-readable protocol label
+        """
+        response = await self.__get("reference/protocolTypes")
+        return [ProtocolType(**protocol) for protocol in response]
+
+    @retry_on_auth_error
+    async def get_reference_timezones(self) -> JSON:
+        """Get timezones list."""
+        return await self.__get("reference/timezones")
+
+    @retry_on_auth_error
+    async def get_reference_ui_classes(self) -> list[str]:
+        """Get a list of all defined UI classes."""
+        return await self.__get("reference/ui/classes")
+
+    @retry_on_auth_error
+    async def get_reference_ui_classifiers(self) -> list[str]:
+        """Get a list of all defined UI classifiers."""
+        return await self.__get("reference/ui/classifiers")
+
+    @retry_on_auth_error
+    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]:
+        """Get a list of all defined UI profiles (and form-factor variants)."""
+        return await self.__get("reference/ui/profileNames")
+
+    @retry_on_auth_error
+    async def get_reference_ui_widgets(self) -> list[str]:
+        """Get a list of all defined UI widgets."""
+        return await self.__get("reference/ui/widgets")
+
     async def __get(self, path: str) -> Any:
         """Make a GET request to the OverKiz API."""
         await self._refresh_token_if_expired()

pyoverkiz/enums/__init__.py

@@ -1,13 +1,43 @@
 """Convenience re-exports for the enums package."""
 
-# flake8: noqa: F403
+# Explicitly re-export all Enum subclasses to avoid wildcard import issues
+from pyoverkiz.enums.command import CommandMode, OverkizCommand, OverkizCommandParam
+from pyoverkiz.enums.execution import (
+    ExecutionState,
+    ExecutionSubType,
+    ExecutionType,
+)
+from pyoverkiz.enums.gateway import GatewaySubType, GatewayType, UpdateBoxStatus
+from pyoverkiz.enums.general import DataType, EventName, FailureType, ProductType
+from pyoverkiz.enums.measured_value_type import MeasuredValueType
+from pyoverkiz.enums.protocol import Protocol
+from pyoverkiz.enums.server import APIType, Server
+from pyoverkiz.enums.state import OverkizAttribute, OverkizState
+from pyoverkiz.enums.ui import UIClass, UIClassifier, UIWidget
+from pyoverkiz.enums.ui_profile import UIProfile
 
-from .command import *
-from .execution import *
-from .gateway import *
-from .general import *
-from .measured_value_type import *
-from .protocol import *
-from .server import *
-from .state import *
-from .ui import *
+__all__ = [
+    "APIType",
+    "CommandMode",
+    "DataType",
+    "EventName",
+    "ExecutionState",
+    "ExecutionSubType",
+    "ExecutionType",
+    "FailureType",
+    "GatewaySubType",
+    "GatewayType",
+    "MeasuredValueType",
+    "OverkizAttribute",
+    "OverkizCommand",
+    "OverkizCommandParam",
+    "OverkizState",
+    "ProductType",
+    "Protocol",
+    "Server",
+    "UIClass",
+    "UIClassifier",
+    "UIProfile",
+    "UIWidget",
+    "UpdateBoxStatus",
+]

pyoverkiz/enums/base.py

@@ -0,0 +1,27 @@
+"""Shared enum helpers for consistent parsing and logging."""
+
+from __future__ import annotations
+
+import logging
+from typing import Self, cast
+
+
+class UnknownEnumMixin:
+    """Mixin for enums that need an `UNKNOWN` fallback.
+
+    Define `UNKNOWN` on the enum and optionally override
+    `__missing_message__` to customize the log message.
+    """
+
+    __missing_message__ = "Unsupported value %s has been returned for %s"
+
+    @classmethod
+    def _missing_(cls, value: object) -> Self:  # type: ignore[override]
+        """Return `UNKNOWN` and log unrecognized values.
+
+        Intentionally overrides the Enum base `_missing_` to provide an UNKNOWN fallback.
+        """
+        message = cls.__missing_message__
+        logging.getLogger(cls.__module__).warning(message, value, cls)
+        # Type checker cannot infer UNKNOWN exists on Self, but all subclasses define it
+        return cast(Self, cls.UNKNOWN)  # type: ignore[attr-defined]