PyPlumIO 0.5.21__py3-none-any.whl → 0.5.22__py3-none-any.whl

pyplumio/helpers/event_manager.py

@@ -3,18 +3,23 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable
-from typing import Any
+from collections.abc import Callable, Coroutine
+from typing import Any, TypeVar
 
 from pyplumio.helpers.task_manager import TaskManager
 
+Callback = Callable[[Any], Coroutine[Any, Any, Any]]
+CallbackT = TypeVar("CallbackT", bound=Callback)
+
 
 class EventManager(TaskManager):
     """Represents an event manager."""
 
+    __slots__ = ("data", "_events", "_callbacks")
+
     data: dict[str, Any]
     _events: dict[str, asyncio.Event]
-    _callbacks: dict[str, list[Callable[[Any], Awaitable[Any]]]]
+    _callbacks: dict[str, list[Callback]]
 
     def __init__(self) -> None:
         """Initialize a new event manager."""
@@ -75,23 +80,23 @@ class EventManager(TaskManager):
         except KeyError:
             return default
 
-    def subscribe(self, name: str, callback: Callable[[Any], Awaitable[Any]]) -> None:
+    def subscribe(self, name: str, callback: CallbackT) -> CallbackT:
         """Subscribe a callback to the event.
 
         :param name: Event name or ID
         :type name: str
         :param callback: A coroutine callback function, that will be
             awaited on the with the event data as an argument.
-        :type callback: Callable[[Any], Awaitable[Any]]
+        :type callback: Callback
+        :return: A reference to the callback, that can be used
+            with `EventManager.unsubscribe()`.
+        :rtype: Callback
         """
-        if name not in self._callbacks:
-            self._callbacks[name] = []
+        callbacks = self._callbacks.setdefault(name, [])
+        callbacks.append(callback)
+        return callback
 
-        self._callbacks[name].append(callback)
-
-    def subscribe_once(
-        self, name: str, callback: Callable[[Any], Awaitable[Any]]
-    ) -> None:
+    def subscribe_once(self, name: str, callback: Callback) -> Callback:
         """Subscribe a callback to the event once.
 
         Callback will be unsubscribed after single event.
@@ -100,17 +105,20 @@ class EventManager(TaskManager):
         :type name: str
         :param callback: A coroutine callback function, that will be
             awaited on the with the event data as an argument.
-        :type callback: Callable[[Any], Awaitable[Any]]
+        :type callback: Callback
+        :return: A reference to the callback, that can be used
+            with `EventManager.unsubscribe()`.
+        :rtype: Callback
         """
 
-        async def _callback(value: Any) -> Any:
+        async def _call_once(value: Any) -> Any:
             """Unsubscribe callback from the event and calls it."""
-            self.unsubscribe(name, _callback)
+            self.unsubscribe(name, _call_once)
             return await callback(value)
 
-        self.subscribe(name, _callback)
+        return self.subscribe(name, _call_once)
 
-    def unsubscribe(self, name: str, callback: Callable[[Any], Awaitable[Any]]) -> None:
+    def unsubscribe(self, name: str, callback: Callback) -> bool:
         """Usubscribe a callback from the event.
 
         :param name: Event name or ID
@@ -118,18 +126,22 @@ class EventManager(TaskManager):
         :param callback: A coroutine callback function, previously
             subscribed to an event using ``subscribe()`` or
             ``subscribe_once()`` methods.
-        :type callback: Callable[[Any], Awaitable[Any]]
+        :type callback: Callback
+        :return: `True` if callback is found, `False` otherwise.
+        :rtype: bool
         """
         if name in self._callbacks and callback in self._callbacks[name]:
             self._callbacks[name].remove(callback)
+            return True
+
+        return False
 
     async def dispatch(self, name: str, value: Any) -> None:
         """Call registered callbacks and dispatch the event."""
-        if name in self._callbacks:
-            callbacks = self._callbacks[name].copy()
-            for callback in callbacks:
-                return_value = await callback(value)
-                value = return_value if return_value is not None else value
+        if callbacks := self._callbacks.get(name, None):
+            for callback in list(callbacks):
+                result = await callback(value)
+                value = result if result is not None else value
 
         self.data[name] = value
         self.set_event(name)
@@ -140,9 +152,8 @@ class EventManager(TaskManager):
 
     async def load(self, data: dict[str, Any]) -> None:
         """Load event data."""
-        self.data = data
         await asyncio.gather(
-            *[self.dispatch(name, value) for name, value in data.items()]
+            *(self.dispatch(name, value) for name, value in data.items())
         )
 
     def load_nowait(self, data: dict[str, Any]) -> None:

pyplumio/helpers/parameter.py

@@ -6,11 +6,10 @@ from abc import ABC
 import asyncio
 from dataclasses import dataclass
 import logging
-from typing import TYPE_CHECKING, Any, Final, Literal
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeVar, Union
 
 from pyplumio.const import BYTE_UNDEFINED, STATE_OFF, STATE_ON, UnitOfMeasurement
 from pyplumio.frames import Request
-from pyplumio.helpers.typing import ParameterValueType
 
 if TYPE_CHECKING:
     from pyplumio.devices import Device
@@ -20,6 +19,8 @@ _LOGGER = logging.getLogger(__name__)
 SET_TIMEOUT: Final = 5
 SET_RETRIES: Final = 5
 
+ParameterValueType = Union[int, float, bool, Literal["off"], Literal["on"]]
+
 
 def unpack_parameter(
     data: bytearray, offset: int = 0, size: int = 1
@@ -82,42 +83,42 @@ class BinaryParameterDescription(ParameterDescription, ABC):
 class Parameter(ABC):
     """Represents a parameter."""
 
-    __slots__ = ("device", "values", "description", "_pending_update", "_index")
+    __slots__ = ("device", "description", "_pending_update", "_index", "_values")
 
     device: Device
-    values: ParameterValues
     description: ParameterDescription
     _pending_update: bool
     _index: int
+    _values: ParameterValues
 
     def __init__(
         self,
         device: Device,
-        values: ParameterValues,
         description: ParameterDescription,
+        values: ParameterValues | None = None,
         index: int = 0,
     ):
         """Initialize a new parameter."""
         self.device = device
-        self.values = values
         self.description = description
         self._pending_update = False
         self._index = index
+        self._values = values if values else ParameterValues(0, 0, 0)
 
     def __repr__(self) -> str:
         """Return a serializable string representation."""
         return (
             f"{self.__class__.__name__}("
             f"device={self.device.__class__.__name__}, "
-            f"values={self.values}, "
             f"description={self.description}, "
+            f"values={self.values}, "
             f"index={self._index})"
         )
 
     def _call_relational_method(self, method_to_call: str, other: Any) -> Any:
         """Call a specified relational method."""
-        func = getattr(self.values.value, method_to_call)
-        return func(_normalize_parameter_value(other))
+        handler = getattr(self.values.value, method_to_call)
+        return handler(_normalize_parameter_value(other))
 
     def __int__(self) -> int:
         """Return an integer representation of parameter's value."""
@@ -163,10 +164,6 @@ class Parameter(ABC):
         """Compare if parameter value is less that other."""
         return self._call_relational_method("__lt__", other)
 
-    async def _confirm_update(self, parameter: Parameter) -> None:
-        """Set parameter as no longer pending update."""
-        self._pending_update = False
-
     async def create_request(self) -> Request:
         """Create a request to change the parameter."""
         raise NotImplementedError
@@ -181,16 +178,14 @@ class Parameter(ABC):
                 f"Value must be between '{self.min_value}' and '{self.max_value}'"
             )
 
-        self.values.value = value
+        self._values.value = value
         self._pending_update = True
-        self.device.subscribe_once(self.description.name, self._confirm_update)
         while self.pending_update:
             if retries <= 0:
                 _LOGGER.error(
                     "Timed out while trying to set '%s' parameter",
                     self.description.name,
                 )
-                self.device.unsubscribe(self.description.name, self._confirm_update)
                 return False
 
             await self.device.queue.put(await self.create_request())
@@ -203,11 +198,21 @@ class Parameter(ABC):
         """Set a parameter value without waiting."""
         self.device.create_task(self.set(value, retries))
 
+    def update(self, values: ParameterValues) -> None:
+        """Update the parameter values."""
+        self._values = values
+        self._pending_update = False
+
     @property
     def pending_update(self) -> bool:
         """Check if parameter is pending update on the device."""
         return self._pending_update
 
+    @property
+    def values(self) -> ParameterValues:
+        """Return the parameter values."""
+        return self._values
+
     @property
     def value(self) -> ParameterValueType:
         """Return the parameter value."""
@@ -228,6 +233,28 @@ class Parameter(ABC):
         """Return the unit of measurement."""
         return self.description.unit_of_measurement
 
+    @classmethod
+    def create_or_update(
+        cls: type[ParameterT],
+        device: Device,
+        description: ParameterDescription,
+        values: ParameterValues,
+        **kwargs: Any,
+    ) -> ParameterT:
+        """Create new parameter or update parameter values."""
+        parameter: ParameterT | None = device.get_nowait(description.name, None)
+        if parameter and isinstance(parameter, cls):
+            parameter.update(values)
+        else:
+            parameter = cls(
+                device=device, description=description, values=values, **kwargs
+            )
+
+        return parameter
+
+
+ParameterT = TypeVar("ParameterT", bound=Parameter)
+
 
 class BinaryParameter(Parameter):
     """Represents binary device parameter."""

pyplumio/helpers/task_manager.py

@@ -10,15 +10,20 @@ from typing import Any
 class TaskManager:
     """Represents a task manager."""
 
+    __slots__ = ("_tasks",)
+
     _tasks: set[asyncio.Task]
 
     def __init__(self) -> None:
         """Initialize a new task manager."""
+        super().__init__()
         self._tasks = set()
 
-    def create_task(self, coro: Coroutine[Any, Any, Any]) -> asyncio.Task:
+    def create_task(
+        self, coro: Coroutine[Any, Any, Any], name: str | None = None
+    ) -> asyncio.Task:
         """Create asyncio task and store a reference for it."""
-        task = asyncio.create_task(coro)
+        task = asyncio.create_task(coro, name=name)
         self._tasks.add(task)
         task.add_done_callback(self._tasks.discard)
         return task

pyplumio/helpers/timeout.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Awaitable, Callable, Coroutine
 from functools import wraps
-import logging
 from typing import Any, TypeVar
 
 from typing_extensions import ParamSpec
@@ -13,8 +12,6 @@ from typing_extensions import ParamSpec
 T = TypeVar("T")
 P = ParamSpec("P")
 
-_LOGGER = logging.getLogger(__name__)
-
 
 def timeout(
     seconds: int,

pyplumio/helpers/uid.py

@@ -7,6 +7,7 @@ from typing import Final
 
 CRC: Final = 0xA3A3
 POLYNOMIAL: Final = 0xA001
+BASE5_KEY: Final = "0123456789ABCDEFGHIJKLMNZPQRSTUV"
 
 
 def decode_uid(buffer: bytes) -> str:
@@ -16,11 +17,10 @@ def decode_uid(buffer: bytes) -> str:
 
 def _base5(buffer: bytes) -> str:
     """Encode bytes to a base5 encoded string."""
-    key_string = "0123456789ABCDEFGHIJKLMNZPQRSTUV"
     number = int.from_bytes(buffer, byteorder="little")
     output = ""
     while number:
-        output = key_string[number & 0b00011111] + output
+        output = BASE5_KEY[number & 0b00011111] + output
         number >>= 5
 
     return output

pyplumio/protocol.py

@@ -10,7 +10,7 @@ import logging
 
 from pyplumio.const import ATTR_CONNECTED, DeviceType
 from pyplumio.devices import AddressableDevice
-from pyplumio.exceptions import FrameError, ReadError, UnknownDeviceError
+from pyplumio.exceptions import ProtocolError
 from pyplumio.frames import Frame
 from pyplumio.frames.requests import StartMasterRequest
 from pyplumio.helpers.event_manager import EventManager
@@ -23,6 +23,8 @@ from pyplumio.structures.network_info import (
 
 _LOGGER = logging.getLogger(__name__)
 
+_Callback = Callable[[], Awaitable[None]]
+
 
 class Protocol(ABC):
     """Represents a protocol."""
@@ -30,7 +32,7 @@ class Protocol(ABC):
     connected: asyncio.Event
     reader: FrameReader | None
     writer: FrameWriter | None
-    _on_connection_lost: set[Callable[[], Awaitable[None]]]
+    _on_connection_lost: set[_Callback]
 
     def __init__(self) -> None:
         """Initialize a new protocol."""
@@ -47,7 +49,7 @@ class Protocol(ABC):
             self.writer = None
 
     @property
-    def on_connection_lost(self) -> set[Callable[[], Awaitable[None]]]:
+    def on_connection_lost(self) -> set[_Callback]:
         """Return the callbacks that'll be called on connection lost."""
         return self._on_connection_lost
 
@@ -86,8 +88,7 @@ class DummyProtocol(Protocol):
         if self.connected.is_set():
             self.connected.clear()
             await self.close_writer()
-            for callback in self.on_connection_lost:
-                await callback()
+            await asyncio.gather(*(callback() for callback in self.on_connection_lost))
 
     async def shutdown(self) -> None:
         """Shutdown the protocol."""
@@ -102,8 +103,8 @@ class Queues:
 
     __slots__ = ("read", "write")
 
-    read: asyncio.Queue
-    write: asyncio.Queue
+    read: asyncio.Queue[Frame]
+    write: asyncio.Queue[Frame]
 
     async def join(self) -> None:
         """Wait for queues to finish."""
@@ -154,37 +155,42 @@ class AsyncProtocol(Protocol, EventManager):
         self.writer = FrameWriter(writer)
         self._queues.write.put_nowait(StartMasterRequest(recipient=DeviceType.ECOMAX))
         self.create_task(
-            self.frame_producer(self._queues, reader=self.reader, writer=self.writer)
+            self.frame_producer(self._queues, reader=self.reader, writer=self.writer),
+            name="frame_producer_task",
         )
-        for _ in range(self.consumers_count):
-            self.create_task(self.frame_consumer(self._queues.read))
+        for consumer in range(self.consumers_count):
+            self.create_task(
+                self.frame_consumer(self._queues.read),
+                name=f"frame_consumer_task ({consumer})",
+            )
 
         for device in self.data.values():
             device.dispatch_nowait(ATTR_CONNECTED, True)
 
         self.connected.set()
 
-    async def connection_lost(self) -> None:
-        """Close the writer and call connection lost callbacks."""
-        if not self.connected.is_set():
-            return
-
+    async def _connection_close(self) -> None:
+        """Close the connection if it is established."""
         self.connected.clear()
-        await self.close_writer()
         await asyncio.gather(
-            *[device.dispatch(ATTR_CONNECTED, False) for device in self.data.values()]
+            *(device.dispatch(ATTR_CONNECTED, False) for device in self.data.values())
         )
-        await asyncio.gather(*[callback() for callback in self.on_connection_lost])
+        await self.close_writer()
+
+    async def connection_lost(self) -> None:
+        """Close the connection and call connection lost callbacks."""
+        if self.connected.is_set():
+            await self._connection_close()
+            await asyncio.gather(*(callback() for callback in self.on_connection_lost))
 
     async def shutdown(self) -> None:
-        """Shutdown protocol tasks."""
+        """Shutdown the protocol and close the connection."""
         await self._queues.join()
         self.cancel_tasks()
         await self.wait_until_done()
-        await asyncio.gather(*[device.shutdown() for device in self.data.values()])
         if self.connected.is_set():
-            self.connected.clear()
-            await self.close_writer()
+            await self._connection_close()
+            await asyncio.gather(*(device.shutdown() for device in self.data.values()))
 
     async def frame_producer(
         self, queues: Queues, reader: FrameReader, writer: FrameWriter
@@ -200,7 +206,7 @@ class AsyncProtocol(Protocol, EventManager):
                 if (response := await reader.read()) is not None:
                     queues.read.put_nowait(response)
 
-            except (ReadError, UnknownDeviceError, FrameError) as e:
+            except ProtocolError as e:
                 _LOGGER.debug("Can't process received frame: %s", e)
             except (OSError, asyncio.TimeoutError):
                 self.create_task(self.connection_lost())
@@ -208,11 +214,11 @@ class AsyncProtocol(Protocol, EventManager):
             except Exception:
                 _LOGGER.exception("Unexpected exception")
 
-    async def frame_consumer(self, queue: asyncio.Queue) -> None:
+    async def frame_consumer(self, queue: asyncio.Queue[Frame]) -> None:
         """Handle frame processing."""
         await self.connected.wait()
         while self.connected.is_set():
-            frame: Frame = await queue.get()
+            frame = await queue.get()
             device = await self.get_device_entry(frame.sender)
             device.handle_frame(frame)
             queue.task_done()
@@ -225,7 +231,7 @@ class AsyncProtocol(Protocol, EventManager):
                 device_type, queue=self._queues.write, network=self._network
             )
             device.dispatch_nowait(ATTR_CONNECTED, True)
-            self.create_task(device.async_setup())
+            self.create_task(device.async_setup(), name=f"device_setup_task ({name})")
             self.set_event(name)
             self.data[name] = device
 

pyplumio/stream.py

@@ -100,8 +100,8 @@ class FrameReader:
         """Read the frame and return corresponding handler object.
 
         Raise pyplumio.ReadError on unexpected frame length or
-        incomplete frame and pyplumio.ChecksumError on incorrect frame
-        checksum.
+        incomplete frame and pyplumio. Raise ChecksumError on incorrect
+        frame checksum.
         """
         (
             header_bytes,

pyplumio/structures/alerts.py

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 from collections.abc import Generator
+from contextlib import suppress
 from dataclasses import dataclass
 from datetime import datetime
 from functools import lru_cache
-from typing import Any, Final
+from typing import Any, Final, Literal, NamedTuple
 
 from pyplumio.const import AlertType
 from pyplumio.helpers.data_types import UnsignedInt
@@ -19,27 +20,40 @@ ATTR_TOTAL_ALERTS: Final = "total_alerts"
 MAX_UINT32: Final = 4294967295
 
 
-@lru_cache(maxsize=10)
-def _convert_to_datetime(seconds: int) -> datetime:
-    """Convert timestamp to a datetime object."""
-
-    def _seconds_to_datetime_args(seconds: int) -> Generator[Any, None, None]:
-        """Convert seconds to a kwargs for a datetime class."""
-        intervals: tuple[tuple[str, int, int], ...] = (
-            ("year", 32140800, 2000),  # 60sec * 60min * 24h * 31d * 12m
-            ("month", 2678400, 1),  # 60sec * 60min * 24h * 31d
-            ("day", 86400, 1),  # 60sec * 60min * 24h
-            ("hour", 3600, 0),  # 60sec * 60min
-            ("minute", 60, 0),
-            ("second", 1, 0),
-        )
+class DateTimeInterval(NamedTuple):
+    """Represents an alert time interval."""
+
+    name: Literal["year", "month", "day", "hour", "minute", "second"]
+    seconds: int
+    offset: int = 0
+
 
-        for name, count, offset in intervals:
-            value = seconds // count
-            seconds -= value * count
+DATETIME_INTERVALS: tuple[DateTimeInterval, ...] = (
+    DateTimeInterval("year", seconds=60 * 60 * 24 * 31 * 12, offset=2000),
+    DateTimeInterval("month", seconds=60 * 60 * 24 * 31, offset=1),
+    DateTimeInterval("day", seconds=60 * 60 * 24, offset=1),
+    DateTimeInterval("hour", seconds=60 * 60),
+    DateTimeInterval("minute", seconds=60),
+    DateTimeInterval("second", seconds=1),
+)
+
+
+@lru_cache(maxsize=10)
+def _seconds_to_datetime(timestamp: int) -> datetime:
+    """Convert timestamp to a datetime object.
+
+    The ecoMAX controller stores alert time as a special timestamp value
+    in seconds counted from Jan 1st, 2000.
+    """
+
+    def _datetime_kwargs(timestamp: int) -> Generator[Any, None, None]:
+        """Yield a tuple, that represents a single datetime kwarg."""
+        for name, seconds, offset in DATETIME_INTERVALS:
+            value = timestamp // seconds
+            timestamp -= value * seconds
             yield name, (value + offset)
 
-    return datetime(**dict(_seconds_to_datetime_args(seconds)))
+    return datetime(**dict(_datetime_kwargs(timestamp)))
 
 
 @dataclass
@@ -62,24 +76,20 @@ class AlertsStructure(StructureDecoder):
 
     def _unpack_alert(self, message: bytearray) -> Alert:
         """Unpack an alert."""
-        try:
-            code = message[self._offset]
-            code = AlertType(code)
-        except ValueError:
-            pass
-
+        code = message[self._offset]
         self._offset += 1
         from_seconds = UnsignedInt.from_bytes(message, self._offset)
         self._offset += from_seconds.size
         to_seconds = UnsignedInt.from_bytes(message, self._offset)
         self._offset += to_seconds.size
-
-        from_dt = _convert_to_datetime(from_seconds.value)
+        from_dt = _seconds_to_datetime(from_seconds.value)
         to_dt = (
             None
             if to_seconds.value == MAX_UINT32
-            else _convert_to_datetime(to_seconds.value)
+            else _seconds_to_datetime(to_seconds.value)
         )
+        with suppress(ValueError):
+            code = AlertType(code)
 
         return Alert(code, from_dt, to_dt)
 
@@ -90,12 +100,11 @@ class AlertsStructure(StructureDecoder):
         total_alerts = message[offset + 0]
         start = message[offset + 1]
         end = message[offset + 2]
-
+        self._offset = offset + 3
         if end == 0:
             # No alerts found.
-            return ensure_dict(data, {ATTR_TOTAL_ALERTS: total_alerts}), offset + 3
+            return ensure_dict(data, {ATTR_TOTAL_ALERTS: total_alerts}), self._offset
 
-        self._offset = offset + 3
         return (
             ensure_dict(
                 data,