PyPlumIO 0.5.44__tar.gz → 0.5.49__tar.gz

{pyplumio-0.5.44 → pyplumio-0.5.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPlumIO
-Version: 0.5.44
+Version: 0.5.49
 Summary: PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.
 Author-email: Denis Paavilainen <denpa@denpa.pro>
 License: MIT License
@@ -35,7 +35,7 @@ Requires-Dist: numpy<3.0.0,>=2.0.0; extra == "test"
 Requires-Dist: pyserial-asyncio-fast==0.16; extra == "test"
 Requires-Dist: pytest==8.3.5; extra == "test"
 Requires-Dist: pytest-asyncio==0.26.0; extra == "test"
-Requires-Dist: ruff==0.11.7; extra == "test"
+Requires-Dist: ruff==0.11.9; extra == "test"
 Requires-Dist: tox==4.25.0; extra == "test"
 Requires-Dist: types-pyserial==3.5.0.20250326; extra == "test"
 Provides-Extra: docs

{pyplumio-0.5.44 → pyplumio-0.5.49}/PyPlumIO.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPlumIO
-Version: 0.5.44
+Version: 0.5.49
 Summary: PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.
 Author-email: Denis Paavilainen <denpa@denpa.pro>
 License: MIT License
@@ -35,7 +35,7 @@ Requires-Dist: numpy<3.0.0,>=2.0.0; extra == "test"
 Requires-Dist: pyserial-asyncio-fast==0.16; extra == "test"
 Requires-Dist: pytest==8.3.5; extra == "test"
 Requires-Dist: pytest-asyncio==0.26.0; extra == "test"
-Requires-Dist: ruff==0.11.7; extra == "test"
+Requires-Dist: ruff==0.11.9; extra == "test"
 Requires-Dist: tox==4.25.0; extra == "test"
 Requires-Dist: types-pyserial==3.5.0.20250326; extra == "test"
 Provides-Extra: docs

{pyplumio-0.5.44 → pyplumio-0.5.49}/PyPlumIO.egg-info/SOURCES.txt

@@ -70,6 +70,8 @@ pyplumio/parameters/__init__.py
 pyplumio/parameters/ecomax.py
 pyplumio/parameters/mixer.py
 pyplumio/parameters/thermostat.py
+pyplumio/parameters/custom/__init__.py
+pyplumio/parameters/custom/ecomax_860d3_hb.py
 pyplumio/structures/__init__.py
 pyplumio/structures/alerts.py
 pyplumio/structures/boiler_load.py
@@ -101,13 +103,18 @@ tests/conftest.py
 tests/ruff.toml
 tests/test_connection.py
 tests/test_data_types.py
-tests/test_devices.py
 tests/test_filters.py
 tests/test_init.py
 tests/test_main.py
 tests/test_protocol.py
 tests/test_stream.py
 tests/test_utils.py
+tests/devices/__init__.py
+tests/devices/test_ecomax.py
+tests/devices/test_ecoster.py
+tests/devices/test_init.py
+tests/devices/test_mixer.py
+tests/devices/test_thermostat.py
 tests/frames/test_init.py
 tests/frames/test_messages.py
 tests/frames/test_requests.py
@@ -125,8 +132,12 @@ tests/parameters/test_ecomax.py
 tests/parameters/test_init.py
 tests/parameters/test_mixers.py
 tests/parameters/test_thermostats.py
+tests/parameters/custom/__init__.py
+tests/parameters/custom/test_ecomax_860d3_hb.py
+tests/parameters/custom/test_init.py
 tests/testdata/messages/regulator_data.json
 tests/testdata/messages/sensor_data.json
+tests/testdata/parameters/ecomax_860d3_hb.json
 tests/testdata/requests/alerts.json
 tests/testdata/requests/ecomax_control.json
 tests/testdata/requests/ecomax_parameters.json

{pyplumio-0.5.44 → pyplumio-0.5.49}/PyPlumIO.egg-info/requires.txt

@@ -21,6 +21,6 @@ numpy<3.0.0,>=2.0.0
 pyserial-asyncio-fast==0.16
 pytest==8.3.5
 pytest-asyncio==0.26.0
-ruff==0.11.7
+ruff==0.11.9
 tox==4.25.0
 types-pyserial==3.5.0.20250326

{pyplumio-0.5.44 → pyplumio-0.5.49}/docs/source/callbacks.rst

@@ -79,6 +79,20 @@ value is changed.
     # last call.
     ecomax.subscribe("heating_temp", filters.on_change(my_callback))
 
+.. autofunction:: pyplumio.filters.deadband
+
+This filter await the callback on signifacant changes only.
+Significance is defined by ``tolerance`` argument (i. e. tolerance=0.1
+will only await callback when value is changed by more that 0.1).
+
+.. code-block:: python
+
+    from pyplumio import filters
+
+    # Await the callback once heating_temp value is changed by more
+    # than 0.1 since last call.
+    ecomax.subscribe("heating_temp", filters.deadband(my_callback, tolerance=0.1))
+
 .. autofunction:: pyplumio.filters.debounce
 
 This filter will only await the callback once value is settled across

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.5.44'
-__version_tuple__ = version_tuple = (0, 5, 44)
+__version__ = version = '0.5.49'
+__version_tuple__ = version_tuple = (0, 5, 49)

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/devices/__init__.py

@@ -39,7 +39,11 @@ def get_device_handler(device_type: int) -> str:
 
     type_name = to_camelcase(
         DeviceType(device_type).name,
-        overrides={"ecomax": "EcoMAX", "ecoster": "EcoSTER"},
+        overrides={
+            "ecomax": "EcoMAX",
+            "ecoster": "EcoSTER",
+            "econet": "EcoNET",
+        },
     )
     return f"devices.{type_name.lower()}.{type_name}"
 
@@ -68,7 +72,7 @@ class Device(ABC, EventManager):
         :param name: Name of the parameter
         :type name: str
         :param value: New value for the parameter
-        :type value: int | float | bool | Literal["off", "on"]
+        :type value: int | float | bool | Literal["on", "off"]
         :param retries: Try setting parameter for this amount of
             times, defaults to 5
         :type retries: int, optional
@@ -100,7 +104,7 @@ class Device(ABC, EventManager):
         :param name: Name of the parameter
         :type name: str
         :param value: New value for the parameter
-        :type value: int | float | bool | Literal["off", "on"]
+        :type value: int | float | bool | Literal["on", "off"]
         :param retries: Try setting parameter for this amount of
             times, defaults to 5
         :type retries: int, optional
@@ -141,7 +145,7 @@ class PhysicalDevice(Device, ABC):
     @event_listener(filter=on_change)
     async def on_event_frame_versions(self, versions: dict[int, int]) -> None:
         """Check frame versions and update outdated frames."""
-        _LOGGER.info("Received version table")
+        _LOGGER.info("Received frame version table")
         for frame_type, version in versions.items():
             if (
                 is_known_frame_type(frame_type)

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/devices/ecomax.py

@@ -12,6 +12,7 @@ from pyplumio.const import (
     ATTR_FRAME_ERRORS,
     ATTR_PASSWORD,
     ATTR_SENSORS,
+    ATTR_SETUP,
     STATE_OFF,
     STATE_ON,
     DeviceState,
@@ -192,7 +193,8 @@ class EcoMAX(PhysicalDevice):
         self, frame_type: FrameType | int, version: int
     ) -> None:
         """Request frame version from the device."""
-        if frame_type not in REQUIRED_TYPES:
+        setup_done = self.get_nowait(ATTR_SETUP, False)
+        if setup_done or frame_type not in REQUIRED_TYPES:
             await super()._request_frame_version(frame_type, version)
 
     async def _set_ecomax_state(self, state: State) -> bool:
@@ -258,10 +260,10 @@ class EcoMAX(PhysicalDevice):
         """Update ecoMAX parameters and dispatch the events."""
         _LOGGER.info("Received device parameters")
         product_info: ProductInfo = await self.get(ATTR_PRODUCT)
+        parameter_types = await get_ecomax_parameter_types(product_info)
 
-        def _ecomax_parameter_events() -> Generator[Coroutine, Any, None]:
+        def _ecomax_parameter_events() -> Generator[Coroutine]:
             """Get dispatch calls for ecoMAX parameter events."""
-            parameter_types = get_ecomax_parameter_types(product_info)
             for index, values in parameters:
                 try:
                     description = parameter_types[index]

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/devices/mixer.py

@@ -42,10 +42,10 @@ class Mixer(VirtualDevice):
         """Update mixer parameters and dispatch the events."""
         _LOGGER.info("Received mixer %i parameters", self.index)
         product_info: ProductInfo = await self.parent.get(ATTR_PRODUCT)
+        parameter_types = get_mixer_parameter_types(product_info)
 
-        def _mixer_parameter_events() -> Generator[Coroutine, Any, None]:
+        def _mixer_parameter_events() -> Generator[Coroutine]:
             """Get dispatch calls for mixer parameter events."""
-            parameter_types = get_mixer_parameter_types(product_info)
             for index, values in parameters:
                 try:
                     description = parameter_types[index]

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/devices/thermostat.py

@@ -40,10 +40,10 @@ class Thermostat(VirtualDevice):
     ) -> bool:
         """Update thermostat parameters and dispatch the events."""
         _LOGGER.info("Received thermostat %i parameters", self.index)
+        parameter_types = get_thermostat_parameter_types()
 
-        def _thermostat_parameter_events() -> Generator[Coroutine, Any, None]:
+        def _thermostat_parameter_events() -> Generator[Coroutine]:
             """Get dispatch calls for thermostat parameter events."""
-            parameter_types = get_thermostat_parameter_types()
             for index, values in parameters:
                 description = parameter_types[index]
                 handler = (

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/filters.py

@@ -36,7 +36,6 @@ with suppress(ImportError):
 
 
 UNDEFINED: Final = "undefined"
-TOLERANCE: Final = 0.1
 
 
 @runtime_checkable
@@ -63,26 +62,34 @@ class SupportsComparison(Protocol):
 
 Comparable = TypeVar("Comparable", Parameter, SupportsFloat, SupportsComparison)
 
+DEFAULT_TOLERANCE: Final = 1e-6
+
 
 @overload
-def is_close(old: Parameter, new: Parameter) -> bool: ...
+def is_close(old: Parameter, new: Parameter, tolerance: None = None) -> bool: ...
 
 
 @overload
-def is_close(old: SupportsFloat, new: SupportsFloat) -> bool: ...
+def is_close(
+    old: SupportsFloat, new: SupportsFloat, tolerance: float = DEFAULT_TOLERANCE
+) -> bool: ...
 
 
 @overload
-def is_close(old: SupportsComparison, new: SupportsComparison) -> bool: ...
+def is_close(
+    old: SupportsComparison, new: SupportsComparison, tolerance: None = None
+) -> bool: ...
 
 
-def is_close(old: Comparable, new: Comparable) -> bool:
+def is_close(
+    old: Comparable, new: Comparable, tolerance: float | None = DEFAULT_TOLERANCE
+) -> 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)
 
-    if isinstance(old, SupportsFloat) and isinstance(new, SupportsFloat):
-        return not math.isclose(old, new, abs_tol=TOLERANCE)
+    if tolerance and isinstance(old, SupportsFloat) and isinstance(new, SupportsFloat):
+        return not math.isclose(old, new, abs_tol=tolerance)
 
     return old.__ne__(new)
 
@@ -293,6 +300,53 @@ def custom(callback: Callback, filter_fn: _FilterT) -> _Custom:
     return _Custom(callback, filter_fn)
 
 
+class _Deadband(Filter):
+    """Represents a deadband filter.
+
+    Calls a callback only when value is significantly changed from the
+    previous callback call.
+    """
+
+    __slots__ = ("_tolerance",)
+
+    _tolerance: float
+
+    def __init__(self, callback: Callback, tolerance: float) -> None:
+        """Initialize a new value changed filter."""
+        self._tolerance = tolerance
+        super().__init__(callback)
+
+    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(
+                "Deadband filter can only be used with numeric values, got "
+                f"{type(new_value).__name__}: {new_value}"
+            )
+
+        if self._value == UNDEFINED or is_close(
+            self._value, new_value, tolerance=self._tolerance
+        ):
+            self._value = new_value
+            return await self._callback(new_value)
+
+
+def deadband(callback: Callback, tolerance: float) -> _Deadband:
+    """Create a new deadband filter.
+
+    A callback function will only be called when the value is significantly changed
+    from the previous callback call.
+
+    :param callback: A callback function to be awaited on significant value change
+    :type callback: Callback
+    :param tolerance: The minimum difference required to trigger the callback
+    :type tolerance: float
+    :return: An instance of callable filter
+    :rtype: _Deadband
+    """
+    return _Deadband(callback, tolerance)
+
+
 class _Debounce(Filter):
     """Represents a debounce filter.
 
@@ -468,6 +522,7 @@ __all__ = [
     "aggregate",
     "clamp",
     "custom",
+    "deadband",
     "debounce",
     "delta",
     "on_change",

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/helpers/async_cache.py

@@ -4,10 +4,11 @@ from collections.abc import Awaitable
 from functools import wraps
 from typing import Any, Callable, TypeVar, cast
 
-from typing_extensions import ParamSpec
+from typing_extensions import ParamSpec, TypeAlias
 
 T = TypeVar("T")
 P = ParamSpec("P")
+_CallableT: TypeAlias = Callable[..., Awaitable[Any]]
 
 
 class AsyncCache:
@@ -21,7 +22,7 @@ class AsyncCache:
         """Initialize the cache."""
         self.cache = {}
 
-    async def get(self, key: str, coro: Callable[..., Awaitable[Any]]) -> Any:
+    async def get(self, key: str, coro: _CallableT) -> Any:
         """Get a value from the cache or compute and store it."""
         if key not in self.cache:
             self.cache[key] = await coro()

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/helpers/factory.py

@@ -8,11 +8,14 @@ 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")
 
 
+@acache
 async def import_module(name: str) -> ModuleType:
     """Import module by name."""
     loop = asyncio.get_running_loop()
@@ -22,19 +25,15 @@ async def import_module(name: str) -> ModuleType:
 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)
-        instance = getattr(module, class_name)(**kwargs)
-        if not isinstance(instance, cls):
-            raise TypeError(
-                f"Expected instance of '{cls.__name__}', but got "
-                f"'{type(instance).__name__}' from '{class_name}'"
-            )
-
-        return instance
-    except Exception:
-        _LOGGER.exception("Failed to create instance for class path '%s'", class_path)
-        raise
+    module = await import_module(module_name)
+    instance = getattr(module, class_name)(**kwargs)
+    if not isinstance(instance, cls):
+        raise TypeError(
+            f"Expected instance of '{cls.__name__}', but got "
+            f"'{type(instance).__name__}' from '{class_name}'"
+        )
+
+    return instance
 
 
 __all__ = ["create_instance"]

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/helpers/schedule.py

@@ -15,13 +15,14 @@ from pyplumio.structures.schedules import collect_schedule_data
 
 TIME_FORMAT: Final = "%H:%M"
 
-MIDNIGHT: Final = "00:00"
+
+Time = Annotated[str, "Time string in %H:%M format"]
+
+MIDNIGHT: Final = Time("00:00")
 MIDNIGHT_DT = dt.datetime.strptime(MIDNIGHT, TIME_FORMAT)
 
 STEP = dt.timedelta(minutes=30)
 
-Time = Annotated[str, "Time string in %H:%M format"]
-
 
 def get_time(
     index: int, start: dt.datetime = MIDNIGHT_DT, step: dt.timedelta = STEP

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/helpers/timeout.py

@@ -23,6 +23,7 @@ def timeout(
         async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
             return await asyncio.wait_for(func(*args, **kwargs), timeout=seconds)
 
+        setattr(wrapper, "_has_timeout_seconds", seconds)
         return wrapper
 
     return decorator

{pyplumio-0.5.44 → pyplumio-0.5.49}/pyplumio/parameters/__init__.py

@@ -4,7 +4,6 @@ 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
@@ -12,16 +11,8 @@ 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,
-    ProductModel,
-    State,
-    UnitOfMeasurement,
-)
+from pyplumio.const import BYTE_UNDEFINED, STATE_OFF, STATE_ON, State, UnitOfMeasurement
 from pyplumio.frames import Request
-from pyplumio.structures.product_info import ProductInfo
 from pyplumio.utils import is_divisible
 
 if TYPE_CHECKING:
@@ -120,8 +111,8 @@ class Parameter(ABC):
             other = other.values
 
         if isinstance(other, ParameterValues):
-            handler = getattr(self.values, method_to_call)
-            return handler(other)
+            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)
@@ -486,53 +477,6 @@ class Switch(Parameter):
         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",
@@ -542,7 +486,6 @@ __all__ = [
     "Parameter",
     "ParameterDescription",
     "ParameterValues",
-    "patch_parameter_types",
     "State",
     "Switch",
     "SwitchDescription",

pyplumio-0.5.49/pyplumio/parameters/custom/__init__.py

@@ -0,0 +1,111 @@
+"""Custom parameters for products."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+import logging
+from typing import ClassVar, TypeVar, cast
+
+from pyplumio.helpers.factory import create_instance
+from pyplumio.parameters import ParameterDescription
+from pyplumio.structures.product_info import ProductInfo
+from pyplumio.utils import to_camelcase
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class Signature:
+    """Represents a product signature."""
+
+    __slots__ = ("id", "model")
+
+    id: int
+    model: str
+
+
+@dataclass
+class CustomParameter:
+    """Represents a custom parameter."""
+
+    __slot__ = ("original", "replacement")
+
+    original: str
+    replacement: ParameterDescription
+
+
+class CustomParameters:
+    """Represents a custom parameters."""
+
+    __slots__ = ("signature", "replacements")
+
+    signature: ClassVar[Signature]
+    replacements: ClassVar[Sequence[CustomParameter]]
+
+    def validate(self, product_info: ProductInfo) -> bool:
+        """Validate the product info."""
+        return (
+            self.signature.id == product_info.id
+            and self.signature.model == product_info.model
+        )
+
+
+async def _load_custom_parameters(
+    product_info: ProductInfo,
+) -> dict[str, ParameterDescription] | None:
+    """Load custom parameters."""
+    module_name = product_info.model.replace("-", "_").replace(" ", "_").lower()
+    module_path = f"parameters.custom.{module_name}"
+    class_name = to_camelcase(module_name).upper().replace("ECOMAX", "EcoMAX")
+    class_path = f"{module_path}.{class_name}"
+    try:
+        _LOGGER.debug(
+            "Trying to load custom parameters for %s from %s",
+            product_info.model,
+            class_path,
+        )
+        custom_parameters = await create_instance(class_path, cls=CustomParameters)
+        if not custom_parameters.validate(product_info):
+            raise ValueError
+    except (ImportError, TypeError, ValueError):
+        _LOGGER.debug("No custom parameters found for %s", product_info.model)
+        return None
+
+    return {
+        custom_parameter.original: custom_parameter.replacement
+        for custom_parameter in custom_parameters.replacements
+    }
+
+
+_DescriptionT = TypeVar("_DescriptionT", bound=ParameterDescription)
+
+
+async def inject_custom_parameters(
+    product_info: ProductInfo, parameter_types: list[_DescriptionT]
+) -> list[_DescriptionT]:
+    """Patch the parameter types based on the provided overrides."""
+    if custom_parameters := await _load_custom_parameters(product_info):
+        _LOGGER.debug("Custom parameters found for %s", product_info.model)
+        return cast(
+            list[_DescriptionT],
+            [
+                replacement
+                if original.name in custom_parameters
+                and (replacement := custom_parameters[original.name])
+                and (base_class := original.__class__.__bases__[0])
+                and isinstance(replacement, base_class)
+                else original
+                for original in parameter_types
+            ],
+        )
+
+    return parameter_types
+
+
+__all__ = (
+    "inject_custom_parameters",
+    "CustomParameters",
+    "CustomParameter",
+    "Signature",
+)