span-panel-api-schema-1 1.4.0b2__tar.gz → 1.4.0b3__tar.gz

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b3}/.gitignore

@@ -16,6 +16,7 @@ xnotes/*
 .env
 .envrc
 .venv
+.deps-installed
 .vscode/settings.json
 
 # mypy

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b3}/CHANGELOG.md

@@ -35,6 +35,8 @@ Requires `span-panel-api` **3.8.0 or newer**, whose snapshot fields accept the u
 - **The grid-forming device name falls back to vendor and model instead of showing a device id.**
 - **A panel with no MID reports `dsm_state` `DSM_ON_GRID` and `current_run_config` `PANEL_ON_GRID` whenever it is publishing**, where both dropped to `UNKNOWN` each time `power-flows/grid` read within 1 W of zero
   ([#215](https://github.com/SpanPanel/span-panel-api/issues/215)).
+- **Each MQTT message costs the same few microseconds however many devices the panel declares**, where routing it tested every recorded subscription in turn and every readiness check walked the device tree. On a 30-device tree the work per message falls
+  from 90–250 µs to about 2 µs, measured on a desktop machine ([#223](https://github.com/SpanPanel/span-panel-api/issues/223)).
 
 ## [1.2.2]
 

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.4.0b2
+Version: 1.4.0b3
 Summary: Parent/child schema (data-model-version 1.x) parser for span-panel-api
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.4.0b2"
+version = "1.4.0b3"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b3}/src/span_panel_api_schema_1/adapter.py

@@ -118,7 +118,14 @@ class SchemaOneAdapter:
         self._controller = Controller(root_device_id=serial_number, mqttc=self._routes)
         self._property_callbacks: list[Callable[[str, str, str, str | None], None]] = []
         self._awaiting: tuple[str, ...] = ()
+        # Readiness as last computed, or None once the tree has changed since.
+        self._ready: bool | None = None
         self._controller.set_on_property_changed_callback(self._on_property_changed)
+        # Every event that can change what `is_ready()` answers; see there.
+        self._controller.set_on_device_discovered_callback(self._tree_changed)
+        self._controller.set_on_device_state_changed_callback(self._tree_changed)
+        self._controller.set_on_device_removed_callback(self._tree_changed)
+        self._controller.set_on_description_received_callback(self._tree_changed)
         # Records the subscriptions the tree walk needs; nothing reaches the
         # wire, because this object has no connection to reach it with.
         self._controller.start_discovery()
@@ -173,7 +180,22 @@ class SchemaOneAdapter:
         panel's positions with none to lay out. Asking only for what the panel
         itself promised keeps a firmware that omits the property connectable —
         it falls back to the drift warning in `panel_size_from_model`.
+
+        **The answer is remembered until the tree changes.** The transport asks
+        before and after every message, and walking the tree each time cost
+        more than routing the message did (#223). Only the Controller's own
+        events can move it: a device's first `$state`, a change of state, a
+        removal, a `$description`, and the root's `info/model` value. Each
+        forgets the answer and the next call works it out again. The events
+        never work it out themselves, because a description is announced before
+        the SDK has reconciled the children it declares.
         """
+        if self._ready is None:
+            self._ready = self._tree_ready()
+        return self._ready
+
+    def _tree_ready(self) -> bool:
+        """What `is_ready()` answers, worked out from the tree as it stands."""
         root = self._controller.get_root(self._serial_number)
         if root is None or root.state != STATE_READY or not root.description:
             return False
@@ -626,5 +648,12 @@ class SchemaOneAdapter:
         protocol has no place for the previous value, and consumers that need
         one keep it themselves.
         """
+        # The one value readiness waits on.
+        if (device_id, node_id, property_id) == (self._serial_number, NODE_INFO, PROP_MODEL):
+            self._ready = None
         for callback in list(self._property_callbacks):
             callback(device_id, node_id, property_id, value)
+
+    def _tree_changed(self, *_event: object) -> None:
+        """Forget the remembered readiness. Accepts any of the Controller's tree events."""
+        self._ready = None

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b3}/src/span_panel_api_schema_1/transport.py

@@ -38,10 +38,11 @@ zero circuits.
 
 from __future__ import annotations
 
+import itertools
 import logging
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NamedTuple
 
-from paho.mqtt.client import topic_matches_sub
+from paho.mqtt.matcher import MQTTMatcher
 
 from span_panel_api.models import ControlTarget
 from span_panel_api_schema_1.const import HOMIE_DOMAIN, HOMIE_VERSION
@@ -80,6 +81,13 @@ def control_target(device_id: str, node: str, prop: str) -> ControlTarget:
 MAX_HELD_MESSAGES = 4096
 
 
+class _Route(NamedTuple):
+    """A recorded callback, and when it was recorded, which decides an overlap."""
+
+    recorded: int
+    callback: Callable[[str, bytes], None]
+
+
 class ControllerRoutes:
     """Record `Controller`'s subscriptions and route messages back to them.
 
@@ -88,8 +96,11 @@ class ControllerRoutes:
     """
 
     def __init__(self) -> None:
-        # Insertion-ordered; dispatch walks it in reverse — see dispatch().
-        self._routes: dict[str, Callable[[str, bytes], None]] = {}
+        self._routes: dict[str, _Route] = {}
+        # The same patterns, indexed for matching: each maps to itself, and
+        # dispatch resolves the patterns that match through `_routes`.
+        self._matcher = MQTTMatcher()
+        self._recordings = itertools.count()
         # Last payload per topic that matched no route yet, keyed by topic so a
         # newer value supersedes an older one — the same last-value-wins rule
         # the broker applies to the retained message this stands in for.
@@ -132,27 +143,35 @@ class ControllerRoutes:
         the adapter's behalf, not of a route recorded in a dict.
         """
         # Pop before insert: assigning an existing key updates the value but
-        # keeps the key's original position, which would leave a re-registered
-        # pattern behind whatever was added after it in dispatch's match order.
+        # keeps the key's original position, and `routes` lists most recent last.
         self._routes.pop(sub, None)
-        self._routes[sub] = param
+        self._routes[sub] = _Route(next(self._recordings), param)
+        self._matcher[sub] = sub
         self._release(sub, param)
 
     def unsubscribe(self, sub: str) -> None:
         """Forget the callback for `sub`.
 
         The broad wire subscription stays. Messages for a device the SDK has
-        dropped simply stop matching a route, and dispatch discards them.
+        dropped simply stop matching a route, and dispatch holds them.
         """
-        self._routes.pop(sub, None)
+        # Guarded because the matcher raises for a pattern it never held, and
+        # forgetting one that was never recorded is harmless.
+        if self._routes.pop(sub, None) is not None:
+            del self._matcher[sub]
 
     # -- our side ----------------------------------------------------------
 
     def dispatch(self, topic: str, payload: str) -> None:
         """Deliver one message to the callback of the route that matches.
 
-        Walked most-recent-first, which is defensive rather than currently
-        required. Tree-rooted discovery subscribes four **device-scoped**
+        Matched through a prefix tree of the recorded patterns, so the cost
+        follows the topic's depth rather than the number of routes. Every
+        message takes this path, and a linear scan grew with each device the
+        panel declares, at four routes per device (#223).
+
+        The most recently recorded match wins, which is defensive rather than
+        currently required. Tree-rooted discovery subscribes four **device-scoped**
         patterns per device — `$state`, `$description`, `+/+`, `+/+/$target`
         (`Controller._subscribe_device_topics`) — which cannot overlap each
         other or another device's, so today exactly one route matches any topic.
@@ -172,11 +191,15 @@ class ControllerRoutes:
 
         The SDK hands callbacks `bytes`; the transport hands us `str`.
         """
-        for sub in reversed(self._routes):
-            if topic_matches_sub(sub, topic):
-                self._routes[sub](topic, payload.encode())
-                return
-        self._hold(topic, payload)
+        # The matcher is untyped and yields what it was given, the pattern
+        # string; `_routes` turns each back into a typed route. The list is
+        # complete before any callback runs, so a callback that subscribes
+        # changes a matcher nothing is still walking.
+        matched = [self._routes[sub] for sub in self._matcher.iter_match(topic)]
+        if not matched:
+            self._hold(topic, payload)
+            return
+        max(matched, key=lambda route: route.recorded).callback(topic, payload.encode())
 
     def _hold(self, topic: str, payload: str) -> None:
         """Keep a message for a route that has not been registered yet."""
@@ -201,8 +224,13 @@ class ControllerRoutes:
         in turn, so a whole tree unfolds from one root subscription. The
         candidate list is therefore taken up front and each entry re-checked,
         since a nested release may have claimed it already.
+
+        The pattern is indexed once and matched against every held topic,
+        rather than indexed afresh for each of them.
         """
-        for topic in [held for held in self._held if topic_matches_sub(sub, held)]:
+        pattern = MQTTMatcher()
+        pattern[sub] = sub
+        for topic in [held for held in self._held if next(pattern.iter_match(held), None) is not None]:
             payload = self._held.pop(topic, None)
             if payload is not None:
                 callback(topic, payload.encode())