Refactor type hints in OverkizClient and models for improved clarity and consistency

Author: iMicknl

pyoverkiz/client.py

@@ -59,7 +59,6 @@
 from pyoverkiz.obfuscate import obfuscate_sensitive_data
 from pyoverkiz.response_handler import check_response
 from pyoverkiz.serializers import prepare_payload
-from pyoverkiz.types import JSON
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -404,7 +403,7 @@ async def get_execution_history(self) -> list[HistoryExecution]:
         return converter.structure(decamelize(response), list[HistoryExecution])
 
     @retry_on_auth_error
-    async def get_device_definition(self, deviceurl: str) -> JSON | None:
+    async def get_device_definition(self, deviceurl: str) -> dict[str, Any] | None:
         """Retrieve a particular setup device definition."""
         response: dict = await self._get(
             f"setup/devices/{urllib.parse.quote_plus(deviceurl)}"
@@ -696,19 +695,23 @@ async def get_setup_option_parameter(
         return None
 
     @retry_on_auth_error
-    async def get_reference_controllable(self, controllable_name: str) -> JSON:
+    async def get_reference_controllable(
+        self, controllable_name: str
+    ) -> dict[str, Any]:
         """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:
+    async def get_reference_controllable_types(self) -> list[dict[str, Any]]:
         """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:
+    async def search_reference_devices_model(
+        self, payload: dict[str, Any]
+    ) -> dict[str, Any]:
         """Search reference device models using a POST payload."""
         return await self._post("reference/devices/search", payload)
 
@@ -727,7 +730,7 @@ async def get_reference_protocol_types(self) -> list[ProtocolType]:
         return converter.structure(response, list[ProtocolType])
 
     @retry_on_auth_error
-    async def get_reference_timezones(self) -> JSON:
+    async def get_reference_timezones(self) -> list[dict[str, Any]]:
         """Get timezones list."""
         return await self._get("reference/timezones")
 
@@ -824,7 +827,10 @@ async def _get(self, path: str) -> Any:
             return await self._parse_response(response)
 
     async def _post(
-        self, path: str, payload: JSON | None = None, data: JSON | None = None
+        self,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
     ) -> Any:
         """Make a POST request to the OverKiz API."""
         await self._refresh_token_if_expired()
@@ -838,7 +844,7 @@ async def _post(
         ) as response:
             return await self._parse_response(response)
 
-    async def _put(self, path: str, payload: JSON | None = None) -> Any:
+    async def _put(self, path: str, payload: dict[str, Any] | None = None) -> Any:
         """Make a PUT request to the OverKiz API."""
         await self._refresh_token_if_expired()
 

pyoverkiz/models.py

@@ -4,7 +4,7 @@
 
 import json
 import re
-from collections.abc import Iterator
+from collections.abc import Iterator, Mapping
 from typing import Any, cast
 
 from attr import define, field
@@ -24,11 +24,11 @@
     UpdateBoxStatus,
     UpdateCriticityLevel,
 )
-from pyoverkiz.enums.command import OverkizCommand, OverkizCommandParam
+from pyoverkiz.enums.command import OverkizCommand
 from pyoverkiz.enums.protocol import Protocol
 from pyoverkiz.enums.server import APIType, Server
 from pyoverkiz.obfuscate import obfuscate_email, obfuscate_id, obfuscate_string
-from pyoverkiz.types import DATA_TYPE_TO_PYTHON, StateType
+from pyoverkiz.types import DATA_TYPE_TO_PYTHON, CommandParameterValue, StateType
 
 # ---------------------------------------------------------------------------
 # State & command primitives
@@ -129,8 +129,8 @@ def _cast_json_value(self, raw_value: str) -> StateType:
 
 
 @define(init=False)
-class States:
-    """Container of State objects providing lookup and mapping helpers."""
+class States(Mapping[str, State]):
+    """Container of State objects implementing Mapping[str, State]."""
 
     _states: list[State]
     _index: dict[str, State]
@@ -142,9 +142,9 @@ def __init__(self, states: list[State] | None = None) -> None:
         self._index = {state.name: state for state in self._states}
         self._pos = {state.name: i for i, state in enumerate(self._states)}
 
-    def __iter__(self) -> Iterator[State]:
-        """Return an iterator over contained State objects."""
-        return self._states.__iter__()
+    def __iter__(self) -> Iterator[str]:
+        """Return an iterator over state names."""
+        return iter(self._index)
 
     def __contains__(self, name: object) -> bool:
         """Return True if a state with the given name exists in the container."""
@@ -172,10 +172,6 @@ def __len__(self) -> int:
         """Return number of states in the container."""
         return len(self._states)
 
-    def get(self, name: str) -> State | None:
-        """Return the State with the given name or None if missing."""
-        return self._index.get(name)
-
     def select(self, names: list[str]) -> State | None:
         """Return the first State that exists and has a non-None value, or None."""
         for name in names:
@@ -204,8 +200,8 @@ class CommandDefinition:
 
 
 @define(init=False)
-class CommandDefinitions:
-    """Container for command definitions providing convenient lookup by name."""
+class CommandDefinitions(Mapping[str, CommandDefinition]):
+    """Container for command definitions implementing Mapping[str, CommandDefinition]."""
 
     _commands: list[CommandDefinition]
     _index: dict[str, CommandDefinition]
@@ -215,9 +211,9 @@ def __init__(self, commands: list[CommandDefinition] | None = None) -> None:
         self._commands = list(commands) if commands else []
         self._index = {cd.command_name: cd for cd in self._commands}
 
-    def __iter__(self) -> Iterator[CommandDefinition]:
-        """Iterate over defined commands."""
-        return self._commands.__iter__()
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over command names."""
+        return iter(self._index)
 
     def __contains__(self, name: object) -> bool:
         """Return True if a command with `name` exists."""
@@ -234,10 +230,6 @@ def __len__(self) -> int:
         """Return number of command definitions."""
         return len(self._commands)
 
-    def get(self, command: str) -> CommandDefinition | None:
-        """Return the command definition or None if missing."""
-        return self._index.get(command)
-
     def select(self, commands: list[str | OverkizCommand]) -> str | None:
         """Return the first command name that exists in this definition, or None."""
         return next(
@@ -283,7 +275,7 @@ class Command:
     """Represents an OverKiz Command."""
 
     name: str | OverkizCommand
-    parameters: list[str | int | float | OverkizCommandParam] | None = None
+    parameters: list[CommandParameterValue] | None = None
     type: int | None = None
 
     def to_payload(self) -> dict[str, object]:

pyoverkiz/types.py

@@ -7,9 +7,12 @@
 from typing import Any
 
 from pyoverkiz.enums import DataType
+from pyoverkiz.enums.command import OverkizCommandParam
 
 StateType = str | int | float | bool | dict[str, Any] | list[Any] | None
 
+CommandParameterValue = str | int | float | bool | OverkizCommandParam
+
 
 def _parse_bool(value: str) -> bool:
     """Parse a string value into a boolean.
@@ -27,5 +30,3 @@ def _parse_bool(value: str) -> bool:
     DataType.JSON_ARRAY: json.loads,
     DataType.JSON_OBJECT: json.loads,
 }
-
-JSON = dict[str, Any] | list[dict[str, Any]]  # pylint: disable=invalid-name