PyPlumIO 0.5.42__py3-none-any.whl → 0.5.44__py3-none-any.whl

pyplumio/frames/responses.py

@@ -221,3 +221,21 @@ class UIDResponse(Response):
     def decode_message(self, message: bytearray) -> dict[str, Any]:
         """Decode a frame message."""
         return ProductInfoStructure(self).decode(message)[0]
+
+
+__all__ = [
+    "AlertsResponse",
+    "DeviceAvailableResponse",
+    "EcomaxControlResponse",
+    "EcomaxParametersResponse",
+    "MixerParametersResponse",
+    "PasswordResponse",
+    "ProgramVersionResponse",
+    "RegulatorDataSchemaResponse",
+    "SchedulesResponse",
+    "SetEcomaxParameterResponse",
+    "SetMixerParameterResponse",
+    "SetThermostatParameterResponse",
+    "ThermostatParametersResponse",
+    "UIDResponse",
+]

pyplumio/helpers/async_cache.py

@@ -0,0 +1,48 @@
+"""Contains a simple async cache for caching results of async functions."""
+
+from collections.abc import Awaitable
+from functools import wraps
+from typing import Any, Callable, TypeVar, cast
+
+from typing_extensions import ParamSpec
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+class AsyncCache:
+    """A simple cache for asynchronous functions."""
+
+    __slots__ = ("cache",)
+
+    cache: dict[str, Any]
+
+    def __init__(self) -> None:
+        """Initialize the cache."""
+        self.cache = {}
+
+    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()
+
+        return self.cache[key]
+
+
+# Create a global cache instance
+async_cache = AsyncCache()
+
+
+def acache(func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+    """Cache the result of an async function."""
+
+    @wraps(func)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        func_name = f"{func.__module__}.{func.__qualname__}"
+        key = f"{func_name}:{args}:{kwargs}"
+        return cast(T, await async_cache.get(key, lambda: func(*args, **kwargs)))
+
+    return wrapper
+
+
+__all__ = ["acache", "async_cache"]

pyplumio/helpers/event_manager.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable, Coroutine
+from collections.abc import Callable, Coroutine, Generator
+import inspect
 from typing import Any, Generic, TypeVar, overload
 
 from typing_extensions import TypeAlias
@@ -11,7 +12,45 @@ from typing_extensions import TypeAlias
 from pyplumio.helpers.task_manager import TaskManager
 
 Callback: TypeAlias = Callable[[Any], Coroutine[Any, Any, Any]]
-CallbackT = TypeVar("CallbackT", bound=Callback)
+
+_CallableT: TypeAlias = Callable[..., Any]
+_CallbackT = TypeVar("_CallbackT", bound=Callback)
+
+
+@overload
+def event_listener(name: _CallableT, filter: None = None) -> Callback: ...
+
+
+@overload
+def event_listener(
+    name: str | None = None, filter: _CallableT | None = None
+) -> _CallableT: ...
+
+
+def event_listener(name: Any = None, filter: _CallableT | 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:
+        # Attach metadata to the function to mark it as a listener.
+        event = (
+            name
+            if isinstance(name, str)
+            else func.__qualname__.split("on_event_", 1)[1]
+        )
+        setattr(func, "_on_event", event)
+        setattr(func, "_on_event_filter", filter)
+        return func
+
+    if callable(name):
+        return decorator(name)
+    else:
+        return decorator
+
+
 T = TypeVar("T")
 
 
@@ -30,6 +69,7 @@ class EventManager(TaskManager, Generic[T]):
         self.data = {}
         self._events = {}
         self._callbacks = {}
+        self._register_event_listeners()
 
     def __getattr__(self, name: str) -> T:
         """Return attributes from the underlying data dictionary."""
@@ -38,6 +78,18 @@ class EventManager(TaskManager, Generic[T]):
         except KeyError as e:
             raise AttributeError from e
 
+    def _register_event_listeners(self) -> None:
+        """Register the event listeners."""
+        for event, callback in self.event_listeners():
+            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]]:
+        """Get the event listeners."""
+        for _, callback in inspect.getmembers(self, predicate=inspect.ismethod):
+            if event := getattr(callback, "_on_event", None):
+                yield (event, callback)
+
     async def wait_for(self, name: str, timeout: float | None = None) -> None:
         """Wait for the value to become available.
 
@@ -91,7 +143,7 @@ class EventManager(TaskManager, Generic[T]):
         except KeyError:
             return default
 
-    def subscribe(self, name: str, callback: CallbackT) -> CallbackT:
+    def subscribe(self, name: str, callback: _CallbackT) -> _CallbackT:
         """Subscribe a callback to the event.
 
         :param name: Event name or ID
@@ -189,3 +241,6 @@ class EventManager(TaskManager, Generic[T]):
     def events(self) -> dict[str, asyncio.Event]:
         """Return the events."""
         return self._events
+
+
+__all__ = ["Callback", "EventManager", "event_listener"]

pyplumio/helpers/factory.py

@@ -13,7 +13,7 @@ _LOGGER = logging.getLogger(__name__)
 T = TypeVar("T")
 
 
-async def _import_module(name: str) -> ModuleType:
+async def import_module(name: str) -> ModuleType:
     """Import module by name."""
     loop = asyncio.get_running_loop()
     return await loop.run_in_executor(None, importlib.import_module, f"pyplumio.{name}")
@@ -23,7 +23,7 @@ async def create_instance(class_path: str, /, cls: type[T], **kwargs: Any) -> T:
     """Return a class instance from the class path."""
     module_name, class_name = class_path.rsplit(".", 1)
     try:
-        module = await _import_module(module_name)
+        module = await import_module(module_name)
         instance = getattr(module, class_name)(**kwargs)
         if not isinstance(instance, cls):
             raise TypeError(
@@ -35,3 +35,6 @@ async def create_instance(class_path: str, /, cls: type[T], **kwargs: Any) -> T:
     except Exception:
         _LOGGER.exception("Failed to create instance for class path '%s'", class_path)
         raise
+
+
+__all__ = ["create_instance"]

pyplumio/helpers/schedule.py

@@ -23,7 +23,7 @@ STEP = dt.timedelta(minutes=30)
 Time = Annotated[str, "Time string in %H:%M format"]
 
 
-def _get_time(
+def get_time(
     index: int, start: dt.datetime = MIDNIGHT_DT, step: dt.timedelta = STEP
 ) -> Time:
     """Return time for a specific index."""
@@ -32,7 +32,7 @@ def _get_time(
 
 
 @lru_cache(maxsize=10)
-def _get_time_range(start: Time, end: Time, step: dt.timedelta = STEP) -> list[Time]:
+def get_time_range(start: Time, end: Time, step: dt.timedelta = STEP) -> list[Time]:
     """Get a time range.
 
     Start and end boundaries should be specified in %H:%M format.
@@ -54,7 +54,7 @@ def _get_time_range(start: Time, end: Time, step: dt.timedelta = STEP) -> list[T
     seconds = (end_dt - start_dt).total_seconds()
     steps = seconds // step.total_seconds() + 1
 
-    return [_get_time(index, start=start_dt, step=step) for index in range(int(steps))]
+    return [get_time(index, start=start_dt, step=step) for index in range(int(steps))]
 
 
 class ScheduleDay(MutableMapping):
@@ -104,7 +104,7 @@ class ScheduleDay(MutableMapping):
         self, state: State | bool, start: Time = MIDNIGHT, end: Time = MIDNIGHT
     ) -> None:
         """Set a schedule interval state."""
-        for time in _get_time_range(start, end):
+        for time in get_time_range(start, end):
             self.__setitem__(time, state)
 
     def set_on(self, start: Time = MIDNIGHT, end: Time = MIDNIGHT) -> None:
@@ -123,7 +123,7 @@ class ScheduleDay(MutableMapping):
     @classmethod
     def from_iterable(cls: type[ScheduleDay], intervals: Iterable[bool]) -> ScheduleDay:
         """Make schedule day from iterable."""
-        return cls({_get_time(index): state for index, state in enumerate(intervals)})
+        return cls({get_time(index): state for index, state in enumerate(intervals)})
 
 
 @dataclass
@@ -174,3 +174,6 @@ class Schedule(Iterable):
                 data=collect_schedule_data(self.name, self.device),
             )
         )
+
+
+__all__ = ["Schedule", "ScheduleDay"]

pyplumio/helpers/task_manager.py

@@ -40,3 +40,6 @@ class TaskManager:
     def tasks(self) -> set[asyncio.Task]:
         """Return the tasks."""
         return self._tasks
+
+
+__all__ = ["TaskManager"]

pyplumio/helpers/timeout.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable, Coroutine
+from collections.abc import Awaitable, Callable
 from functools import wraps
-from typing import Any, TypeVar
+from typing import TypeVar
 
 from typing_extensions import ParamSpec
 
@@ -15,12 +15,10 @@ P = ParamSpec("P")
 
 def timeout(
     seconds: float,
-) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Coroutine[Any, Any, T]]]:
+) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T]]]:
     """Decorate a timeout for the awaitable."""
 
-    def decorator(
-        func: Callable[P, Awaitable[T]],
-    ) -> Callable[P, Coroutine[Any, Any, T]]:
+    def decorator(func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
         @wraps(func)
         async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
             return await asyncio.wait_for(func(*args, **kwargs), timeout=seconds)
@@ -28,3 +26,6 @@ def timeout(
         return wrapper
 
     return decorator
+
+
+__all__ = ["timeout"]

pyplumio/helpers/uid.py

@@ -12,10 +12,10 @@ BASE5_KEY: Final = "0123456789ABCDEFGHIJKLMNZPQRSTUV"
 
 def unpack_uid(buffer: bytes) -> str:
     """Unpack UID from bytes."""
-    return _base5(buffer + _crc16(buffer))
+    return base5(buffer + crc16(buffer))
 
 
-def _base5(buffer: bytes) -> str:
+def base5(buffer: bytes) -> str:
     """Encode bytes to a base5 encoded string."""
     number = int.from_bytes(buffer, byteorder="little")
     output = []
@@ -26,16 +26,19 @@ def _base5(buffer: bytes) -> str:
     return "".join(reversed(output))
 
 
-def _crc16(buffer: bytes) -> bytes:
+def crc16(buffer: bytes) -> bytes:
     """Return a CRC 16."""
-    crc16 = reduce(_crc16_byte, buffer, CRC)
+    crc16 = reduce(crc16_byte, buffer, CRC)
     return crc16.to_bytes(length=2, byteorder="little")
 
 
-def _crc16_byte(crc: int, byte: int) -> int:
+def crc16_byte(crc: int, byte: int) -> int:
     """Add a byte to the CRC."""
     crc ^= byte
     for _ in range(8):
         crc = (crc >> 1) ^ POLYNOMIAL if crc & 1 else crc >> 1
 
     return crc
+
+
+__all__ = ["unpack_uid"]

pyplumio/{helpers/parameter.py → parameters/__init__.py}

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 import asyncio
+from collections.abc import Sequence
 from dataclasses import dataclass
 import logging
 from typing import TYPE_CHECKING, Any, Literal, TypeVar, Union, get_args
@@ -11,8 +12,16 @@ from typing import TYPE_CHECKING, Any, Literal, TypeVar, Union, get_args
 from dataslots import dataslots
 from typing_extensions import TypeAlias
 
-from pyplumio.const import BYTE_UNDEFINED, STATE_OFF, STATE_ON, State, UnitOfMeasurement
+from pyplumio.const import (
+    BYTE_UNDEFINED,
+    STATE_OFF,
+    STATE_ON,
+    ProductModel,
+    State,
+    UnitOfMeasurement,
+)
 from pyplumio.frames import Request
+from pyplumio.structures.product_info import ProductInfo
 from pyplumio.utils import is_divisible
 
 if TYPE_CHECKING:
@@ -20,8 +29,6 @@ if TYPE_CHECKING:
 
 _LOGGER = logging.getLogger(__name__)
 
-
-NumericType: TypeAlias = Union[int, float]
 ParameterT = TypeVar("ParameterT", bound="Parameter")
 
 
@@ -68,6 +75,9 @@ class ParameterDescription:
     optimistic: bool = False
 
 
+NumericType: TypeAlias = Union[int, float]
+
+
 class Parameter(ABC):
     """Represents a base parameter."""
 
@@ -186,7 +196,7 @@ class Parameter(ABC):
         self, value: int, retries: int = 5, timeout: float = 5.0
     ) -> bool:
         """Attempt to update a parameter value on the remote device."""
-        _LOGGER.debug(
+        _LOGGER.info(
             "Attempting to update '%s' parameter to %d", self.description.name, value
         )
         if value == self.values.value:
@@ -360,6 +370,30 @@ class Number(Parameter):
         return self.description.unit_of_measurement
 
 
+@dataslots
+@dataclass
+class OffsetNumberDescription(NumberDescription):
+    """Represents a parameter description."""
+
+    offset: int = 0
+
+
+class OffsetNumber(Number):
+    """Represents a number with offset."""
+
+    __slots__ = ()
+
+    description: OffsetNumberDescription
+
+    def _pack_value(self, value: NumericType) -> int:
+        """Pack the parameter value."""
+        return super()._pack_value(value + self.description.offset)
+
+    def _unpack_value(self, value: int) -> NumericType:
+        """Unpack the parameter value."""
+        return super()._unpack_value(value - self.description.offset)
+
+
 @dataslots
 @dataclass
 class SwitchDescription(ParameterDescription):
@@ -387,7 +421,10 @@ class Switch(Parameter):
     def validate(self, value: Any) -> bool:
         """Validate a parameter value."""
         if not isinstance(value, bool) and value not in get_args(State):
-            raise ValueError(f"Invalid switch value: {value}. Must be 'on' or 'off'.")
+            raise ValueError(
+                f"Invalid value: {value}. The value must be either 'on', 'off' or "
+                f"boolean."
+            )
 
         return True
 
@@ -447,3 +484,66 @@ class Switch(Parameter):
     def max_value(self) -> Literal["on"]:
         """Return the maximum allowed value."""
         return STATE_ON
+
+
+@dataclass
+class ParameterOverride:
+    """Represents a parameter override."""
+
+    __slot__ = ("original", "replacement", "product_model", "product_id")
+
+    original: str
+    replacement: ParameterDescription
+    product_model: ProductModel
+    product_id: int
+
+
+_DescriptorT = TypeVar("_DescriptorT", bound=ParameterDescription)
+
+
+def patch_parameter_types(
+    product_info: ProductInfo,
+    parameter_types: list[_DescriptorT],
+    parameter_overrides: Sequence[ParameterOverride],
+) -> list[_DescriptorT]:
+    """Patch the parameter types based on the provided overrides.
+
+    Note:
+        The `# type: ignore[assignment]` comment is used to suppress a
+        type-checking error caused by mypy bug. For more details, see:
+        https://github.com/python/mypy/issues/13596
+
+    """
+    replacements = {
+        override.original: override.replacement
+        for override in parameter_overrides
+        if override.product_model.value == product_info.model
+        and override.product_id == product_info.id
+    }
+    for index, description in enumerate(parameter_types):
+        if description.name in replacements:
+            _LOGGER.info(
+                "Replacing parameter description for '%s' with '%s' (%s)",
+                description.name,
+                replacements[description.name],
+                product_info.model,
+            )
+            parameter_types[index] = replacements[description.name]  # type: ignore[assignment]
+
+    return parameter_types
+
+
+__all__ = [
+    "Number",
+    "NumberDescription",
+    "NumericType",
+    "OffsetNumber",
+    "OffsetNumberDescription",
+    "Parameter",
+    "ParameterDescription",
+    "ParameterValues",
+    "patch_parameter_types",
+    "State",
+    "Switch",
+    "SwitchDescription",
+]