PyPlumIO 0.5.5__py3-none-any.whl → 0.5.7__py3-none-any.whl

pyplumio/helpers/parameter.py

@@ -58,7 +58,7 @@ def _normalize_parameter_value(value: ParameterValueType) -> int:
 class ParameterValues:
     """Represents a parameter values."""
 
-    __slots__ = "value", "min_value", "max_value"
+    __slots__ = ("value", "min_value", "max_value")
 
     value: int
     min_value: int
@@ -81,13 +81,13 @@ class BinaryParameterDescription(ParameterDescription):
 class Parameter(ABC):
     """Represents a parameter."""
 
-    __slots__ = ("device", "values", "description", "_index", "_pending_update")
+    __slots__ = ("device", "values", "description", "_pending_update", "_index")
 
     device: Device
     values: ParameterValues
     description: ParameterDescription
-    _index: int
     _pending_update: bool
+    _index: int
 
     def __init__(
         self,
@@ -98,8 +98,8 @@ class Parameter(ABC):
     ):
         """Initialize a new parameter."""
         self.device = device
-        self.description = description
         self.values = values
+        self.description = description
         self._pending_update = False
         self._index = index
 
@@ -235,19 +235,29 @@ class BinaryParameter(Parameter):
     """Represents binary device parameter."""
 
     async def turn_on(self) -> bool:
-        """Set a parameter value to 'on'."""
+        """Set a parameter value to 'on'.
+
+        :return: `True` if parameter was successfully turned on, `False`
+            otherwise.
+        :rtype: bool
+        """
         return await self.set(STATE_ON)
 
     async def turn_off(self) -> bool:
-        """Set a parameter value to 'off'."""
+        """Set a parameter value to 'off'.
+
+        :return: `True` if parameter was successfully turned off, `False`
+            otherwise.
+        :rtype: bool
+        """
         return await self.set(STATE_OFF)
 
     def turn_on_nowait(self) -> None:
-        """Set a parameter state to 'on' without waiting."""
+        """Set a parameter value to 'on' without waiting."""
         self.set_nowait(STATE_ON)
 
     def turn_off_nowait(self) -> None:
-        """Set a parameter state to 'off' without waiting."""
+        """Set a parameter value to 'off' without waiting."""
         self.set_nowait(STATE_OFF)
 
     @property

pyplumio/helpers/schedule.py

@@ -8,7 +8,7 @@ import math
 from typing import Final, Literal
 
 from pyplumio.const import STATE_OFF, STATE_ON
-from pyplumio.devices import Addressable
+from pyplumio.devices import AddressableDevice
 from pyplumio.helpers.factory import factory
 from pyplumio.structures.schedules import collect_schedule_data
 
@@ -136,7 +136,7 @@ class Schedule(Iterable):
     )
 
     name: str
-    device: Addressable
+    device: AddressableDevice
     monday: ScheduleDay
     tuesday: ScheduleDay
     wednesday: ScheduleDay

pyplumio/helpers/task_manager.py

@@ -9,8 +9,6 @@ from typing import Any
 class TaskManager:
     """Represents a task manager."""
 
-    __slots__ = ("_tasks",)
-
     _tasks: set[asyncio.Task]
 
     def __init__(self):

pyplumio/helpers/typing.py

@@ -7,7 +7,6 @@ from typing import Any, Literal, Protocol, Union
 ParameterValueType = Union[int, float, bool, Literal["off"], Literal["on"]]
 EventDataType = dict[Union[str, int], Any]
 EventCallbackType = Callable[[Any], Awaitable[Any]]
-UndefinedType = Literal["undefined"]
 
 
 class SupportsSubtraction(Protocol):

pyplumio/protocol.py

@@ -1,13 +1,14 @@
 """Contains protocol representation."""
 from __future__ import annotations
 
+from abc import ABC, abstractmethod
 import asyncio
 from collections.abc import Awaitable, Callable
 import logging
 from typing import Final, cast
 
 from pyplumio.const import ATTR_CONNECTED, DeviceType
-from pyplumio.devices import Addressable, get_device_handler_and_name
+from pyplumio.devices import AddressableDevice, get_device_handler_and_name
 from pyplumio.exceptions import (
     FrameDataError,
     FrameError,
@@ -30,24 +31,14 @@ _LOGGER = logging.getLogger(__name__)
 CONSUMERS_NUMBER: Final = 2
 
 
-class Protocol(EventManager):
-    """Represents protocol."""
-
-    __slots__ = (
-        "writer",
-        "reader",
-        "connected",
-        "_network",
-        "_queues",
-        "_connection_lost_callback",
-    )
+class Protocol(ABC):
+    """Represents a protocol."""
 
     writer: FrameWriter | None
     reader: FrameReader | None
     connected: asyncio.Event
-    _network: NetworkInfo
-    _queues: tuple[asyncio.Queue, asyncio.Queue]
     _connection_lost_callback: Callable[[], Awaitable[None]] | None
+    _network: NetworkInfo
 
     def __init__(
         self,
@@ -60,60 +51,107 @@ class Protocol(EventManager):
         self.writer = None
         self.reader = None
         self.connected = asyncio.Event()
-        read_queue: asyncio.Queue = asyncio.Queue()
-        write_queue: asyncio.Queue = asyncio.Queue()
-        self._queues = (read_queue, write_queue)
         self._connection_lost_callback = connection_lost_callback
         if ethernet_parameters is None:
-            ethernet_parameters = EthernetParameters()
+            ethernet_parameters = EthernetParameters(status=False)
 
         if wireless_parameters is None:
-            wireless_parameters = WirelessParameters()
+            wireless_parameters = WirelessParameters(status=False)
 
         self._network = NetworkInfo(eth=ethernet_parameters, wlan=wireless_parameters)
 
-    async def frame_producer(
-        self, read_queue: asyncio.Queue, write_queue: asyncio.Queue
-    ) -> None:
-        """Handle frame reads and writes."""
-        await self.connected.wait()
-        while self.connected.is_set():
-            try:
-                if write_queue.qsize() > 0:
-                    await self.writer.write(await write_queue.get())
-                    write_queue.task_done()
+    async def close_writer(self) -> None:
+        """Ensure that writer is closed."""
+        if not self.writer:
+            return
 
-                if (response := await self.reader.read()) is not None:
-                    read_queue.put_nowait(
-                        (self.setup_device_entry(response.sender), response)
-                    )
+        try:
+            await self.writer.close()
+        except (OSError, asyncio.TimeoutError):
+            # Ignore any connection errors when closing the writer.
+            pass
+        finally:
+            self.writer = None
 
-            except FrameDataError as e:
-                _LOGGER.warning("Incorrect payload: %s", e)
-            except ReadError as e:
-                _LOGGER.debug("Read error: %s", e)
-            except UnknownDeviceError as e:
-                _LOGGER.debug("Unknown device: %s", e)
-            except FrameError as e:
-                _LOGGER.debug("Can't process received frame: %s", e)
-            except (OSError, asyncio.TimeoutError):
-                self.create_task(self.connection_lost())
-                break
-            except Exception as e:  # pylint: disable=broad-except
-                _LOGGER.exception(e)
+    @abstractmethod
+    def connection_established(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ):
+        """Called when connection is established."""
 
-    async def frame_consumer(self, read_queue: asyncio.Queue) -> None:
-        """Handle frame processing."""
-        await self.connected.wait()
-        while self.connected.is_set():
-            device, frame = cast(tuple[Addressable, Frame], await read_queue.get())
-            device.handle_frame(frame)
-            read_queue.task_done()
+    @abstractmethod
+    async def connection_lost(self):
+        """Called when connection is lost."""
+
+    @abstractmethod
+    async def shutdown(self):
+        """Shutdown the protocol."""
+
+
+class DummyProtocol(Protocol):
+    """Represents a dummy protocol.
+
+    This protocol sets frame reader and writer as attributes, then
+    sets connected event and does nothing.
+    """
+
+    def connection_established(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ):
+        """Called when connection is established."""
+        self.reader = FrameReader(reader)
+        self.writer = FrameWriter(writer)
+        self.connected.set()
+
+    async def connection_lost(self):
+        """Called when connection is lost."""
+        if self.connected.is_set():
+            self.connected.clear()
+            await self.close_writer()
+            if self._connection_lost_callback is not None:
+                await self._connection_lost_callback()
+
+    async def shutdown(self):
+        """Shutdown the protocol."""
+        if self.connected.is_set():
+            self.connected.clear()
+            await self.close_writer()
+
+
+class AsyncProtocol(Protocol, EventManager):
+    """Represents an async protocol.
+
+    This protocol implements producer-consumers pattern using
+    asyncio queues.
+
+    The frame producer tries to read frames from write queue, if any
+    available, and sends them to the device via frame writer.
+
+    It reads stream via frame reader, creates device handler entry
+    and puts received frame and handler into the read queue.
+
+    Frame consumers reads handler-frame tuples from the read queue and
+    sends frame to respective handler for further processing.
+    """
+
+    _queues: tuple[asyncio.Queue, asyncio.Queue]
+
+    def __init__(
+        self,
+        connection_lost_callback: Callable[[], Awaitable[None]] | None = None,
+        ethernet_parameters: EthernetParameters | None = None,
+        wireless_parameters: WirelessParameters | None = None,
+    ):
+        """Initialize a new default protocol."""
+        super().__init__(
+            connection_lost_callback, ethernet_parameters, wireless_parameters
+        )
+        self._queues = (asyncio.Queue(), asyncio.Queue())
 
     def connection_established(
         self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
     ):
-        """Start consumers and producer tasks."""
+        """Called when connection is established."""
         self.reader = FrameReader(reader)
         self.writer = FrameWriter(writer)
         read_queue, write_queue = self.queues
@@ -128,27 +166,69 @@ class Protocol(EventManager):
         self.connected.set()
 
     async def connection_lost(self):
-        """Shutdown consumers and call connection lost callback."""
+        """Called when connection is lost."""
         if self.connected.is_set():
             self.connected.clear()
             for device in self.data.values():
                 # Notify devices about connection loss.
                 await device.dispatch(ATTR_CONNECTED, False)
 
-            await self._remove_writer()
+            await self.close_writer()
             if self._connection_lost_callback is not None:
                 await self._connection_lost_callback()
 
     async def shutdown(self):
         """Shutdown protocol tasks."""
         await asyncio.gather(*[queue.join() for queue in self.queues])
-        await super().shutdown()
+        await super(Protocol, self).shutdown()
         for device in self.data.values():
             await device.shutdown()
 
-        await self._remove_writer()
+        if self.connected.is_set():
+            self.connected.clear()
+            await self.close_writer()
+
+    async def frame_producer(
+        self, read_queue: asyncio.Queue, write_queue: asyncio.Queue
+    ) -> None:
+        """Handle frame reads and writes."""
+        await self.connected.wait()
+        while self.connected.is_set():
+            try:
+                if write_queue.qsize() > 0:
+                    await self.writer.write(await write_queue.get())
+                    write_queue.task_done()
+
+                if (response := await self.reader.read()) is not None:
+                    read_queue.put_nowait(
+                        (self.setup_device_entry(response.sender), response)
+                    )
+
+            except FrameDataError as e:
+                _LOGGER.warning("Incorrect payload: %s", e)
+            except ReadError as e:
+                _LOGGER.debug("Read error: %s", e)
+            except UnknownDeviceError as e:
+                _LOGGER.debug("Unknown device: %s", e)
+            except FrameError as e:
+                _LOGGER.debug("Can't process received frame: %s", e)
+            except (OSError, asyncio.TimeoutError):
+                self.create_task(self.connection_lost())
+                break
+            except Exception as e:  # pylint: disable=broad-except
+                _LOGGER.exception(e)
+
+    async def frame_consumer(self, read_queue: asyncio.Queue) -> None:
+        """Handle frame processing."""
+        await self.connected.wait()
+        while self.connected.is_set():
+            device, frame = cast(
+                tuple[AddressableDevice, Frame], await read_queue.get()
+            )
+            device.handle_frame(frame)
+            read_queue.task_done()
 
-    def setup_device_entry(self, device_type: DeviceType) -> Addressable:
+    def setup_device_entry(self, device_type: DeviceType) -> AddressableDevice:
         """Setup the device entry."""
         handler, name = get_device_handler_and_name(device_type)
         if name not in self.data:
@@ -159,23 +239,14 @@ class Protocol(EventManager):
     def _create_device_entry(self, name: str, handler: str) -> None:
         """Create the device entry."""
         write_queue = self.queues[1]
-        device: Addressable = factory(handler, queue=write_queue, network=self._network)
+        device: AddressableDevice = factory(
+            handler, queue=write_queue, network=self._network
+        )
         device.dispatch_nowait(ATTR_CONNECTED, True)
         self.create_task(device.async_setup())
         self.data[name] = device
         self.set_event(name)
 
-    async def _remove_writer(self):
-        """Attempt to gracefully remove the frame writer."""
-        if self.writer:
-            try:
-                await self.writer.close()
-            except (OSError, asyncio.TimeoutError):
-                # Ignore any connection errors when closing the writer.
-                pass
-            finally:
-                self.writer = None
-
     @property
     def queues(self) -> tuple[asyncio.Queue, asyncio.Queue]:
         """Protocol queues."""

pyplumio/stream.py

@@ -23,8 +23,6 @@ _LOGGER = logging.getLogger(__name__)
 class FrameWriter:
     """Represents a frame writer."""
 
-    __slots__ = ("_writer",)
-
     _writer: StreamWriter
 
     def __init__(self, writer: StreamWriter):
@@ -50,8 +48,6 @@ class FrameWriter:
 class FrameReader:
     """Represents a frame reader."""
 
-    __slots__ = ("_reader",)
-
     _reader: StreamReader
 
     def __init__(self, reader: StreamReader):

pyplumio/structures/alerts.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from datetime import datetime
+from functools import lru_cache
 from typing import Any, Final, Generator
 
 from pyplumio.const import AlertType
@@ -12,28 +13,21 @@ from pyplumio.structures import StructureDecoder
 from pyplumio.utils import ensure_dict
 
 ATTR_ALERTS: Final = "alerts"
-ATTR_YEAR: Final = "year"
-ATTR_MONTH: Final = "month"
-ATTR_DAY: Final = "day"
-ATTR_HOUR: Final = "hour"
-ATTR_MINUTE: Final = "minute"
-ATTR_SECOND: Final = "second"
-
-ALERT_SIZE: Final = 9
 
 
+@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 kwarg for a datetime class."""
+        """Convert seconds to a kwargs for a datetime class."""
         intervals: tuple[tuple[str, int, int], ...] = (
-            (ATTR_YEAR, 32140800, 2000),  # 60sec * 60min * 24h * 31d * 12m
-            (ATTR_MONTH, 2678400, 1),  # 60sec * 60min * 24h * 31d
-            (ATTR_DAY, 86400, 1),  # 60sec * 60min * 24h
-            (ATTR_HOUR, 3600, 0),  # 60sec * 60min
-            (ATTR_MINUTE, 60, 0),
-            (ATTR_SECOND, 1, 0),
+            ("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),
         )
 
         for name, count, offset in intervals:

pyplumio/structures/ecomax_parameters.py

@@ -13,7 +13,7 @@ from pyplumio.const import (
     ProductType,
     UnitOfMeasurement,
 )
-from pyplumio.devices import Addressable
+from pyplumio.devices import AddressableDevice
 from pyplumio.frames import Request
 from pyplumio.helpers.factory import factory
 from pyplumio.helpers.parameter import (
@@ -38,7 +38,9 @@ ECOMAX_PARAMETER_SIZE: Final = 3
 class EcomaxParameter(Parameter):
     """Represents an ecoMAX parameter."""
 
-    device: Addressable
+    __slots__ = ()
+
+    device: AddressableDevice
     description: EcomaxParameterDescription
 
     async def set(self, value: ParameterValueType, retries: int = 5) -> bool:

pyplumio/structures/network_info.py

@@ -22,18 +22,30 @@ NETWORK_INFO_SIZE: Final = 25
 class EthernetParameters:
     """Represents an ethernet parameters."""
 
+    #: IP address.
     ip: str = DEFAULT_IP
+
+    #: IP subnet mask.
     netmask: str = DEFAULT_NETMASK
+
+    #: Gateway IP address.
     gateway: str = DEFAULT_IP
-    status: bool = False
+
+    #: Connection status. Parameters will be ignored if set to False.
+    status: bool = True
 
 
 @dataclass
 class WirelessParameters(EthernetParameters):
     """Represents a wireless network parameters."""
 
+    #: Wireless Service Set IDentifier.
     ssid: str = ""
+
+    #: Wireless encryption standard.
     encryption: EncryptionType = EncryptionType.NONE
+
+    #: Wireless signal strength in percentage.
     signal_quality: int = 100
 
 

pyplumio/structures/regulator_data.py

@@ -3,13 +3,13 @@ from __future__ import annotations
 
 from typing import Final
 
-from pyplumio.devices import Addressable
+from pyplumio.devices import AddressableDevice
 from pyplumio.helpers.data_types import BitArray, DataType
 from pyplumio.helpers.event_manager import EventManager
 from pyplumio.helpers.typing import EventDataType
 from pyplumio.structures import StructureDecoder
-from pyplumio.structures.data_schema import ATTR_SCHEMA
 from pyplumio.structures.frame_versions import FrameVersionsStructure
+from pyplumio.structures.regulator_data_schema import ATTR_REGDATA_SCHEMA
 from pyplumio.utils import ensure_dict
 
 ATTR_REGDATA: Final = "regdata"
@@ -60,8 +60,8 @@ class RegulatorDataStructure(StructureDecoder):
         )
 
         sender = self.frame.sender
-        if isinstance(sender, Addressable) and (
-            schema := sender.get_nowait(ATTR_SCHEMA, [])
+        if isinstance(sender, AddressableDevice) and (
+            schema := sender.get_nowait(ATTR_REGDATA_SCHEMA, [])
         ):
             data.setdefault(ATTR_REGDATA, RegulatorData()).load(
                 {

pyplumio/structures/{data_schema.py → regulator_data_schema.py}

@@ -8,13 +8,11 @@ from pyplumio.helpers.typing import EventDataType
 from pyplumio.structures import StructureDecoder
 from pyplumio.utils import ensure_dict
 
-ATTR_SCHEMA: Final = "schema"
+ATTR_REGDATA_SCHEMA: Final = "regdata_schema"
 
-BLOCK_SIZE: Final = 3
 
-
-class DataSchemaStructure(StructureDecoder):
-    """Represents a data schema structure."""
+class RegulatorDataSchemaStructure(StructureDecoder):
+    """Represents a regulator data schema structure."""
 
     _offset: int
 
@@ -39,7 +37,7 @@ class DataSchemaStructure(StructureDecoder):
             ensure_dict(
                 data,
                 {
-                    ATTR_SCHEMA: [
+                    ATTR_REGDATA_SCHEMA: [
                         self._unpack_block(message) for _ in range(blocks.value)
                     ]
                 },

pyplumio/structures/schedules.py

@@ -8,7 +8,7 @@ from itertools import chain
 from typing import Final
 
 from pyplumio.const import ATTR_PARAMETER, ATTR_SCHEDULE, ATTR_SWITCH, ATTR_TYPE
-from pyplumio.devices import Addressable, Device
+from pyplumio.devices import AddressableDevice, Device
 from pyplumio.exceptions import FrameDataError
 from pyplumio.frames import Request
 from pyplumio.helpers.factory import factory
@@ -80,7 +80,7 @@ class ScheduleParameter(Parameter):
 
     __slots__ = ()
 
-    device: Addressable
+    device: AddressableDevice
 
     @property
     def request(self) -> Request:

pyplumio/structures/temperatures.py

@@ -47,8 +47,6 @@ TEMPERATURES: tuple[str, ...] = (
     ATTR_AIR_OUT_TEMP,
 )
 
-TEMPERATURE_SIZE: Final = 5
-
 
 class TemperaturesStructure(StructureDecoder):
     """Represents a temperatures data structure."""

pyplumio/structures/thermostat_parameters.py

@@ -11,7 +11,7 @@ from pyplumio.const import (
     ATTR_VALUE,
     UnitOfMeasurement,
 )
-from pyplumio.devices import Addressable
+from pyplumio.devices import AddressableDevice
 from pyplumio.frames import Request
 from pyplumio.helpers.factory import factory
 from pyplumio.helpers.parameter import (
@@ -211,7 +211,7 @@ class ThermostatParametersStructure(StructureDecoder):
         """Decode bytes and return message data and offset."""
         sender = self.frame.sender
         if (
-            isinstance(sender, Addressable)
+            isinstance(sender, AddressableDevice)
             and (thermostats := sender.get_nowait(ATTR_THERMOSTATS_CONNECTED, 0)) == 0
         ):
             return (