span-panel-api 3.7.0b1__tar.gz → 3.8.0b2__tar.gz

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/.gitignore

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

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/CHANGELOG.md

@@ -13,7 +13,10 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 
 ### Added
 
+- **spanos3/r202639/03 batch 2: reads more of the data this firmware publishes.**
+- **`SpanMqttClient.masked_tree()` returns the panel's device tree with identifiers and site details masked**, for a consumer's diagnostics; `None` on a flat panel.
 - **`V2StatusInfo.hardware_version` reports the hardware version string from `GET /api/v2/status`.**
+- **`SpanEvseSnapshot.charge_current_limit_minimum_a` and `charge_current_limit_maximum_a` report the range a SPAN Drive declares for its charge-current limit**, `None` where undeclared.
 
 ### Changed
 
@@ -22,7 +25,10 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 - **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.uptime_s` becomes `int | None`**, and with those parsers it is `None` on a parent/child panel and before a flat panel first reports ready, where it was a constant `0`.
 - **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.instant_power_update_time_s` and `energy_accum_update_time_s` become `int | None` and default to `None`**, and with those parsers they are `None` until the reading has arrived and always on a parent/child
   panel, where they were `0`.
-- **The `schema-0` and `schema-1` extras require `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer**, the adapters that report these values as unknown.
+- **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.is_240v` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` where the pole count is unpublished.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.lugs_at_service_entrance` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` while the upstream lugs declare their feed but leave it unpublished.
+- **The `schema-0` extra requires `span-panel-api-schema-0` 1.3.0 or newer and the `schema-1` extra requires `span-panel-api-schema-1` 1.4.0 or newer**, the adapters that report these values as unknown; schema-1 1.4.0 also fills the snapshot fields this
+  release adds.
 
 ### Removed
 
@@ -33,6 +39,7 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 
 - **`V2HomieSchema.types_schema_hash` on data model 1.0 is the panel's published `deviceClassesSchemaHash`, or a hash of `deviceClasses` when none is published, where it was one constant for every such panel**; a flat panel's value is unchanged, and a
   value stored from 3.6.x differs once on a data model 1.0 panel.
+- **A property the panel clears reads as unpublished** on a parent/child panel, where it read as an empty value until the panel published it again.
 
 ## [3.6.2]
 

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.7.0b1
+Version: 3.8.0b2
 Summary: A client library 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
@@ -22,7 +22,7 @@ Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
 Requires-Dist: span-panel-api-schema-0>=1.3.0b1; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.3.0b1; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.4.0b4; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -171,6 +171,9 @@ because a transport could reasonably offer one and not the other.
 One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
+`TreeExportingAdapter` sits beside `SchemaAdapter` as an optional protocol, not one every adapter must implement: an adapter that offers `export_masked_tree()` lets `SpanMqttClient.masked_tree()` return the panel's device tree with serials, device ids and
+site details masked, and `None` otherwise.
+
 ### Snapshots
 
 All panel state is represented as immutable, frozen dataclasses:

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/README.md

@@ -144,6 +144,9 @@ because a transport could reasonably offer one and not the other.
 One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
+`TreeExportingAdapter` sits beside `SchemaAdapter` as an optional protocol, not one every adapter must implement: an adapter that offers `export_masked_tree()` lets `SpanMqttClient.masked_tree()` return the panel's device tree with serials, device ids and
+site details masked, and `None` otherwise.
+
 ### Snapshots
 
 All panel state is represented as immutable, frozen dataclasses:

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.7.0b1"
+version = "3.8.0b2"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -69,7 +69,10 @@ schema-0 = ["span-panel-api-schema-0>=1.3.0b1"]
 # Raised to 1.2.2 for 3.6.2: the readiness gate every snapshot passes asks that
 # adapter what is still missing, and 1.2.2 restarts its feed grace correctly.
 # Raised to 1.3.0b1 for 3.7.0b1, for the same reason as schema-0's.
-schema-1 = ["span-panel-api-schema-1>=1.3.0b1"]
+# Raised to 1.4.0b1 for 3.8.0b1: that adapter fills the snapshot fields this
+# bootstrap adds.
+# Raised to 1.4.0b4 for 3.8.0b2: that adapter exports the masked device tree.
+schema-1 = ["span-panel-api-schema-1>=1.4.0b4"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"
@@ -93,7 +96,7 @@ dev = [
     # known. Dependabot raises the bump on its own; the bump PR re-runs
     # `scripts/capture_parent_child_reference.py` and the suite then says whether
     # the wire moved.
-    "ebus-panel-sim==0.8.0",
+    "ebus-panel-sim==0.9.0",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-cov",
@@ -253,6 +256,12 @@ explicit_package_bases = true
 # `tests/` on `sys.path`; the support packages the mypy hook checks resolve the same
 # way here.
 mypy_path = "src:tests"
+# paho ships `py.typed` but leaves its topic matcher unannotated, so every call
+# into it would be an untyped call. The schema-1 route table resolves what the
+# matcher yields through a typed dict at once, which keeps its `Any` from going
+# further; `warn_return_any` does not police that for you (a union or a
+# `yield from` passes it), so keep it to that shape.
+untyped_calls_exclude = ["paho.mqtt.matcher"]
 # Excluded by name for the reason `[tool.ruff]` gives above: the capture script is
 # checked like the library, and the hand-run tools written before that was expected
 # are not.

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/src/span_panel_api/__init__.py

@@ -29,6 +29,7 @@ from .exceptions import (
     SpanPanelError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelSchemaVersionError,
     SpanPanelServerError,
     SpanPanelStaleDataError,
@@ -41,15 +42,22 @@ from .models import (
     ADOPTION_IDENTITY_NODE,
     ADOPTION_TOPOLOGY_NODE,
     DISCOVERY_NAMESPACE,
+    FEEDS_ROLES,
+    PROTECTION_FUNCTIONS,
     AdoptedDevice,
     AdoptedProperty,
     ControlTarget,
     DiscoveredMetadata,
     ExtensionProperty,
     ExtensionSubject,
+    FeedsRole,
     FieldMetadata,
     HomieSchemaTypes,
+    MaskedTree,
+    MaskedTreeDevice,
+    MaskedTreeMetadata,
     PassphraseRotation,
+    ProtectionFunction,
     SpanBatterySnapshot,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
@@ -57,10 +65,12 @@ from .models import (
     SpanPanelSnapshot,
     SpanPcsSnapshot,
     SpanPVSnapshot,
+    UndescribedDevice,
     V2AuthResponse,
     V2HomieSchema,
     V2StatusInfo,
     is_discovery_path,
+    shared_meter_groups,
 )
 from .mqtt import (
     ControlCommand,
@@ -84,10 +94,12 @@ from .protocol import (
     CircuitControlProtocol,
     ControlInterceptionProtocol,
     EvseControlProtocol,
+    EvseLockControlProtocol,
     PanelCapability,
     PanelControlProtocol,
     SpanPanelClientProtocol,
     StreamingCapableProtocol,
+    TreeExportingAdapter,
 )
 
 __version__ = _pkg_version("span-panel-api")
@@ -106,6 +118,9 @@ __all__ = [  # noqa: RUF022
     # snapshot rather than by its arguments -- a device the adapter models
     # produces no AdoptedDevice and so cannot be addressed through it.
     "AdoptedControlProtocol",
+    # A charger's connector lock, authorised by `SpanEvseSnapshot.lock_control`.
+    # A protocol of its own so `EvseControlProtocol`'s implementers are unchanged.
+    "EvseLockControlProtocol",
     # Added 2026-08-25 (3.1.0): one veto/observe point for every control
     # command. A protocol of its own rather than a member on the four control
     # protocols, which would break their implementers a second time in one
@@ -137,6 +152,15 @@ __all__ = [  # noqa: RUF022
     "ControlTarget",
     "ExtensionProperty",
     "ExtensionSubject",
+    # Added 2026-10-31: the masked device tree a consumer forwards in diagnostics,
+    # and the optional protocol an adapter offers it through. Deliberately not a
+    # SchemaAdapter member: the protocol derives its required set from itself, so a
+    # member there would invalidate every built adapter wheel.
+    "MaskedTree",
+    "MaskedTreeDevice",
+    "MaskedTreeMetadata",
+    "UndescribedDevice",
+    "TreeExportingAdapter",
     # Snapshots
     "SpanBatterySnapshot",
     "SpanCircuitSnapshot",
@@ -145,6 +169,16 @@ __all__ = [  # noqa: RUF022
     "SpanPVSnapshot",
     "SpanPanelSnapshot",
     "SpanPcsSnapshot",
+    # What a circuit's `connection/feeds-role` declares, read into
+    # `SpanCircuitSnapshot.feeds_role`.
+    "FEEDS_ROLES",
+    "FeedsRole",
+    # What a circuit's `breaker/protection-functions` lists, read into
+    # `SpanCircuitSnapshot.protection_functions`.
+    "PROTECTION_FUNCTIONS",
+    "ProtectionFunction",
+    # The circuits one meter measures, from `SpanCircuitSnapshot.meter_shared_with`.
+    "shared_meter_groups",
     # Factory
     "create_span_client",
     # Detection
@@ -216,6 +250,10 @@ __all__ = [  # noqa: RUF022
     # keep their meaning; deliberately not a SpanPanelAuthError, because the
     # passphrase the user supplied may be correct.
     "SpanPanelPassphraseUnavailableError",
+    # Registration refused with HTTP 429, carrying the panel's `Retry-After` in
+    # seconds. A subclass of SpanPanelAPIError, so existing except clauses keep
+    # their meaning; not a SpanPanelAuthError, because no credential was judged.
+    "SpanPanelRateLimitError",
     "SpanPanelServerError",
     "SpanPanelStaleDataError",
     # Added 2026-08-31 (3.4.0): a bootstrap REST call that failed verification

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/src/span_panel_api/auth.py

@@ -10,9 +10,12 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Collection, Mapping
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 import hashlib
 import json
 import logging
+import math
 import ssl
 import uuid
 
@@ -24,6 +27,7 @@ from .exceptions import (
     SpanPanelAuthError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelServerError,
 )
 from .models import HomieSchemaTypes, PassphraseRotation, V2AuthResponse, V2HomieSchema, V2StatusInfo
@@ -216,21 +220,37 @@ CA_CERT_MAX_ATTEMPTS = 5
 CA_CERT_BACKOFF_S = 1.5
 
 
-def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
-    """Return how long to wait before retrying a rate-limited request.
+def _retry_after_s(retry_after: str | None, now: datetime) -> float | None:
+    """The wait a ``Retry-After`` header asks for, in seconds, or None if it asks for none.
 
-    Prefers the panel's ``Retry-After`` header (delta-seconds form) and falls
-    back to exponential backoff. Malformed or negative values fall back too,
-    so a bad header can never stall or skip the retry.
+    Both forms RFC 9110 allows: delta-seconds, taken as given, and an HTTP-date,
+    taken as the seconds from `now` until then (0.0 once it has passed). A
+    negative, infinite or unparseable value is no answer, so a bad header can
+    never stall or skip a retry.
     """
-    fallback = backoff_s * (2.0 ** (attempt - 1))
     if retry_after is None:
-        return fallback
+        return None
     try:
-        parsed = float(retry_after)
-    except (TypeError, ValueError):
-        return fallback
-    return parsed if parsed >= 0 else fallback
+        seconds = float(retry_after)
+    except ValueError:
+        try:
+            until = parsedate_to_datetime(retry_after)
+        except (TypeError, ValueError):
+            return None
+        if until.tzinfo is None:
+            return None
+        return max((until - now).total_seconds(), 0.0)
+    return seconds if math.isfinite(seconds) and seconds >= 0 else None
+
+
+def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
+    """Return how long to wait before retrying a rate-limited request.
+
+    Prefers the panel's ``Retry-After`` header and falls back to exponential
+    backoff where it gives no usable wait.
+    """
+    parsed = _retry_after_s(retry_after, datetime.now(UTC))
+    return backoff_s * (2.0 ** (attempt - 1)) if parsed is None else parsed
 
 
 async def register_v2(
@@ -276,6 +296,7 @@ async def register_v2(
     Raises:
         SpanPanelAuthError: Invalid passphrase or auth failure
         SpanPanelPassphraseUnavailableError: The panel cannot read its own passphrase
+        SpanPanelRateLimitError: HTTP 429; the panel is limiting registrations. Not retried
         SpanPanelServerError: The panel is not ready to register clients (any 5xx,
             including the 503 it answers before its serial number is known); retryable
         SpanPanelConnectionError: Cannot reach panel
@@ -314,6 +335,16 @@ async def register_v2(
             status_code=reply.status_code,
         )
 
+    if reply.status_code == HTTP_TOO_MANY_REQUESTS:
+        # Not retried: the panel limits registrations per client address, and a
+        # retry here would spend the caller's next attempt on its behalf.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelRateLimitError(
+            f"Panel is rate-limiting registration (HTTP {reply.status_code})",
+            status_code=reply.status_code,
+            retry_after_s=_retry_after_s(reply.headers.get("retry-after"), datetime.now(UTC)),
+        )
+
     if reply.status_code == 422 and _error_detail(reply.response) == REGISTRATION_UNAVAILABLE_DETAIL:
         # Checked before the general 422 below, which means "credential not
         # accepted". This one is the panel failing to read its own passphrase,
@@ -613,8 +644,8 @@ async def rotate_passphrase(
     Raises:
         SpanPanelInsufficientPrivilegeError: HTTP 403; the token is reduced-privilege
         SpanPanelAuthError: HTTP 401 (token invalid or stale) or 412 (no bearer token)
-        SpanPanelServerError: HTTP 5xx. After a 500 the outcome is unknown: the
-            passphrase may or may not have changed.
+        SpanPanelServerError: HTTP 5xx. After a 500 or a 504 the outcome is unknown:
+            the passphrase may or may not have changed.
         SpanPanelConnectionError: Cannot reach panel
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b2}/src/span_panel_api/exceptions.py

@@ -68,6 +68,25 @@ class SpanPanelServerError(SpanPanelAPIError):
     """
 
 
+class SpanPanelRateLimitError(SpanPanelAPIError):
+    """The panel is limiting the client's requests and refused this one (HTTP 429).
+
+    Raised by ``register_v2``, which does not retry: the caller decides when to
+    try again. ``retry_after_s`` is the wait the panel asked for, in seconds,
+    from its ``Retry-After`` header: a delta-seconds value as given, an HTTP-date
+    as the seconds until that time. ``None`` when the header is absent or holds
+    neither.
+
+    A `SpanPanelAPIError`, so an existing clause catching that class still
+    catches this, and not a `SpanPanelAuthError`: the credential was never
+    judged.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None, retry_after_s: float | None = None) -> None:
+        super().__init__(message, status_code)
+        self.retry_after_s = retry_after_s
+
+
 class SpanPanelPassphraseUnavailableError(SpanPanelAPIError):
     """The panel cannot read its own passphrase, so it cannot issue broker credentials.