PyPlumIO 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

pyplumio/frames/responses.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from pyplumio.const import ATTR_PASSWORD, FrameType
-from pyplumio.frames import Response
+from pyplumio.frames import Response, Structured, frame_handler
 from pyplumio.structures.alerts import AlertsStructure
 from pyplumio.structures.ecomax_parameters import EcomaxParametersStructure
 from pyplumio.structures.mixer_parameters import MixerParametersStructure
@@ -17,19 +17,15 @@ from pyplumio.structures.schedules import SchedulesStructure
 from pyplumio.structures.thermostat_parameters import ThermostatParametersStructure
 
 
-class AlertsResponse(Response):
+@frame_handler(FrameType.RESPONSE_ALERTS, structure=AlertsStructure)
+class AlertsResponse(Structured, Response):
     """Represents response to a device alerts request."""
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_ALERTS
 
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return AlertsStructure(self).decode(message)[0]
-
-
-class DeviceAvailableResponse(Response):
+@frame_handler(FrameType.RESPONSE_DEVICE_AVAILABLE, structure=NetworkInfoStructure)
+class DeviceAvailableResponse(Structured, Response):
     """Represents a device available response.
 
     Contains network information and status.
@@ -37,17 +33,8 @@ class DeviceAvailableResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_DEVICE_AVAILABLE
-
-    def create_message(self, data: dict[str, Any]) -> bytearray:
-        """Create a frame message."""
-        return NetworkInfoStructure(self).encode(data)
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return NetworkInfoStructure(self).decode(message, offset=1)[0]
-
 
+@frame_handler(FrameType.RESPONSE_ECOMAX_CONTROL)
 class EcomaxControlResponse(Response):
     """Represents response to an ecoMAX control request.
 
@@ -57,10 +44,11 @@ class EcomaxControlResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_ECOMAX_CONTROL
 
-
-class EcomaxParametersResponse(Response):
+@frame_handler(
+    FrameType.RESPONSE_ECOMAX_PARAMETERS, structure=EcomaxParametersStructure
+)
+class EcomaxParametersResponse(Structured, Response):
     """Represents an ecoMAX parameters response.
 
     Contains editable ecoMAX parameters.
@@ -68,14 +56,9 @@ class EcomaxParametersResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_ECOMAX_PARAMETERS
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return EcomaxParametersStructure(self).decode(message)[0]
-
 
-class MixerParametersResponse(Response):
+@frame_handler(FrameType.RESPONSE_MIXER_PARAMETERS, structure=MixerParametersStructure)
+class MixerParametersResponse(Structured, Response):
     """Represents a mixer parameters response.
 
     Contains editable mixer parameters.
@@ -83,13 +66,8 @@ class MixerParametersResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_MIXER_PARAMETERS
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return MixerParametersStructure(self).decode(message)[0]
-
 
+@frame_handler(FrameType.RESPONSE_PASSWORD)
 class PasswordResponse(Response):
     """Represents a password response.
 
@@ -98,15 +76,14 @@ class PasswordResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_PASSWORD
-
     def decode_message(self, message: bytearray) -> dict[str, Any]:
         """Decode a frame message."""
         password = message[1:].decode() if message[1:] else None
         return {ATTR_PASSWORD: password}
 
 
-class ProgramVersionResponse(Response):
+@frame_handler(FrameType.RESPONSE_PROGRAM_VERSION, structure=ProgramVersionStructure)
+class ProgramVersionResponse(Structured, Response):
     """Represents a program version response.
 
     Contains software version info.
@@ -114,18 +91,11 @@ class ProgramVersionResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_PROGRAM_VERSION
-
-    def create_message(self, data: dict[str, Any]) -> bytearray:
-        """Create a frame message."""
-        return ProgramVersionStructure(self).encode(data)
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return ProgramVersionStructure(self).decode(message)[0]
-
 
-class RegulatorDataSchemaResponse(Response):
+@frame_handler(
+    FrameType.RESPONSE_REGULATOR_DATA_SCHEMA, structure=RegulatorDataSchemaStructure
+)
+class RegulatorDataSchemaResponse(Structured, Response):
     """Represents a regulator data schema response.
 
     Contains schema, that describes structure of ecoMAX regulator data
@@ -134,25 +104,15 @@ class RegulatorDataSchemaResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_REGULATOR_DATA_SCHEMA
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return RegulatorDataSchemaStructure(self).decode(message)[0]
-
 
-class SchedulesResponse(Response):
+@frame_handler(FrameType.RESPONSE_SCHEDULES, structure=SchedulesStructure)
+class SchedulesResponse(Structured, Response):
     """Represents response to a device schedules request."""
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_SCHEDULES
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return SchedulesStructure(self).decode(message)[0]
-
 
+@frame_handler(FrameType.RESPONSE_SET_ECOMAX_PARAMETER)
 class SetEcomaxParameterResponse(Response):
     """Represents response to a set ecoMAX parameter request.
 
@@ -162,9 +122,8 @@ class SetEcomaxParameterResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_SET_ECOMAX_PARAMETER
-
 
+@frame_handler(FrameType.RESPONSE_SET_MIXER_PARAMETER)
 class SetMixerParameterResponse(Response):
     """Represents response to a set mixer parameter request.
 
@@ -174,9 +133,8 @@ class SetMixerParameterResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_SET_MIXER_PARAMETER
-
 
+@frame_handler(FrameType.RESPONSE_SET_THERMOSTAT_PARAMETER)
 class SetThermostatParameterResponse(Response):
     """Represents response to a set thermostat parameter request.
 
@@ -186,10 +144,11 @@ class SetThermostatParameterResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_SET_THERMOSTAT_PARAMETER
-
 
-class ThermostatParametersResponse(Response):
+@frame_handler(
+    FrameType.RESPONSE_THERMOSTAT_PARAMETERS, structure=ThermostatParametersStructure
+)
+class ThermostatParametersResponse(Structured, Response):
     """Represents a thermostat parameters response.
 
     Contains editable thermostat parameters.
@@ -197,14 +156,9 @@ class ThermostatParametersResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_THERMOSTAT_PARAMETERS
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return ThermostatParametersStructure(self).decode(message)[0]
-
 
-class UIDResponse(Response):
+@frame_handler(FrameType.RESPONSE_UID, structure=ProductInfoStructure)
+class UIDResponse(Structured, Response):
     """Represents an UID response.
 
     Contains product info and product UID.
@@ -212,16 +166,6 @@ class UIDResponse(Response):
 
     __slots__ = ()
 
-    frame_type = FrameType.RESPONSE_UID
-
-    def create_message(self, data: dict[str, Any]) -> bytearray:
-        """Create a frame message."""
-        return ProductInfoStructure(self).encode(data)
-
-    def decode_message(self, message: bytearray) -> dict[str, Any]:
-        """Decode a frame message."""
-        return ProductInfoStructure(self).decode(message)[0]
-
 
 __all__ = [
     "AlertsResponse",

pyplumio/helpers/async_cache.py

@@ -2,30 +2,35 @@
 
 from collections.abc import Awaitable, Callable
 from functools import wraps
-from typing import Any, ParamSpec, TypeAlias, TypeVar, cast
+from types import MappingProxyType
+from typing import Any, ParamSpec, TypeVar, cast
 
 T = TypeVar("T")
 P = ParamSpec("P")
-_CallableT: TypeAlias = Callable[..., Awaitable[Any]]
 
 
 class AsyncCache:
     """A simple cache for asynchronous functions."""
 
-    __slots__ = ("cache",)
+    __slots__ = ("_cache",)
 
-    cache: dict[str, Any]
+    _cache: dict[str, Any]
 
     def __init__(self) -> None:
         """Initialize the cache."""
-        self.cache = {}
+        self._cache = {}
 
-    async def get(self, key: str, coro: _CallableT) -> Any:
+    async def get(self, key: str, coro: Callable[..., Awaitable[Any]]) -> Any:
         """Get a value from the cache or compute and store it."""
         if key not in self.cache:
-            self.cache[key] = await coro()
+            self._cache[key] = await coro()
 
-        return self.cache[key]
+        return self._cache[key]
+
+    @property
+    def cache(self) -> MappingProxyType[str, Any]:
+        """Return the internal cache dictionary."""
+        return MappingProxyType(self._cache)
 
 
 # Create a global cache instance

pyplumio/helpers/event_manager.py

@@ -5,34 +5,35 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Callable, Coroutine, Generator
 import inspect
+from types import MappingProxyType
 from typing import Any, Generic, TypeAlias, TypeVar, overload
 
 from pyplumio.helpers.task_manager import TaskManager
 
-Callback: TypeAlias = Callable[[Any], Coroutine[Any, Any, Any]]
+EventCallback: TypeAlias = Callable[[Any], Coroutine[Any, Any, Any]]
+_Callable: TypeAlias = Callable[..., Any]
 
-_CallableT: TypeAlias = Callable[..., Any]
-_CallbackT = TypeVar("_CallbackT", bound=Callback)
+_EventCallbackT = TypeVar("_EventCallbackT", bound=EventCallback)
 
 
 @overload
-def event_listener(name: _CallableT, filter: None = None) -> Callback: ...
+def event_listener(name: _Callable, filter: None = None) -> EventCallback: ...
 
 
 @overload
 def event_listener(
-    name: str | None = None, filter: _CallableT | None = None
-) -> _CallableT: ...
+    name: str | None = None, filter: _Callable | None = None
+) -> _Callable: ...
 
 
-def event_listener(name: Any = None, filter: _CallableT | None = None) -> Any:
+def event_listener(name: Any = None, filter: _Callable | None = None) -> Any:
     """Mark a function as an event listener.
 
     This decorator attaches metadata to the function, identifying it
     as a subscriber for the specified event.
     """
 
-    def decorator(func: _CallbackT) -> _CallbackT:
+    def decorator(func: _EventCallbackT) -> _EventCallbackT:
         # Attach metadata to the function to mark it as a listener.
         event = (
             name
@@ -55,16 +56,16 @@ T = TypeVar("T")
 class EventManager(TaskManager, Generic[T]):
     """Represents an event manager."""
 
-    __slots__ = ("data", "_events", "_callbacks")
+    __slots__ = ("_data", "_events", "_callbacks")
 
-    data: dict[str, T]
+    _data: dict[str, T]
     _events: dict[str, asyncio.Event]
-    _callbacks: dict[str, list[Callback]]
+    _callbacks: dict[str, list[EventCallback]]
 
     def __init__(self) -> None:
         """Initialize a new event manager."""
         super().__init__()
-        self.data = {}
+        self._data = {}
         self._events = {}
         self._callbacks = {}
         self._register_event_listeners()
@@ -82,7 +83,7 @@ class EventManager(TaskManager, Generic[T]):
             filter_func = getattr(callback, "_on_event_filter", None)
             self.subscribe(event, filter_func(callback) if filter_func else callback)
 
-    def event_listeners(self) -> Generator[tuple[str, Callback]]:
+    def event_listeners(self) -> Generator[tuple[str, EventCallback]]:
         """Get the event listeners."""
         for _, callback in inspect.getmembers(self, predicate=inspect.ismethod):
             if event := getattr(callback, "_on_event", None):
@@ -141,7 +142,7 @@ class EventManager(TaskManager, Generic[T]):
         except KeyError:
             return default
 
-    def subscribe(self, name: str, callback: _CallbackT) -> _CallbackT:
+    def subscribe(self, name: str, callback: _EventCallbackT) -> _EventCallbackT:
         """Subscribe a callback to the event.
 
         :param name: Event name or ID
@@ -157,7 +158,7 @@ class EventManager(TaskManager, Generic[T]):
         callbacks.append(callback)
         return callback
 
-    def subscribe_once(self, name: str, callback: Callback) -> Callback:
+    def subscribe_once(self, name: str, callback: EventCallback) -> EventCallback:
         """Subscribe a callback to the event once.
 
         Callback will be unsubscribed after single event.
@@ -179,7 +180,7 @@ class EventManager(TaskManager, Generic[T]):
 
         return self.subscribe(name, _call_once)
 
-    def unsubscribe(self, name: str, callback: Callback) -> bool:
+    def unsubscribe(self, name: str, callback: EventCallback) -> bool:
         """Usubscribe a callback from the event.
 
         :param name: Event name or ID
@@ -204,7 +205,7 @@ class EventManager(TaskManager, Generic[T]):
                 if (result := await callback(value)) is not None:
                     value = result
 
-        self.data[name] = value
+        self._data[name] = value
         self.set_event(name)
 
     def dispatch_nowait(self, name: str, value: T) -> None:
@@ -240,5 +241,10 @@ class EventManager(TaskManager, Generic[T]):
         """Return the events."""
         return self._events
 
+    @property
+    def data(self) -> MappingProxyType[str, T]:
+        """Return the event data."""
+        return MappingProxyType(self._data)
+
 
-__all__ = ["Callback", "EventManager", "event_listener"]
+__all__ = ["EventCallback", "EventManager", "event_listener"]

pyplumio/helpers/factory.py

@@ -4,14 +4,11 @@ from __future__ import annotations
 
 import asyncio
 import importlib
-import logging
 from types import ModuleType
 from typing import Any, TypeVar
 
 from pyplumio.helpers.async_cache import acache
 
-_LOGGER = logging.getLogger(__name__)
-
 T = TypeVar("T")
 
 

pyplumio/parameters/__init__.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 import asyncio
 from contextlib import suppress
-from dataclasses import asdict, dataclass
+from copy import copy
+from dataclasses import dataclass, replace
 import logging
 from typing import TYPE_CHECKING, Any, Literal, TypeAlias, TypeVar, get_args
 
@@ -18,7 +19,7 @@ if TYPE_CHECKING:
 
 _LOGGER = logging.getLogger(__name__)
 
-ParameterT = TypeVar("ParameterT", bound="Parameter")
+_ParameterT = TypeVar("_ParameterT", bound="Parameter")
 
 
 def unpack_parameter(
@@ -44,7 +45,7 @@ def is_valid_parameter(data: bytearray) -> bool:
     return any(x for x in data if x != BYTE_UNDEFINED)
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class ParameterValues:
     """Represents a parameter values."""
 
@@ -61,7 +62,7 @@ class ParameterDescription:
     optimistic: bool = False
 
 
-NumericType: TypeAlias = int | float
+Numeric: TypeAlias = int | float
 
 
 class Parameter(ABC):
@@ -111,31 +112,34 @@ class Parameter(ABC):
 
     def __hash__(self) -> int:
         """Return a hash of the parameter based on its values."""
-        return hash(frozenset(asdict(self.values).items()))
+        return hash(self.values)
 
     def _call_relational_method(self, method_to_call: str, other: Any) -> Any:
         """Call a specified relational method."""
+        handler = getattr(self.values.value, method_to_call)
         if isinstance(other, Parameter):
-            other = other.values
+            return handler(other.values.value)
 
         if isinstance(other, ParameterValues):
-            handler = getattr(self.values.value, method_to_call)
             return handler(other.value)
 
-        if isinstance(other, int | float | bool) or other in get_args(State):
-            handler = getattr(self.values.value, method_to_call)
+        if isinstance(other, Numeric | bool) or other in get_args(State):
             return handler(self._pack_value(other))
-        else:
-            return NotImplemented
+
+        return NotImplemented
 
     def __int__(self) -> int:
         """Return an integer representation of parameter's value."""
         return self.values.value
 
     def __add__(self, other: Any) -> Any:
-        """Return result of addition."""
+        """Add a number to this parameter."""
         return self._call_relational_method("__add__", other)
 
+    def __radd__(self, other: Any) -> Any:
+        """Add this parameter to another number."""
+        return self._call_relational_method("__radd__", other)
+
     def __sub__(self, other: Any) -> Any:
         """Return result of the subtraction."""
         return self._call_relational_method("__sub__", other)
@@ -174,10 +178,7 @@ class Parameter(ABC):
 
     def __copy__(self) -> Parameter:
         """Create a copy of parameter."""
-        values = type(self.values)(
-            self.values.value, self.values.min_value, self.values.max_value
-        )
-        return type(self)(self.device, self.description, values)
+        return type(self)(self.device, self.description, values=copy(self.values))
 
     async def set(self, value: Any, retries: int = 0, timeout: float = 5.0) -> bool:
         """Set a parameter value."""
@@ -200,7 +201,7 @@ class Parameter(ABC):
             # Value is unchanged
             return True
 
-        self._values.value = value
+        self._values = replace(self._values, value=value)
         request = await self.create_request()
         if self.description.optimistic:
             await self.device.queue.put(request)
@@ -262,14 +263,14 @@ class Parameter(ABC):
 
     @classmethod
     def create_or_update(
-        cls: type[ParameterT],
+        cls: type[_ParameterT],
         device: Device,
         description: ParameterDescription,
         values: ParameterValues,
         **kwargs: Any,
-    ) -> ParameterT:
+    ) -> _ParameterT:
         """Create new parameter or update parameter values."""
-        parameter: ParameterT | None = device.get_nowait(description.name, None)
+        parameter: _ParameterT | None = device.get_nowait(description.name, None)
         if parameter and isinstance(parameter, cls):
             parameter.update(values)
         else:
@@ -293,17 +294,17 @@ class Parameter(ABC):
 
     @property
     @abstractmethod
-    def value(self) -> NumericType | State | bool:
+    def value(self) -> Numeric | State | bool:
         """Return the value."""
 
     @property
     @abstractmethod
-    def min_value(self) -> NumericType | State | bool:
+    def min_value(self) -> Numeric | State | bool:
         """Return the minimum allowed value."""
 
     @property
     @abstractmethod
-    def max_value(self) -> NumericType | State | bool:
+    def max_value(self) -> Numeric | State | bool:
         """Return the maximum allowed value."""
 
     @abstractmethod
@@ -327,11 +328,15 @@ class Number(Parameter):
 
     description: NumberDescription
 
-    def _pack_value(self, value: NumericType) -> int:
+    def __float__(self) -> float:
+        """Return number value as float."""
+        return float(self.value)
+
+    def _pack_value(self, value: Numeric) -> int:
         """Pack the parameter value."""
         return int(round(value / self.description.step))
 
-    def _unpack_value(self, value: int) -> NumericType:
+    def _unpack_value(self, value: int) -> Numeric:
         """Unpack the parameter value."""
         return round(value * self.description.step, self.description.precision)
 
@@ -351,14 +356,12 @@ class Number(Parameter):
 
         return True
 
-    async def set(
-        self, value: NumericType, retries: int = 0, timeout: float = 5.0
-    ) -> bool:
+    async def set(self, value: Numeric, retries: int = 0, timeout: float = 5.0) -> bool:
         """Set a parameter value."""
         return await super().set(value, retries=retries, timeout=timeout)
 
     def set_nowait(
-        self, value: NumericType, retries: int = 0, timeout: float = 5.0
+        self, value: Numeric, retries: int = 0, timeout: float = 5.0
     ) -> None:
         """Set a parameter value without waiting."""
         super().set_nowait(value, retries=retries, timeout=timeout)
@@ -368,17 +371,17 @@ class Number(Parameter):
         return Request()
 
     @property
-    def value(self) -> NumericType:
+    def value(self) -> Numeric:
         """Return the value."""
         return self._unpack_value(self.values.value)
 
     @property
-    def min_value(self) -> NumericType:
+    def min_value(self) -> Numeric:
         """Return the minimum allowed value."""
         return self._unpack_value(self.values.min_value)
 
     @property
-    def max_value(self) -> NumericType:
+    def max_value(self) -> Numeric:
         """Return the maximum allowed value."""
         return self._unpack_value(self.values.max_value)
 
@@ -402,11 +405,11 @@ class OffsetNumber(Number):
 
     description: OffsetNumberDescription
 
-    def _pack_value(self, value: NumericType) -> int:
+    def _pack_value(self, value: Numeric) -> int:
         """Pack the parameter value."""
         return super()._pack_value(value + self.description.offset)
 
-    def _unpack_value(self, value: int) -> NumericType:
+    def _unpack_value(self, value: int) -> Numeric:
         """Unpack the parameter value."""
         return super()._unpack_value(value - self.description.offset)
 
@@ -505,7 +508,7 @@ class Switch(Parameter):
 __all__ = [
     "Number",
     "NumberDescription",
-    "NumericType",
+    "Numeric",
     "OffsetNumber",
     "OffsetNumberDescription",
     "Parameter",