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

pyplumio/helpers/data_types.py

@@ -54,15 +54,15 @@ class DataType(ABC, Generic[T]):
 
         return NotImplemented
 
-    def _slice_data(self, data: bytes) -> bytes:
+    def _slice_to_size(self, buffer: bytes) -> bytes:
         """Slice the data to data type size."""
-        return data if self.size == 0 else data[: self.size]
+        return buffer if self.size == 0 else buffer[: self.size]
 
     @classmethod
-    def from_bytes(cls: type[DataTypeT], data: bytes, offset: int = 0) -> DataTypeT:
+    def from_bytes(cls: type[DataTypeT], buffer: bytes, offset: int = 0) -> DataTypeT:
         """Initialize a new data type from bytes."""
         data_type = cls()
-        data_type.unpack(data[offset:])
+        data_type.unpack(buffer[offset:])
         return data_type
 
     def to_bytes(self) -> bytes:
@@ -84,7 +84,7 @@ class DataType(ABC, Generic[T]):
         """Pack the data."""
 
     @abstractmethod
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
 
 
@@ -138,9 +138,9 @@ class BitArray(DataType[int]):
 
         return b""
 
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
-        self._value = UnsignedChar.from_bytes(data[:1]).value
+        self._value = UnsignedChar.from_bytes(buffer[:1]).value
 
     @property
     def value(self) -> bool:
@@ -170,9 +170,9 @@ class IPv4(DataType[str]):
         """Pack the data."""
         return socket.inet_aton(self.value)
 
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
-        self._value = socket.inet_ntoa(self._slice_data(data))
+        self._value = socket.inet_ntoa(self._slice_to_size(buffer))
 
 
 class IPv6(DataType[str]):
@@ -189,9 +189,9 @@ class IPv6(DataType[str]):
         """Pack the data."""
         return socket.inet_pton(socket.AF_INET6, self.value)
 
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
-        self._value = socket.inet_ntop(socket.AF_INET6, self._slice_data(data))
+        self._value = socket.inet_ntop(socket.AF_INET6, self._slice_to_size(buffer))
 
 
 class String(DataType[str]):
@@ -208,9 +208,9 @@ class String(DataType[str]):
         """Pack the data."""
         return self.value.encode() + b"\0"
 
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
-        self._value = data.split(b"\0", 1)[0].decode("utf-8", "replace")
+        self._value = buffer.split(b"\0", 1)[0].decode("utf-8", "replace")
         self._size = len(self.value) + 1
 
 
@@ -228,10 +228,10 @@ class VarBytes(DataType[bytes]):
         """Pack the data."""
         return UnsignedChar(self.size - 1).to_bytes() + self.value
 
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
-        self._size = data[0] + 1
-        self._value = data[1 : self.size]
+        self._size = buffer[0] + 1
+        self._value = buffer[1 : self.size]
 
 
 class VarString(DataType[str]):
@@ -248,10 +248,10 @@ class VarString(DataType[str]):
         """Pack the data."""
         return UnsignedChar(self.size - 1).to_bytes() + self.value.encode()
 
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
-        self._size = data[0] + 1
-        self._value = data[1 : self.size].decode("utf-8", "replace")
+        self._size = buffer[0] + 1
+        self._value = buffer[1 : self.size].decode("utf-8", "replace")
 
 
 class BuiltInDataType(DataType[T], ABC):
@@ -265,9 +265,9 @@ class BuiltInDataType(DataType[T], ABC):
         """Pack the data."""
         return self._struct.pack(self.value)
 
-    def unpack(self, data: bytes) -> None:
+    def unpack(self, buffer: bytes) -> None:
         """Unpack the data."""
-        self._value = self._struct.unpack_from(data)[0]
+        self._value = self._struct.unpack_from(buffer)[0]
 
     @property
     def size(self) -> int:
@@ -379,3 +379,5 @@ DATA_TYPES: tuple[type[DataType], ...] = (
     IPv4,
     IPv6,
 )
+
+__all__ = ["DataType"] + list({dt.__name__ for dt in DATA_TYPES})

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,27 @@ 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)
+
+
+def event_listener(event: str, filter: _CallableT | None = None) -> _CallableT:
+    """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.
+        setattr(func, "_on_event", event)
+        setattr(func, "_on_event_filter", filter)
+        return func
+
+    return decorator
+
+
 T = TypeVar("T")
 
 
@@ -30,6 +51,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 +60,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 +125,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 +223,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,24 +3,21 @@
 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_extensions import ParamSpec
+from typing_extensions import ParamSpec, TypeAlias
 
 T = TypeVar("T")
 P = ParamSpec("P")
+_CallableT: TypeAlias = Callable[..., Any]
 
 
-def timeout(
-    seconds: float,
-) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Coroutine[Any, Any, T]]]:
+def timeout(seconds: float) -> _CallableT:
     """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]]) -> _CallableT:
         @wraps(func)
         async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
             return await asyncio.wait_for(func(*args, **kwargs), timeout=seconds)
@@ -28,3 +25,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."""
 
@@ -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,60 @@ 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:
+            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",
+]