PyPlumIO 0.5.55__tar.gz → 0.5.56__tar.gz

{pyplumio-0.5.55 → pyplumio-0.5.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPlumIO
-Version: 0.5.55
+Version: 0.5.56
 Summary: PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.
 Author-email: Denis Paavilainen <denpa@denpa.pro>
 License: MIT License

{pyplumio-0.5.55 → pyplumio-0.5.56}/PyPlumIO.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPlumIO
-Version: 0.5.55
+Version: 0.5.56
 Summary: PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.
 Author-email: Denis Paavilainen <denpa@denpa.pro>
 License: MIT License

{pyplumio-0.5.55 → pyplumio-0.5.56}/PyPlumIO.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ docs/source/mixers_thermostats.rst
 docs/source/protocol.rst
 docs/source/reading.rst
 docs/source/schedules.rst
+docs/source/statistics.rst
 docs/source/writing.rst
 images/ecomax.png
 images/rs485.png

{pyplumio-0.5.55 → pyplumio-0.5.56}/docs/source/index.rst

@@ -51,6 +51,7 @@ Documentation
    callbacks
    mixers_thermostats
    schedules
+   statistics
    protocol
    frames
 

pyplumio-0.5.56/docs/source/statistics.rst

@@ -0,0 +1,40 @@
+Statistics
+==========
+
+About Statistics
+----------------
+
+Since PyPlumIO v0.5.56, you can access statistics via following property.
+
+.. autoattribute:: pyplumio.protocol.AsyncProtocol.statistics
+
+Statistics contain transfer data consisting of number of received/sent frames and bytes
+as well as datetime of when connection was established, when connection was lost and
+number of connection loss event.
+
+.. autoclass:: pyplumio.protocol.Statistics
+
+The `devices` property of statistics class of also contains a list of
+device statistics objects.
+
+.. autoclass:: pyplumio.protocol.DeviceStatistics
+
+Statistics Examples
+-------------------
+
+You can easily access statistic object via proxy call through Connection object
+as in example below.
+
+.. code-block:: python
+
+    import asyncio
+
+    import pyplumio
+
+    async def main():
+        """Read the current heating temperature."""
+        async with pyplumio.open_tcp_connection("localhost", 8899) as conn:
+            print(conn.statistic)
+
+
+    asyncio.run(main())

{pyplumio-0.5.55 → pyplumio-0.5.56}/pyplumio/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.5.55'
-__version_tuple__ = version_tuple = (0, 5, 55)
+__version__ = version = '0.5.56'
+__version_tuple__ = version_tuple = (0, 5, 56)
 
-__commit_id__ = commit_id = 'gb0f1bcbdf'
+__commit_id__ = commit_id = 'g61d991c97'

{pyplumio-0.5.55 → pyplumio-0.5.56}/pyplumio/protocol.py

@@ -5,9 +5,12 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 import asyncio
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from datetime import datetime
 import logging
+from typing import Any, Final, Literal
 
+from dataslots import dataslots
 from typing_extensions import TypeAlias
 
 from pyplumio.const import ATTR_CONNECTED, ATTR_SETUP, DeviceType
@@ -23,6 +26,7 @@ from pyplumio.structures.network_info import (
     NetworkInfo,
     WirelessParameters,
 )
+from pyplumio.structures.regulator_data import ATTR_REGDATA
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -114,6 +118,87 @@ class Queues:
         await asyncio.gather(self.read.join(), self.write.join())
 
 
+NEVER: Final = "never"
+
+
+@dataslots
+@dataclass
+class Statistics:
+    """Represents a connection statistics.
+
+    :param received_bytes: Number of received bytes. Resets on reconnect.
+    :type received_bytes: int
+    :param received_frames: Number of received frames. Resets on reconnect.
+    :type received_frames: int
+    :param sent_bytes: Number of sent bytes.  Resets on reconnect.
+    :type sent_bytes: int
+    :param sent_frames: Number of sent frames. Resets on reconnect.
+    :type sent_frames: int
+    :param failed_frames: Number of failed frames. Resets on reconnect.
+    :type failed_frames: int
+    :param connected_since: Datetime object representing connection time.
+    :type connected_since: datetime.datetime | Literal["never"]
+    :param connection_loss_at: Datetime object representing last connection loss event.
+    :type connection_loss_at: datetime.datetime | Literal["never"]
+    :param connection_losses: Number of connection lost event.
+    :type connection_losses: int
+    :param devices: Contains list of statistics for connected devices.
+    :type devices: list[DeviceStatistics]
+    """
+
+    received_bytes: int = 0
+    received_frames: int = 0
+    sent_bytes: int = 0
+    sent_frames: int = 0
+    failed_frames: int = 0
+    connected_since: datetime | Literal["never"] = NEVER
+    connection_loss_at: datetime | Literal["never"] = NEVER
+    connection_losses: int = 0
+    devices: list[DeviceStatistics] = field(default_factory=list)
+
+    def update_transfer_statistics(
+        self, sent: Frame | None = None, received: Frame | None = None
+    ) -> None:
+        """Update transfer statistics."""
+        if sent:
+            self.sent_bytes += sent.length
+            self.sent_frames += 1
+
+        if received:
+            self.received_bytes += received.length
+            self.received_frames += 1
+
+    def reset_transfer_statistics(self) -> None:
+        """Reset transfer statistics."""
+        self.sent_bytes = 0
+        self.sent_frames = 0
+        self.received_bytes = 0
+        self.received_frames = 0
+        self.failed_frames = 0
+
+
+@dataslots
+@dataclass
+class DeviceStatistics:
+    """Represents a device statistics.
+
+    :param name: Device name.
+    :type name: str
+    :param connected_since: Datetime object representing connection time.
+    :type connected_since: datetime.datetime | Literal["never"]
+    :param last_seen: Datetime object representing time when device was last seen.
+    :type last_seen: datetime.datetime | Literal["never"]
+    """
+
+    name: str
+    connected_since: datetime | Literal["never"] = NEVER
+    last_seen: datetime | Literal["never"] = NEVER
+
+    async def update_last_seen(self, data: Any) -> None:
+        """Update last seen property."""
+        self.last_seen = datetime.now()
+
+
 class AsyncProtocol(Protocol, EventManager[PhysicalDevice]):
     """Represents an async protocol.
 
@@ -134,6 +219,7 @@ class AsyncProtocol(Protocol, EventManager[PhysicalDevice]):
     _network: NetworkInfo
     _queues: Queues
     _entry_lock: asyncio.Lock
+    _statistics: Statistics
 
     def __init__(
         self,
@@ -150,6 +236,7 @@ class AsyncProtocol(Protocol, EventManager[PhysicalDevice]):
         )
         self._queues = Queues(read=asyncio.Queue(), write=asyncio.Queue())
         self._entry_lock = asyncio.Lock()
+        self._statistics = Statistics()
 
     def connection_established(
         self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
@@ -172,6 +259,8 @@ class AsyncProtocol(Protocol, EventManager[PhysicalDevice]):
             device.dispatch_nowait(ATTR_CONNECTED, True)
 
         self.connected.set()
+        self.statistics.reset_transfer_statistics()
+        self.statistics.connected_since = datetime.now()
 
     async def _connection_close(self) -> None:
         """Close the connection if it is established."""
@@ -200,19 +289,27 @@ class AsyncProtocol(Protocol, EventManager[PhysicalDevice]):
         self, queues: Queues, reader: FrameReader, writer: FrameWriter
     ) -> None:
         """Handle frame reads and writes."""
+        statistics = self.statistics
         await self.connected.wait()
         while self.connected.is_set():
             try:
+                request = None
                 if not queues.write.empty():
-                    await writer.write(await queues.write.get())
+                    request = await queues.write.get()
+                    await writer.write(request)
                     queues.write.task_done()
 
                 if response := await reader.read():
                     queues.read.put_nowait(response)
 
+                statistics.update_transfer_statistics(request, response)
+
             except ProtocolError as e:
+                statistics.failed_frames += 1
                 _LOGGER.debug("Can't process received frame: %s", e)
             except (OSError, asyncio.TimeoutError):
+                statistics.connection_losses += 1
+                statistics.connection_loss_at = datetime.now()
                 self.create_task(self.connection_lost())
                 break
             except Exception:
@@ -239,8 +336,21 @@ class AsyncProtocol(Protocol, EventManager[PhysicalDevice]):
                 device.dispatch_nowait(ATTR_CONNECTED, True)
                 device.dispatch_nowait(ATTR_SETUP, True)
                 await self.dispatch(name, device)
+                self.statistics.devices.append(
+                    device_statistics := DeviceStatistics(
+                        name=name,
+                        connected_since=datetime.now(),
+                        last_seen=datetime.now(),
+                    )
+                )
+                device.subscribe(ATTR_REGDATA, device_statistics.update_last_seen)
 
         return self.data[name]
 
+    @property
+    def statistics(self) -> Statistics:
+        """Return the statistics."""
+        return self._statistics
+
 
-__all__ = ["Protocol", "DummyProtocol", "AsyncProtocol"]
+__all__ = ["Protocol", "DummyProtocol", "AsyncProtocol", "Statistics"]

{pyplumio-0.5.55 → pyplumio-0.5.56}/tests/test_protocol.py

@@ -1,7 +1,10 @@
 """Contains tests for the protocol classes."""
 
 import asyncio
+from dataclasses import asdict
+from datetime import datetime, timedelta
 import logging
+from typing import cast
 from unittest.mock import AsyncMock, Mock, PropertyMock, call, patch
 
 import pytest
@@ -15,19 +18,20 @@ from pyplumio.exceptions import (
     UnknownDeviceError,
     UnknownFrameError,
 )
-from pyplumio.frames import Response
+from pyplumio.frames import Request, Response
 from pyplumio.frames.requests import (
     CheckDeviceRequest,
     ProgramVersionRequest,
     StartMasterRequest,
 )
-from pyplumio.protocol import AsyncProtocol, DummyProtocol, Queues
+from pyplumio.protocol import AsyncProtocol, DummyProtocol, Queues, Statistics
 from pyplumio.stream import FrameReader, FrameWriter
 from pyplumio.structures.network_info import (
     EthernetParameters,
     NetworkInfo,
     WirelessParameters,
 )
+from pyplumio.structures.regulator_data import ATTR_REGDATA
 
 
 @pytest.fixture(name="skip_asyncio_create_task")
@@ -102,9 +106,30 @@ async def test_dummy_protocol() -> None:
     assert not dummy_protocol.connected.is_set()
 
 
+def test_statistics() -> None:
+    """Test statistics dataclass."""
+    statistics = Statistics()
+    statistics.update_transfer_statistics(sent=Request())
+    statistics.update_transfer_statistics(received=Response())
+    statistics.failed_frames = 1
+    assert statistics.connected_since == "never"
+    assert statistics.sent_bytes == 10
+    assert statistics.sent_frames == 1
+    assert statistics.received_bytes == 10
+    assert statistics.received_frames == 1
+    assert statistics.failed_frames == 1
+    statistics.reset_transfer_statistics()
+    assert statistics.sent_bytes == 0
+    assert statistics.sent_frames == 0
+    assert statistics.received_bytes == 0
+    assert statistics.received_frames == 0
+    assert statistics.failed_frames == 0
+
+
 @patch("pyplumio.protocol.AsyncProtocol.create_task")
 @patch("pyplumio.protocol.AsyncProtocol.frame_consumer", new_callable=Mock)
 @patch("pyplumio.protocol.AsyncProtocol.frame_producer", new_callable=Mock)
+@pytest.mark.usefixtures("frozen_time")
 def test_async_protocol_connection_established(
     mock_frame_producer, mock_frame_consumer, mock_create_task
 ) -> None:
@@ -124,8 +149,13 @@ def test_async_protocol_connection_established(
     async_protocol.data = {"ecomax": mock_ecomax}
 
     # Test connection established.
-    with patch.object(
-        async_protocol, "_queues", Queues(mock_read_queue, mock_write_queue)
+    with (
+        patch.object(
+            async_protocol, "_queues", Queues(mock_read_queue, mock_write_queue)
+        ),
+        patch(
+            "pyplumio.protocol.Statistics.reset_transfer_statistics"
+        ) as mock_reset_transfer_statistics,
     ):
         async_protocol.connection_established(mock_stream_reader, mock_stream_writer)
 
@@ -144,6 +174,10 @@ def test_async_protocol_connection_established(
     # Check that devices were notified.
     mock_ecomax.dispatch_nowait.assert_called_once_with(ATTR_CONNECTED, True)
 
+    # Check statistics.
+    mock_reset_transfer_statistics.assert_called_once()
+    assert async_protocol.statistics.connected_since == datetime.now()
+
 
 async def test_async_protocol_connection_lost() -> None:
     """Test losing the connection with an async protocol."""
@@ -236,7 +270,9 @@ async def test_async_protocol_shutdown(
     assert async_protocol.writer is None
 
 
-@pytest.mark.usefixtures("skip_asyncio_events", "skip_asyncio_create_task")
+@pytest.mark.usefixtures(
+    "skip_asyncio_events", "skip_asyncio_create_task", "frozen_time"
+)
 async def test_async_protocol_frame_producer(
     async_protocol: AsyncProtocol, caplog
 ) -> None:
@@ -267,7 +303,8 @@ async def test_async_protocol_frame_producer(
             *(True for _ in range(len(responses) - 1)),
         )
     )
-    mock_write_queue.get = AsyncMock(return_value="test_request")
+    request = Request()
+    mock_write_queue.get = AsyncMock(return_value=request)
 
     with (
         patch("pyplumio.devices.ecomax.EcoMAX"),
@@ -315,7 +352,7 @@ async def test_async_protocol_frame_producer(
         ),
     ]
 
-    mock_writer.write.assert_awaited_once_with("test_request")
+    mock_writer.write.assert_awaited_once_with(request)
     mock_write_queue.task_done.assert_called_once()
     mock_read_queue.put_nowait.assert_called_once_with(success)
     mock_connection_lost.assert_called_once()
@@ -323,6 +360,19 @@ async def test_async_protocol_frame_producer(
     assert mock_write_queue.empty.call_count == 8
     assert mock_reader.read.await_count == 8
 
+    # Check statistics.
+    assert asdict(async_protocol.statistics) == {
+        "connected_since": "never",
+        "received_bytes": 10,
+        "received_frames": 1,
+        "sent_bytes": 10,
+        "sent_frames": 1,
+        "failed_frames": 5,
+        "connection_losses": 1,
+        "connection_loss_at": datetime.now(),
+        "devices": [],
+    }
+
 
 @patch("pyplumio.frames.requests.CheckDeviceRequest.response")
 @patch("pyplumio.frames.requests.ProgramVersionRequest.response")
@@ -332,6 +382,7 @@ async def test_async_protocol_frame_consumer(
     mock_device_available_response,
     async_protocol: AsyncProtocol,
     caplog,
+    frozen_time,
 ) -> None:
     """Test a frame consumer task within an async protocol."""
     mock_read_queue = Mock(spec=asyncio.Queue)
@@ -394,3 +445,14 @@ async def test_async_protocol_frame_consumer(
         ]
     )
     assert mock_read_queue.task_done.call_count == 2
+
+    # Test statistics.
+    connected_since = datetime.now()
+    frozen_time.tick(timedelta(seconds=10))
+    ecomax = cast(EcoMAX, async_protocol.get_nowait("ecomax"))
+    await ecomax.dispatch(ATTR_REGDATA, True)
+    assert asdict(async_protocol.statistics.devices[0]) == {
+        "name": "ecomax",
+        "connected_since": connected_since,
+        "last_seen": datetime.now(),
+    }