Merge remote-tracking branch 'origin/main' into formatting-changes

# Conflicts:
#	src/powersensor_local/__init__.py
#	src/powersensor_local/plug_api.py
#	src/powersensor_local/plug_listener.py

Author: bookman-dius

src/powersensor_local/__init__.py

@@ -1,20 +1,37 @@
 """Direct (non-cloud) interface to Powersensor devices
 
-This package contains two abstraction layers:
+This package contains various abstractions for interacting with Powersensor
+devices on the local network.
 
-• PowersensorDevices is the main API layer
-• PowersensorListener provides a lower-level abstraction
+The recommended approach is to use mDNS to discover plugs via their service
+"_powersensor._tcp.local", and then instantiate a PlugApi to obtain the event
+stream from each plug.
 
-These are both available within this namespace, or specifically as
-devices.PowersensorDevices and listener.PowersensorListener
+A legacy abstraction is also provided via PowersensorDevices, which uses
+an older way of discovering plugs.
 
-The 'events' and 'rawfirehose' modules are helper utilities provided as
-debug aids, which get installed under the names ps-events and ps-rawfirehose
-respectively.
+Lower-level interfaces are available in the PlugListener and
+PowersensorListener classed, though they are not recommended for general use.
+
+Additionally a convience abstraction for translating some of the events into
+a household view is available in VirtualHousehold.
+
+Quick overview:
+• PlugApi is the recommended API layer
+• PlugListener is the lower-level abstraction used by PlugApi
+• PowersensorDevices is the legacy main API layer
+• PowersensorListener provides a (legacy) lower-level abstraction
+• VirtualHousehold can be used to translate events into a household view
+
+The 'plugevents' and 'rawplug' modules are helper utilities provided as
+debug aids, which get installed under the names ps-plugevents and ps-rawplug
+respectively. There are also the legacy 'events' and 'rawfirehose' debug aids
+which get installed under the names ps-events and ps-rawfirehose respectively.
 """
-__all__ = [ 'devices', 'listener', 'plug_api', 'plug_listener' ]
+__all__ = [ 'devices', 'listener', 'plug_api', 'plug_listener', 'virtual_household', 'PlugApi' ]
 __version__ = "2.0.0"
 from .devices import PowersensorDevices
 from .listener import PowersensorListener
 from .plug_api import PlugApi
 from .plug_listener import PlugListener
+from .virtual_household import VirtualHousehold

src/powersensor_local/plug_api.py

@@ -1,6 +1,5 @@
 import sys
 from pathlib import Path
-
 project_root = str(Path(__file__).parents[1])
 if project_root not in sys.path:
     sys.path.append(project_root)
@@ -53,20 +52,21 @@ async def disconnect(self):
     async def _on_message(self, _, message):
         """Translates the raw message and emits the resulting messages, if any.
 
-        Also synthesizes 'now_relaying_for' messages as needed.
+        Also synthesises 'now_relaying_for' messages as needed.
         """
+        evs = None
         try:
             evs = translate_raw_message(message, self._mac)
         except KeyError:
             # Ignore malformed messages
             return
 
-        message_mac = message.get('mac')
-        if message_mac != self._mac and message_mac not in self._seen:
-            self._seen.add(message_mac)
+        msgmac = message.get('mac')
+        if msgmac != self._mac and msgmac not in self._seen:
+            self._seen.add(msgmac)
             # We want to emit this prior to events with data
             ev = {
-                'mac': message_mac,
+                'mac': msgmac,
                 'device_type': message.get('device'),
                 'role': message.get('role'),
             }

src/powersensor_local/plug_listener.py

@@ -1,21 +1,16 @@
 import asyncio
 import json
+import socket
+import time
 
 import sys
 from pathlib import Path
-
 project_root = str(Path(__file__).parents[1])
 if project_root not in sys.path:
     sys.path.append(project_root)
 
 from powersensor_local.async_event_emitter import AsyncEventEmitter
 
-
-async def _send_subscribe(writer):
-    writer.write(b'subscribe(60)\n')
-    await writer.drain()
-
-
 class PlugListener(AsyncEventEmitter):
     """An interface class for accessing the event stream from a single plug.
     The following events may be emitted:
@@ -24,8 +19,11 @@ class PlugListener(AsyncEventEmitter):
       - ("disconnected") When a connection is dropped, be it intentional or not.
       - ("message",{...}) For each event message received from the plug. The
       plug's JSON message is decoded into a dict which is passed as the second
-      argument to the registered event handler(s). The event handlers must be
-      async.
+      argument to the registered event handler(s).
+      - ("malformed",line) If JSON decoding of a message fails. The raw line
+      is included (as a byte string).
+
+      The event handlers must be async.
     """
 
     def __init__(self, ip, port=49476):
@@ -72,14 +70,16 @@ async def _close_connection(self):
             await self.emit('disconnected')
 
     async def _do_connection(self, backoff = 0):
+        if self._disconnecting:
+            return
         if backoff < 9:
             backoff += 1
         try:
             await self.emit('connecting')
             reader, writer = await asyncio.open_connection(self._ip, self._port)
             self._connection = (reader, writer)
 
-            await _send_subscribe(writer)
+            await self._send_subscribe(writer)
             backoff = 1
 
             await self.emit('connected')
@@ -91,7 +91,7 @@ async def _do_connection(self, backoff = 0):
             # Handle disconnection and retry with exponential backoff
             await self._close_connection()
             if self._disconnecting:
-                return None
+                return
             await asyncio.sleep(min(5 * 60, 2**backoff * 1))
             return await self._do_connection(backoff)
 
@@ -105,10 +105,14 @@ async def _process_line(self, reader, writer):
                 typ = message['type']
                 if typ == 'subscription':
                     if message['subtype'] == 'warning':
-                        await _send_subscribe(writer)
+                        await self._send_subscribe(writer)
                 elif typ == 'discovery':
                     pass
                 else:
                     await self.emit('message', message)
-            except json.decoder.JSONDecodeError as ex:
-                print(f"JSON error {ex} from {data}")
+            except (json.decoder.JSONDecodeError) as ex:
+                await self.emit('malformed', data)
+
+    async def _send_subscribe(self, writer):
+        writer.write(b'subscribe(60)\n')
+        await writer.drain()

src/powersensor_local/virtual_household.py

@@ -1,6 +1,12 @@
 """Abstraction for producing a household view."""
 
-from async_event_emitter import AsyncEventEmitter
+import sys
+from pathlib import Path
+project_root = str(Path(__file__).parents[1])
+if project_root not in sys.path:
+    sys.path.append(project_root)
+
+from powersensor_local.async_event_emitter import AsyncEventEmitter
 from dataclasses import dataclass
 from typing import Optional