python-mobius 0.10.1__tar.gz → 0.10.2__tar.gz

{python_mobius-0.10.1 → python_mobius-0.10.2}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.10.2
+
+- Mesh peer discovery can raise its error (`raise_errors=True`) instead
+  of returning an empty list on failure.
+
 ## 0.10.1
 
 - Fixed lights not being read through a gateway: the poll's reply was too

{python_mobius-0.10.1 → python_mobius-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.10.1
+Version: 0.10.2
 Summary: Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)
 Project-URL: Homepage, https://code.r3pek.org/r3pek/python-mobius
 Project-URL: Documentation, https://code.r3pek.org/r3pek/python-mobius/src/branch/main/documentation

{python_mobius-0.10.1 → python_mobius-0.10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.10.1"
+version = "0.10.2"
 description = "Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)"
 readme = "README.md"
 license = { text = "GPL-2.0-only" }

{python_mobius-0.10.1 → python_mobius-0.10.2}/src/mobius/__init__.py

@@ -87,7 +87,7 @@ from .mob import (
     MAX_PUMP_PRIMITIVE_SIZE,
 )
 
-__version__ = "0.10.1"
+__version__ = "0.10.2"
 
 __all__ = [
     "__version__",

{python_mobius-0.10.1 → python_mobius-0.10.2}/src/mobius/device.py

@@ -1842,7 +1842,7 @@ class MobiusDevice:
             return None
         return raw
 
-    async def discover_mesh_peers(self) -> list[MeshPeer]:
+    async def discover_mesh_peers(self, raise_errors: bool = False) -> list[MeshPeer]:
         """
         Mesh peers from the ShortAddressArray/SerialNumberArray/
         DeviceModelArray (3700/3701/3702) parallel arrays, with addresses
@@ -1852,10 +1852,12 @@ class MobiusDevice:
         UnsupportedAttribute and this returns []. Whether the connected
         device lists itself is not known. Empty slots (serial
         "00000000000000") and short entries are skipped. Returns [] on any
-        failure.
+        failure, or raises it with raise_errors=True.
         """
         own_address = await self.get_own_mesh_address()
         if own_address is None:
+            if raise_errors:
+                raise IOError("own mesh address (MeshLocalAddresses) not readable")
             return []
         prefix = mesh_local_prefix_from_own_address(own_address)
 
@@ -1864,6 +1866,8 @@ class MobiusDevice:
             models_raw = await self.get_attribute(C2Attribute.DeviceModelArray, index=0, count=ALL_ELEMENTS)
             shorts_raw = await self.get_attribute(C2Attribute.ShortAddressArray, index=0, count=ALL_ELEMENTS)
         except Exception:
+            if raise_errors:
+                raise
             return []
 
         peers: list[MeshPeer] = []
@@ -1882,7 +1886,7 @@ class MobiusDevice:
             ))
         return peers
 
-    async def discover_networked_thread_devices(self) -> list[MeshPeer]:
+    async def discover_networked_thread_devices(self, raise_errors: bool = False) -> list[MeshPeer]:
         """
         Every device on this device's Thread mesh, including itself, from
         MLPrefix (2128) and NetworkedThreadDevices (1001). Supported more
@@ -1896,7 +1900,8 @@ class MobiusDevice:
           12-13  model id, i16 LE
           14-27  serial, ASCII
         Empty slots are all zeros and are skipped, as are entries of any
-        other length. Returns [] on any failure.
+        other length. Returns [] on any failure, or raises it with
+        raise_errors=True.
         """
         try:
             mlprefix_raw = await self.get_attribute(C2Attribute.MLPrefix)
@@ -1904,8 +1909,15 @@ class MobiusDevice:
                 C2Attribute.NetworkedThreadDevices, index=0, count=ALL_ELEMENTS,
             )
         except Exception:
+            if raise_errors:
+                raise
             return []
         if not mlprefix_raw or len(mlprefix_raw[0]) != 24:
+            if raise_errors:
+                raise IOError(
+                    f"unexpected MLPrefix: {mlprefix_raw[0].hex() if mlprefix_raw else 'empty'} "
+                    f"(expected 24 bytes)"
+                )
             return []
         prefix = mesh_local_prefix_from_mlprefix(mlprefix_raw[0])
 
@@ -1928,18 +1940,35 @@ class MobiusDevice:
             ))
         return peers
 
-    async def discover_mesh_peers_auto(self) -> list[MeshPeer]:
+    async def discover_mesh_peers_auto(self, raise_errors: bool = False) -> list[MeshPeer]:
         """
         discover_networked_thread_devices(), falling back to
         discover_mesh_peers() when it finds nothing. The recommended entry
         point. mobius.discovery.discover_mesh_peers_via_direct_connect() is
         the remaining fallback, but it needs scan results and has to be
         called explicitly.
+
+        raise_errors=True: a failure raises instead of looking like an
+        empty mesh. The fallback is then only tried when
+        NetworkedThreadDevices can't be read (an MXM hub), and the error
+        raised names both attempts.
         """
-        peers = await self.discover_networked_thread_devices()
-        if peers:
-            return peers
-        return await self.discover_mesh_peers()
+        if not raise_errors:
+            peers = await self.discover_networked_thread_devices()
+            if peers:
+                return peers
+            return await self.discover_mesh_peers()
+
+        try:
+            return await self.discover_networked_thread_devices(raise_errors=True)
+        except Exception as networked_error:
+            try:
+                return await self.discover_mesh_peers(raise_errors=True)
+            except Exception as arrays_error:
+                raise IOError(
+                    f"NetworkedThreadDevices: {networked_error or type(networked_error).__name__}; "
+                    f"peer arrays: {arrays_error or type(arrays_error).__name__}"
+                ) from networked_error
 
     async def get_firmware_versions(self, model: Optional[Model] = None) -> dict:
         """{label: version} for every firmware component (FirmwareVersion,

{python_mobius-0.10.1 → python_mobius-0.10.2}/tests/test_networked_thread_devices.py

@@ -328,3 +328,68 @@ async def test_discover_networked_thread_devices_real_hardware_capture():
     assert p.model == Model.RadionXR15wG6Pro
     assert p.age == 8490
     assert p.short_address == 0x0400
+
+
+@pytest.mark.asyncio
+async def test_raise_errors_reports_a_failed_read_instead_of_an_empty_mesh():
+    device = MobiusDevice(_fake_ble_device())
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        raise IOError("timed out")
+
+    device.get_attribute = fake_get_attribute
+
+    assert await device.discover_networked_thread_devices() == []
+    with pytest.raises(IOError, match="timed out"):
+        await device.discover_networked_thread_devices(raise_errors=True)
+
+
+@pytest.mark.asyncio
+async def test_raise_errors_reports_an_unexpected_mlprefix():
+    device = MobiusDevice(_fake_ble_device())
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        if attr_id == C2Attribute.MLPrefix:
+            return [PREFIX]  # 8 bytes instead of 24
+        return []
+
+    device.get_attribute = fake_get_attribute
+
+    with pytest.raises(IOError, match="unexpected MLPrefix"):
+        await device.discover_networked_thread_devices(raise_errors=True)
+
+
+@pytest.mark.asyncio
+async def test_auto_with_raise_errors_names_both_attempts_when_both_fail():
+    device = MobiusDevice(_fake_ble_device())
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        raise IOError(f"no answer for {int(attr_id)}")
+
+    async def no_own_address():
+        return None
+
+    device.get_attribute = fake_get_attribute
+    device.get_own_mesh_address = no_own_address
+
+    assert await device.discover_mesh_peers_auto() == []
+    with pytest.raises(IOError, match=r"NetworkedThreadDevices: no answer for 2128; peer arrays: own mesh address"):
+        await device.discover_mesh_peers_auto(raise_errors=True)
+
+
+@pytest.mark.asyncio
+async def test_auto_with_raise_errors_returns_networked_devices():
+    device = MobiusDevice(_fake_ble_device())
+    suffix = bytes.fromhex("000000fffe00") + struct.pack("<H", 0x1234)
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        if attr_id == C2Attribute.MLPrefix:
+            return [MLPREFIX_RAW]
+        if attr_id == C2Attribute.NetworkedThreadDevices:
+            return [_entry(suffix, 42, Model.VorTechMP40wG3QD, "00000000000001")]
+        raise AssertionError("the peer arrays must not be read")
+
+    device.get_attribute = fake_get_attribute
+
+    peers = await device.discover_mesh_peers_auto(raise_errors=True)
+    assert [p.serial for p in peers] == ["00000000000001"]