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

pyplumio/helpers/parameter.py

@@ -2,15 +2,17 @@
 
 from __future__ import annotations
 
-from abc import ABC
+from abc import ABC, abstractmethod
 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 dataslots import dataslots
+from typing_extensions import TypeAlias
 
 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 +22,9 @@ _LOGGER = logging.getLogger(__name__)
 SET_TIMEOUT: Final = 5
 SET_RETRIES: Final = 5
 
+ParameterValueType: TypeAlias = Union[int, float, bool, Literal["off", "on"]]
+ParameterT = TypeVar("ParameterT", bound="Parameter")
+
 
 def unpack_parameter(
     data: bytearray, offset: int = 0, size: int = 1
@@ -45,13 +50,10 @@ def check_parameter(data: bytearray) -> bool:
 
 
 def _normalize_parameter_value(value: ParameterValueType) -> int:
-    """Normalize a parameter value to an integer."""
-    if isinstance(value, str):
+    """Normalize a parameter value."""
+    if value in (STATE_OFF, STATE_ON):
         return 1 if value == STATE_ON else 0
 
-    if isinstance(value, ParameterValues):
-        value = value.value
-
     return int(value)
 
 
@@ -66,58 +68,54 @@ class ParameterValues:
     max_value: int
 
 
+@dataslots
 @dataclass
-class ParameterDescription(ABC):
+class ParameterDescription:
     """Represents a parameter description."""
 
     name: str
-    unit_of_measurement: UnitOfMeasurement | Literal["%"] | None = None
-
-
-@dataclass
-class BinaryParameterDescription(ParameterDescription, ABC):
-    """Represent a binary parameter description."""
 
 
 class Parameter(ABC):
-    """Represents a parameter."""
+    """Represents a base 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)
+        other = other.value if isinstance(other, ParameterValues) else other
+        return handler(_normalize_parameter_value(other))
 
     def __int__(self) -> int:
         """Return an integer representation of parameter's value."""
@@ -163,15 +161,7 @@ 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
-
-    async def set(self, value: ParameterValueType, retries: int = SET_RETRIES) -> bool:
+    async def set(self, value: Any, retries: int = SET_RETRIES) -> bool:
         """Set a parameter value."""
         if (value := _normalize_parameter_value(value)) == self.values.value:
             return True
@@ -181,16 +171,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())
@@ -199,9 +187,10 @@ class Parameter(ABC):
 
         return True
 
-    def set_nowait(self, value: ParameterValueType, retries: int = SET_RETRIES) -> None:
-        """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:
@@ -209,17 +198,88 @@ class Parameter(ABC):
         return self._pending_update
 
     @property
-    def value(self) -> ParameterValueType:
-        """Return the parameter value."""
+    def values(self) -> ParameterValues:
+        """Return the parameter values."""
+        return self._values
+
+    @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
+
+    @property
+    @abstractmethod
+    def value(self) -> Any:
+        """Return the value."""
+
+    @property
+    @abstractmethod
+    def min_value(self) -> Any:
+        """Return the minimum allowed value."""
+
+    @property
+    @abstractmethod
+    def max_value(self) -> Any:
+        """Return the maximum allowed value."""
+
+    @abstractmethod
+    async def create_request(self) -> Request:
+        """Create a request to change the parameter."""
+
+
+@dataslots
+@dataclass
+class NumberDescription(ParameterDescription):
+    """Represents a parameter description."""
+
+    unit_of_measurement: UnitOfMeasurement | Literal["%"] | None = None
+
+
+class Number(Parameter):
+    """Represents a number."""
+
+    __slots__ = ()
+
+    description: NumberDescription
+
+    async def set(self, value: int | float, retries: int = SET_RETRIES) -> bool:
+        """Set a parameter value."""
+        return await super().set(value, retries)
+
+    def set_nowait(self, value: int | float, retries: int = SET_RETRIES) -> None:
+        """Set a parameter value without waiting."""
+        self.device.create_task(self.set(value, retries))
+
+    async def create_request(self) -> Request:
+        """Create a request to change the number."""
+        return Request()
+
+    @property
+    def value(self) -> int | float:
+        """Return the value."""
         return self.values.value
 
     @property
-    def min_value(self) -> ParameterValueType:
+    def min_value(self) -> int | float:
         """Return the minimum allowed value."""
         return self.values.min_value
 
     @property
-    def max_value(self) -> ParameterValueType:
+    def max_value(self) -> int | float:
         """Return the maximum allowed value."""
         return self.values.max_value
 
@@ -229,11 +289,33 @@ class Parameter(ABC):
         return self.description.unit_of_measurement
 
 
-class BinaryParameter(Parameter):
-    """Represents binary device parameter."""
+@dataslots
+@dataclass
+class SwitchDescription(ParameterDescription):
+    """Represents a switch description."""
+
+
+class Switch(Parameter):
+    """Represents a switch."""
+
+    __slots__ = ()
+
+    description: SwitchDescription
+
+    async def set(
+        self, value: bool | Literal["off", "on"], retries: int = SET_RETRIES
+    ) -> bool:
+        """Set a parameter value."""
+        return await super().set(value, retries)
+
+    def set_nowait(
+        self, value: bool | Literal["off", "on"], retries: int = SET_RETRIES
+    ) -> None:
+        """Set a switch value without waiting."""
+        self.device.create_task(self.set(value, retries))
 
     async def turn_on(self) -> bool:
-        """Set a parameter value to 'on'.
+        """Set a switch value to 'on'.
 
         :return: `True` if parameter was successfully turned on, `False`
             otherwise.
@@ -242,7 +324,7 @@ class BinaryParameter(Parameter):
         return await self.set(STATE_ON)
 
     async def turn_off(self) -> bool:
-        """Set a parameter value to 'off'.
+        """Set a switch value to 'off'.
 
         :return: `True` if parameter was successfully turned off, `False`
             otherwise.
@@ -251,24 +333,28 @@ class BinaryParameter(Parameter):
         return await self.set(STATE_OFF)
 
     def turn_on_nowait(self) -> None:
-        """Set a parameter value to 'on' without waiting."""
+        """Set a switch value to 'on' without waiting."""
         self.set_nowait(STATE_ON)
 
     def turn_off_nowait(self) -> None:
-        """Set a parameter value to 'off' without waiting."""
+        """Set a switch value to 'off' without waiting."""
         self.set_nowait(STATE_OFF)
 
+    async def create_request(self) -> Request:
+        """Create a request to change the switch."""
+        return Request()
+
     @property
-    def value(self) -> ParameterValueType:
-        """Return the parameter value."""
+    def value(self) -> Literal["off", "on"]:
+        """Return the value."""
         return STATE_ON if self.values.value == 1 else STATE_OFF
 
     @property
-    def min_value(self) -> ParameterValueType:
+    def min_value(self) -> Literal["off"]:
         """Return the minimum allowed value."""
         return STATE_OFF
 
     @property
-    def max_value(self) -> ParameterValueType:
+    def max_value(self) -> Literal["on"]:
         """Return the maximum allowed value."""
         return STATE_ON

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

@@ -8,9 +8,11 @@ from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 import logging
 
+from typing_extensions import TypeAlias
+
 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 +25,8 @@ from pyplumio.structures.network_info import (
 
 _LOGGER = logging.getLogger(__name__)
 
+_Callback: TypeAlias = Callable[[], Awaitable[None]]
+
 
 class Protocol(ABC):
     """Represents a protocol."""
@@ -30,7 +34,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 +51,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 +90,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,15 +105,15 @@ 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."""
         await asyncio.gather(self.read.join(), self.write.join())
 
 
-class AsyncProtocol(Protocol, EventManager):
+class AsyncProtocol(Protocol, EventManager[AddressableDevice]):
     """Represents an async protocol.
 
     This protocol implements producer-consumers pattern using
@@ -127,7 +130,6 @@ class AsyncProtocol(Protocol, EventManager):
     """
 
     consumers_count: int
-    data: dict[str, AddressableDevice]
     _network: NetworkInfo
     _queues: Queues
 
@@ -154,37 +156,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 +207,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 +215,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 +232,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,