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

pyplumio/devices/thermostat.py

@@ -3,59 +3,49 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Coroutine, Generator, Sequence
-from typing import TYPE_CHECKING, Any
+from collections.abc import Coroutine, Generator
+import logging
+from typing import Any
 
-from pyplumio.devices import PhysicalDevice, VirtualDevice
-from pyplumio.helpers.parameter import ParameterValues
-from pyplumio.structures.thermostat_parameters import (
-    ATTR_THERMOSTAT_PARAMETERS,
-    THERMOSTAT_PARAMETERS,
+from pyplumio.devices import VirtualDevice
+from pyplumio.helpers.event_manager import event_listener
+from pyplumio.parameters import ParameterValues
+from pyplumio.parameters.thermostat import (
     ThermostatNumber,
     ThermostatSwitch,
     ThermostatSwitchDescription,
+    get_thermostat_parameter_types,
 )
-from pyplumio.structures.thermostat_sensors import ATTR_THERMOSTAT_SENSORS
 
-if TYPE_CHECKING:
-    from pyplumio.frames import Frame
+_LOGGER = logging.getLogger()
 
 
 class Thermostat(VirtualDevice):
     """Represents a thermostat."""
 
-    def __init__(
-        self, queue: asyncio.Queue[Frame], parent: PhysicalDevice, index: int = 0
-    ) -> None:
-        """Initialize a new thermostat."""
-        super().__init__(queue, parent, index)
-        self.subscribe(ATTR_THERMOSTAT_SENSORS, self._handle_thermostat_sensors)
-        self.subscribe(ATTR_THERMOSTAT_PARAMETERS, self._handle_thermostat_parameters)
+    __slots__ = ()
 
-    async def _handle_thermostat_sensors(self, sensors: dict[str, Any]) -> bool:
-        """Handle thermostat sensors.
-
-        For each sensor dispatch an event with the
-        sensor's name and value.
-        """
+    @event_listener
+    async def on_event_thermostat_sensors(self, sensors: dict[str, Any]) -> bool:
+        """Update thermostat sensors and dispatch the events."""
+        _LOGGER.info("Received thermostat %i sensors", self.index)
         await asyncio.gather(
             *(self.dispatch(name, value) for name, value in sensors.items())
         )
         return True
 
-    async def _handle_thermostat_parameters(
-        self, parameters: Sequence[tuple[int, ParameterValues]]
+    @event_listener
+    async def on_event_thermostat_parameters(
+        self, parameters: list[tuple[int, ParameterValues]]
     ) -> bool:
-        """Handle thermostat parameters.
-
-        For each parameter dispatch an event with the
-        parameter's name and value.
-        """
+        """Update thermostat parameters and dispatch the events."""
+        _LOGGER.info("Received thermostat %i parameters", self.index)
 
         def _thermostat_parameter_events() -> Generator[Coroutine, Any, None]:
             """Get dispatch calls for thermostat parameter events."""
+            parameter_types = get_thermostat_parameter_types()
             for index, values in parameters:
-                description = THERMOSTAT_PARAMETERS[index]
+                description = parameter_types[index]
                 handler = (
                     ThermostatSwitch
                     if isinstance(description, ThermostatSwitchDescription)
@@ -74,3 +64,6 @@ class Thermostat(VirtualDevice):
 
         await asyncio.gather(*_thermostat_parameter_events())
         return True
+
+
+__all__ = ["Thermostat"]

pyplumio/filters.py

@@ -4,7 +4,10 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from collections.abc import Callable
+from contextlib import suppress
 from copy import copy
+from decimal import Decimal
+import logging
 import math
 import time
 from typing import (
@@ -17,8 +20,20 @@ from typing import (
     runtime_checkable,
 )
 
+from typing_extensions import TypeAlias
+
 from pyplumio.helpers.event_manager import Callback
-from pyplumio.helpers.parameter import Parameter
+from pyplumio.parameters import Parameter
+
+_LOGGER = logging.getLogger(__name__)
+
+numpy_installed = False
+with suppress(ImportError):
+    import numpy as np
+
+    _LOGGER.info("Using numpy for improved float precision")
+    numpy_installed = True
+
 
 UNDEFINED: Final = "undefined"
 TOLERANCE: Final = 0.1
@@ -50,20 +65,18 @@ Comparable = TypeVar("Comparable", Parameter, SupportsFloat, SupportsComparison)
 
 
 @overload
-def _significantly_changed(old: Parameter, new: Parameter) -> bool: ...
+def is_close(old: Parameter, new: Parameter) -> bool: ...
 
 
 @overload
-def _significantly_changed(old: SupportsFloat, new: SupportsFloat) -> bool: ...
+def is_close(old: SupportsFloat, new: SupportsFloat) -> bool: ...
 
 
 @overload
-def _significantly_changed(
-    old: SupportsComparison, new: SupportsComparison
-) -> bool: ...
+def is_close(old: SupportsComparison, new: SupportsComparison) -> bool: ...
 
 
-def _significantly_changed(old: Comparable, new: Comparable) -> bool:
+def is_close(old: Comparable, new: Comparable) -> bool:
     """Check if value is significantly changed."""
     if isinstance(old, Parameter) and isinstance(new, Parameter):
         return new.pending_update or old.values.__ne__(new.values)
@@ -75,16 +88,16 @@ def _significantly_changed(old: Comparable, new: Comparable) -> bool:
 
 
 @overload
-def _diffence_between(old: list, new: list) -> list: ...
+def diffence_between(old: list, new: list) -> list: ...
 
 
 @overload
-def _diffence_between(
+def diffence_between(
     old: SupportsSubtraction, new: SupportsSubtraction
 ) -> SupportsSubtraction: ...
 
 
-def _diffence_between(
+def diffence_between(
     old: SupportsSubtraction | list, new: SupportsSubtraction | list
 ) -> SupportsSubtraction | list | None:
     """Return a difference between values."""
@@ -125,6 +138,70 @@ class Filter(ABC):
         """Set a new value for the callback."""
 
 
+class _Aggregate(Filter):
+    """Represents an aggregate filter.
+
+    Calls a callback with a sum of values collected over a specified
+    time period or when sample size limit reached.
+    """
+
+    __slots__ = ("_values", "_sample_size", "_timeout", "_last_call_time")
+
+    _values: list[float | int | Decimal]
+    _sample_size: int
+    _timeout: float
+    _last_call_time: float
+
+    def __init__(self, callback: Callback, seconds: float, sample_size: int) -> None:
+        """Initialize a new aggregate filter."""
+        super().__init__(callback)
+        self._last_call_time = time.monotonic()
+        self._timeout = seconds
+        self._sample_size = sample_size
+        self._values = []
+
+    async def __call__(self, new_value: Any) -> Any:
+        """Set a new value for the callback."""
+        if not isinstance(new_value, (float, int, Decimal)):
+            raise TypeError(
+                "Aggregate filter can only be used with numeric values, got "
+                f"{type(new_value).__name__}: {new_value}"
+            )
+
+        current_time = time.monotonic()
+        self._values.append(new_value)
+        time_since_call = current_time - self._last_call_time
+        if time_since_call >= self._timeout or len(self._values) >= self._sample_size:
+            result = await self._callback(
+                np.sum(self._values) if numpy_installed else sum(self._values)
+            )
+            self._last_call_time = current_time
+            self._values = []
+            return result
+
+
+def aggregate(callback: Callback, seconds: float, sample_size: int) -> _Aggregate:
+    """Create a new aggregate filter.
+
+    A callback function will be called with a sum of values collected
+    over a specified time period or when sample size limit reached.
+    Can only be used with numeric values.
+
+    :param callback: A callback function to be awaited once filter
+        conditions are fulfilled
+    :type callback: Callback
+    :param seconds: A callback will be awaited with a sum of values
+        aggregated over this amount of seconds.
+    :type seconds: float
+    :param sample_size: The maximum number of values to aggregate
+        before calling the callback
+    :type sample_size: int
+    :return: An instance of callable filter
+    :rtype: _Aggregate
+    """
+    return _Aggregate(callback, seconds, sample_size)
+
+
 class _Clamp(Filter):
     """Represents a clamp filter.
 
@@ -137,7 +214,7 @@ class _Clamp(Filter):
     _max_value: float
 
     def __init__(self, callback: Callback, min_value: float, max_value: float) -> None:
-        """Initialize a new clamp filter."""
+        """Initialize a new Clamp filter."""
         super().__init__(callback)
         self._min_value = min_value
         self._max_value = max_value
@@ -154,10 +231,10 @@ class _Clamp(Filter):
 
 
 def clamp(callback: Callback, min_value: float, max_value: float) -> _Clamp:
-    """Return a clamp filter.
+    """Create a new clamp filter.
 
-    A callback function will be called with value clamped between
-    specified boundaries.
+    A callback function will be called and passed value clamped
+    between specified boundaries.
 
     :param callback: A callback function to be awaited on new value
     :type callback: Callback
@@ -171,36 +248,49 @@ def clamp(callback: Callback, min_value: float, max_value: float) -> _Clamp:
     return _Clamp(callback, min_value, max_value)
 
 
-class _OnChange(Filter):
-    """Represents a value changed filter.
+_FilterT: TypeAlias = Callable[[Any], bool]
 
-    Calls a callback only when value is changed from the
-    previous callback call.
+
+class _Custom(Filter):
+    """Represents a custom filter.
+
+    Calls a callback with value, if user-defined filter function
+    that's called by this class with the value as an argument
+    returns true.
     """
 
-    __slots__ = ()
+    __slots__ = ("_filter_fn",)
+
+    _filter_fn: _FilterT
+
+    def __init__(self, callback: Callback, filter_fn: _FilterT) -> None:
+        """Initialize a new custom filter."""
+        super().__init__(callback)
+        self._filter_fn = filter_fn
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._value == UNDEFINED or _significantly_changed(self._value, new_value):
-            self._value = (
-                copy(new_value) if isinstance(new_value, Parameter) else new_value
-            )
-            return await self._callback(new_value)
+        if self._filter_fn(new_value):
+            await self._callback(new_value)
 
 
-def on_change(callback: Callback) -> _OnChange:
-    """Return a value changed filter.
+def custom(callback: Callback, filter_fn: _FilterT) -> _Custom:
+    """Create a new custom filter.
 
-    A callback function will only be called if value is changed from the
-    previous call.
+    A callback function will be called when a user-defined filter
+    function, that's being called with the value as an argument,
+    returns true.
 
-    :param callback: A callback function to be awaited on value change
+    :param callback: A callback function to be awaited when
+        filter function return true
     :type callback: Callback
+    :param filter_fn: Filter function, that will be called with a
+        value and should return `True` to await filter's callback
+    :type filter_fn: Callable[[Any], bool]
     :return: An instance of callable filter
-    :rtype: _OnChange
+    :rtype: _Custom
     """
-    return _OnChange(callback)
+    return _Custom(callback, filter_fn)
 
 
 class _Debounce(Filter):
@@ -223,7 +313,7 @@ class _Debounce(Filter):
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._value == UNDEFINED or _significantly_changed(self._value, new_value):
+        if self._value == UNDEFINED or is_close(self._value, new_value):
             self._calls += 1
         else:
             self._calls = 0
@@ -237,9 +327,9 @@ class _Debounce(Filter):
 
 
 def debounce(callback: Callback, min_calls: int) -> _Debounce:
-    """Return a debounce filter.
+    """Create a new debounce filter.
 
-    A callback function will only called once value is stabilized
+    A callback function will only be called once the value is stabilized
     across multiple filter calls.
 
     :param callback: A callback function to be awaited on value change
@@ -253,53 +343,6 @@ def debounce(callback: Callback, min_calls: int) -> _Debounce:
     return _Debounce(callback, min_calls)
 
 
-class _Throttle(Filter):
-    """Represents a throttle filter.
-
-    Calls a callback only when certain amount of seconds passed
-    since the last call.
-    """
-
-    __slots__ = ("_last_called", "_timeout")
-
-    _last_called: float | None
-    _timeout: float
-
-    def __init__(self, callback: Callback, seconds: float) -> None:
-        """Initialize a new throttle filter."""
-        super().__init__(callback)
-        self._last_called = None
-        self._timeout = seconds
-
-    async def __call__(self, new_value: Any) -> Any:
-        """Set a new value for the callback."""
-        current_timestamp = time.monotonic()
-        if (
-            self._last_called is None
-            or (current_timestamp - self._last_called) >= self._timeout
-        ):
-            self._last_called = current_timestamp
-            return await self._callback(new_value)
-
-
-def throttle(callback: Callback, seconds: float) -> _Throttle:
-    """Return a throttle filter.
-
-    A callback function will only be called once a certain amount of
-    seconds passed since the last call.
-
-    :param callback: A callback function that will be awaited once
-        filter conditions are fulfilled
-    :type callback: Callback
-    :param seconds: A callback will be awaited at most once per
-        this amount of seconds
-    :type seconds: float
-    :return: An instance of callable filter
-    :rtype: _Throttle
-    """
-    return _Throttle(callback, seconds)
-
-
 class _Delta(Filter):
     """Represents a difference filter.
 
@@ -310,23 +353,23 @@ class _Delta(Filter):
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._value == UNDEFINED or _significantly_changed(self._value, new_value):
+        if self._value == UNDEFINED or is_close(self._value, new_value):
             old_value = self._value
             self._value = (
                 copy(new_value) if isinstance(new_value, Parameter) else new_value
             )
             if (
                 self._value != UNDEFINED
-                and (difference := _diffence_between(old_value, new_value)) is not None
+                and (difference := diffence_between(old_value, new_value)) is not None
             ):
                 return await self._callback(difference)
 
 
 def delta(callback: Callback) -> _Delta:
-    """Return a difference filter.
+    """Create a new difference filter.
 
     A callback function will be called with a difference between two
-    subsequent value.
+    subsequent values.
 
     :param callback: A callback function that will be awaited with
         difference between values in two subsequent calls
@@ -337,98 +380,96 @@ def delta(callback: Callback) -> _Delta:
     return _Delta(callback)
 
 
-class _Aggregate(Filter):
-    """Represents an aggregate filter.
+class _OnChange(Filter):
+    """Represents a value changed filter.
 
-    Calls a callback with a sum of values collected over a specified
-    time period.
+    Calls a callback only when value is changed from the
+    previous callback call.
     """
 
-    __slots__ = ("_sum", "_last_update", "_timeout")
-
-    _sum: complex
-    _last_update: float
-    _timeout: float
+    __slots__ = ()
 
-    def __init__(self, callback: Callback, seconds: float) -> None:
-        """Initialize a new aggregate filter."""
+    def __init__(self, callback: Callback) -> None:
+        """Initialize a new value changed filter."""
         super().__init__(callback)
-        self._last_update = time.monotonic()
-        self._timeout = seconds
-        self._sum = 0.0
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        current_timestamp = time.monotonic()
-        try:
-            self._sum += new_value
-        except TypeError as e:
-            raise ValueError(
-                "Aggregate filter can only be used with numeric values"
-            ) from e
-
-        if current_timestamp - self._last_update >= self._timeout:
-            result = await self._callback(self._sum)
-            self._last_update = current_timestamp
-            self._sum = 0.0
-            return result
+        if self._value == UNDEFINED or is_close(self._value, new_value):
+            self._value = (
+                copy(new_value) if isinstance(new_value, Parameter) else new_value
+            )
+            return await self._callback(new_value)
 
 
-def aggregate(callback: Callback, seconds: float) -> _Aggregate:
-    """Return an aggregate filter.
+def on_change(callback: Callback) -> _OnChange:
+    """Create a new value changed filter.
 
-    A callback function will be called with a sum of values collected
-    over a specified time period. Can only be used with numeric values.
+    A callback function will only be called if the value is changed from the
+    previous call.
 
-    :param callback: A callback function to be awaited once filter
-        conditions are fulfilled
+    :param callback: A callback function to be awaited on value change
     :type callback: Callback
-    :param seconds: A callback will be awaited with a sum of values
-        aggregated over this amount of seconds.
-    :type seconds: float
     :return: An instance of callable filter
-    :rtype: _Aggregate
+    :rtype: _OnChange
     """
-    return _Aggregate(callback, seconds)
+    return _OnChange(callback)
 
 
-class _Custom(Filter):
-    """Represents a custom filter.
+class _Throttle(Filter):
+    """Represents a throttle filter.
 
-    Calls a callback with value, if user-defined filter function
-    that's called by this class with the value as an argument
-    returns true.
+    Calls a callback only when certain amount of seconds passed
+    since the last call.
     """
 
-    __slots__ = ("_filter_fn",)
+    __slots__ = ("_last_called", "_timeout")
 
-    filter_fn: Callable[[Any], bool]
+    _last_called: float | None
+    _timeout: float
 
-    def __init__(self, callback: Callback, filter_fn: Callable[[Any], bool]) -> None:
-        """Initialize a new custom filter."""
+    def __init__(self, callback: Callback, seconds: float) -> None:
+        """Initialize a new throttle filter."""
         super().__init__(callback)
-        self._filter_fn = filter_fn
+        self._last_called = None
+        self._timeout = seconds
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._filter_fn(new_value):
-            await self._callback(new_value)
+        current_timestamp = time.monotonic()
+        if (
+            self._last_called is None
+            or (current_timestamp - self._last_called) >= self._timeout
+        ):
+            self._last_called = current_timestamp
+            return await self._callback(new_value)
 
 
-def custom(callback: Callback, filter_fn: Callable[[Any], bool]) -> _Custom:
-    """Return a custom filter.
+def throttle(callback: Callback, seconds: float) -> _Throttle:
+    """Create a new throttle filter.
 
-    A callback function will be called when user-defined filter
-    function, that's being called with the value as an argument,
-    returns true.
+    A callback function will only be called once a certain amount of
+    seconds passed since the last call.
 
-    :param callback: A callback function to be awaited when
-        filter function return true
+    :param callback: A callback function that will be awaited once
+        filter conditions are fulfilled
     :type callback: Callback
-    :param filter_fn: Filter function, that will be called with a
-        value and should return `True` to await filter's callback
-    :type filter_fn: Callable[[Any], bool]
+    :param seconds: A callback will be awaited at most once per
+        this amount of seconds
+    :type seconds: float
     :return: An instance of callable filter
-    :rtype: _Custom
+    :rtype: _Throttle
     """
-    return _Custom(callback, filter_fn)
+    return _Throttle(callback, seconds)
+
+
+__all__ = [
+    "Filter",
+    "aggregate",
+    "clamp",
+    "custom",
+    "debounce",
+    "delta",
+    "on_change",
+    "throttle",
+]

pyplumio/frames/__init__.py

@@ -30,9 +30,9 @@ if TYPE_CHECKING:
     from pyplumio.devices import PhysicalDevice
 
 
-def bcc(data: bytes) -> int:
+def bcc(buffer: bytes) -> int:
     """Return a block check character."""
-    return reduce(lambda x, y: x ^ y, data)
+    return reduce(lambda x, y: x ^ y, buffer)
 
 
 @cache
@@ -121,12 +121,12 @@ class Frame(ABC):
                 self._message,
                 self._data,
             ) == (
-                self.recipient,
-                self.sender,
-                self.econet_type,
-                self.econet_version,
-                self._message,
-                self._data,
+                other.recipient,
+                other.sender,
+                other.econet_type,
+                other.econet_version,
+                other._message,
+                other._data,
             )
 
         return NotImplemented
@@ -280,3 +280,15 @@ class Message(Response):
     """Represents a message."""
 
     __slots__ = ()
+
+
+__all__ = [
+    "Frame",
+    "Request",
+    "Response",
+    "Message",
+    "DataFrameDescription",
+    "bcc",
+    "is_known_frame_type",
+    "get_frame_handler",
+]

pyplumio/frames/messages.py

@@ -79,3 +79,6 @@ class SensorDataMessage(Message):
             sensors[ATTR_STATE] = DeviceState(sensors[ATTR_STATE])
 
         return {ATTR_SENSORS: sensors}
+
+
+__all__ = ["RegulatorDataMessage", "SensorDataMessage"]

pyplumio/frames/requests.py

@@ -260,3 +260,24 @@ class UIDRequest(Request):
     __slots__ = ()
 
     frame_type = FrameType.REQUEST_UID
+
+
+__all__ = [
+    "AlertsRequest",
+    "CheckDeviceRequest",
+    "EcomaxControlRequest",
+    "EcomaxParametersRequest",
+    "MixerParametersRequest",
+    "PasswordRequest",
+    "ProgramVersionRequest",
+    "RegulatorDataSchemaRequest",
+    "SchedulesRequest",
+    "SetEcomaxParameterRequest",
+    "SetMixerParameterRequest",
+    "SetScheduleRequest",
+    "SetThermostatParameterRequest",
+    "StartMasterRequest",
+    "StopMasterRequest",
+    "ThermostatParametersRequest",
+    "UIDRequest",
+]