span-panel-api 3.0.0b6__tar.gz → 3.0.0b7__tar.gz

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b7}/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0b7]
+
+### Changed
+
+- **`SpanMqttClient` accepts an `httpx_client`, and so does `create_span_client`.** Four config-flow-facing entry points already took an injected client; the runtime path was the one that did not, so every schema read built a throwaway — including the
+  retry loop that runs during a firmware upgrade, which built one per attempt at exactly the moment the panel was mid-reboot. Optional and defaulted, so nothing outside Home Assistant changes. The ownership rule is the one the existing entry points already
+  state: a client handed in is never closed here, and its timeouts, limits and headers are the caller's, which is why the per-call `timeout` defaults are ignored when one is given. Home Assistant's shared client carries httpx's default timeout rather than
+  this library's 10 s, and that is the caller exercising the policy it owns rather than a setting being lost.
+
 ## [3.0.0b6]
 
 ### Added

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.0.0b6
+Version: 3.0.0b7
 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

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.0.0b6"
+version = "3.0.0b7"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b7}/src/span_panel_api/factory.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from typing import TYPE_CHECKING
 
 from .adapters import resolve_adapter
 from .auth import get_homie_schema, register_v2
@@ -17,6 +18,9 @@ from .exceptions import SpanPanelAuthError
 from .mqtt.client import SpanMqttClient
 from .mqtt.models import MqttClientConfig
 
+if TYPE_CHECKING:
+    import httpx
+
 _LOGGER = logging.getLogger(__name__)
 
 _V2_CLIENT_NAME = "span-panel-api"
@@ -28,6 +32,7 @@ async def create_span_client(
     mqtt_config: MqttClientConfig | None = None,
     serial_number: str | None = None,
     port: int = 80,
+    httpx_client: httpx.AsyncClient | None = None,
 ) -> SpanMqttClient:
     """Create a SPAN Panel MQTT client.
 
@@ -37,6 +42,10 @@ async def create_span_client(
         mqtt_config: Pre-built MQTT broker configuration.
         serial_number: Panel serial number (extracted from detection/registration if omitted).
         port: HTTP port of the panel bootstrap API used for registration and detection.
+        httpx_client: Optional shared ``httpx.AsyncClient``, used for every request this
+            makes and handed to the client it builds. Not closed here; its timeouts and
+            limits are the caller's, which is why the per-call ``timeout`` defaults are
+            ignored when one is given.
 
     Returns:
         A connected-ready SpanMqttClient instance.
@@ -54,7 +63,7 @@ async def create_span_client(
     if mqtt_config is None:
         if passphrase is None:
             raise SpanPanelAuthError("Neither mqtt_config nor passphrase provided")
-        auth_response = await register_v2(host, _V2_CLIENT_NAME, passphrase, port=port)
+        auth_response = await register_v2(host, _V2_CLIENT_NAME, passphrase, port=port, httpx_client=httpx_client)
         mqtt_config = MqttClientConfig(
             broker_host=auth_response.ebus_broker_host,
             username=auth_response.ebus_broker_username,
@@ -68,7 +77,7 @@ async def create_span_client(
 
     if serial_number is None:
         # Try to detect from panel status
-        result = await detect_api_version(host, port=port)
+        result = await detect_api_version(host, port=port, httpx_client=httpx_client)
         if result.status_info is not None:
             serial_number = result.status_info.serial_number
 
@@ -80,7 +89,7 @@ async def create_span_client(
     # flat-versus-parent/child signal, mirroring MQTT's `info/data-model-version`
     # — so the parser is chosen before a single message is consumed, rather than
     # a wrong parser being discovered by its output.
-    schema = await get_homie_schema(host, port=port)
+    schema = await get_homie_schema(host, port=port, httpx_client=httpx_client)
     adapter_key, dispatch_reason = select_adapter_key(schema.data_model_version)
     # In a thread: resolution reads distribution metadata and imports the adapter
     # package, and this is the first call in the process to do either. See
@@ -96,6 +105,7 @@ async def create_span_client(
         data_model_version=schema.data_model_version,
         schema_dispatch_reason=dispatch_reason,
         schema=schema,
+        httpx_client=httpx_client,
     )
     await client.connect()
     return client

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b7}/src/span_panel_api/mqtt/client.py

@@ -13,6 +13,7 @@ import contextlib
 from importlib.metadata import version
 import logging
 import time
+from typing import TYPE_CHECKING
 
 from span_panel_api.schema_drift import log_schema_drift
 
@@ -34,6 +35,9 @@ from .connection import AsyncMqttBridge
 from .const import MQTT_READY_TIMEOUT_S
 from .models import MqttClientConfig
 
+if TYPE_CHECKING:
+    import httpx
+
 _LOGGER = logging.getLogger(__name__)
 
 # How long to wait for circuit name properties after device ready.
@@ -74,6 +78,7 @@ class SpanMqttClient:
         data_model_version: str | None = None,
         schema_dispatch_reason: str | None = None,
         schema: V2HomieSchema | None = None,
+        httpx_client: httpx.AsyncClient | None = None,
     ) -> None:
         self._host = host
         self._serial_number = serial_number
@@ -81,6 +86,12 @@ class SpanMqttClient:
         self._snapshot_interval = snapshot_interval
         self._panel_http_port = panel_http_port
         self._adapter_factory = adapter_factory
+        # Shared by the caller, owned by the caller: never closed here, and its
+        # policy -- timeouts, limits, headers -- is whatever the caller set. That
+        # is the same rule the four config-flow entry points already state, and
+        # the reason this exists at all is that the runtime path was the one place
+        # left without it. See `_get_client`.
+        self._httpx_client = httpx_client
 
         self._bridge: AsyncMqttBridge | None = None
         self._adapter: SchemaAdapter | None = None
@@ -287,7 +298,11 @@ class SpanMqttClient:
         # would be a second call to the same unauthenticated endpoint for a
         # value that cannot have changed. A directly-constructed client has no
         # schema yet, so it fetches here and dispatches in _build_adapter.
-        schema = self._schema if self._schema is not None else await get_homie_schema(self._host, port=self._panel_http_port)
+        schema = (
+            self._schema
+            if self._schema is not None
+            else await get_homie_schema(self._host, port=self._panel_http_port, httpx_client=self._httpx_client)
+        )
         self._schema = schema
         await self._preload_adapter(schema)
         adapter = self._build_adapter(schema)
@@ -807,7 +822,7 @@ class SpanMqttClient:
         last: Exception | None = None
         for _ in range(_REDISPATCH_RETRY_ATTEMPTS):
             try:
-                return await get_homie_schema(self._host, port=self._panel_http_port)
+                return await get_homie_schema(self._host, port=self._panel_http_port, httpx_client=self._httpx_client)
             except (SpanPanelConnectionError, SpanPanelTimeoutError) as exc:
                 last = exc
                 await asyncio.sleep(delay)

span_panel_api-3.0.0b7/tests/test_shared_http_client.py

@@ -0,0 +1,121 @@
+"""The runtime path uses the caller's HTTP client, not one of its own.
+
+Four config-flow-facing entry points already take an injected
+`httpx.AsyncClient`; `SpanMqttClient` was the one runtime entry point without
+it, so every schema fetch built a throwaway client -- including the retry loop
+that runs during a firmware upgrade, which builds one per attempt at exactly the
+moment the panel is mid-reboot.
+
+Home Assistant is the caller that cares. It owns a shared client, closes it at
+shutdown, and the integration's own `quality_scale.yaml` claims
+`inject-websession: done` -- a claim that was true of the config flow and not of
+anything that ran afterwards.
+
+**Ownership is the whole contract.** A client handed in is never closed here, and
+its policy is the caller's: timeouts, limits and headers are whatever the caller
+configured, which is why the per-call `timeout` arguments are documented as
+ignored when a client is injected. Home Assistant's shared client carries
+httpx's default timeout rather than this library's, and that is the caller
+exercising the policy it owns rather than a setting being lost.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from span_panel_api.mqtt import MqttClientConfig
+from span_panel_api.mqtt.client import SpanMqttClient
+
+SERIAL = "sp3-242424-001"
+
+
+class _Schema:
+    def __init__(self, version: str | None) -> None:
+        self.data_model_version = version
+
+
+def _client(injected: object | None) -> SpanMqttClient:
+    return SpanMqttClient(
+        host="192.168.1.1",
+        serial_number=SERIAL,
+        broker_config=MqttClientConfig(broker_host="broker.local", username="u", password="p"),
+        httpx_client=injected,  # type: ignore[arg-type]
+    )
+
+
+@pytest.mark.asyncio
+async def test_the_connect_fetch_uses_the_injected_client() -> None:
+    """The first schema read of a session, and the one every install makes."""
+    sentinel = MagicMock(name="shared-client")
+    client = _client(sentinel)
+
+    fetch = AsyncMock(return_value=_Schema("1.0"))
+    with (
+        patch("span_panel_api.mqtt.client.get_homie_schema", fetch),
+        patch.object(client, "_preload_adapter", AsyncMock()),
+        patch.object(client, "_build_adapter", MagicMock()),
+        patch.object(client, "_connect_bridge", AsyncMock(), create=True),
+    ):
+        # Connect goes on to bring up the MQTT bridge, which has nothing to do
+        # with this assertion and no broker to reach. The fetch is what is under
+        # test, and the await-count assertion below is what keeps that from
+        # passing vacuously if it never happened at all.
+        with contextlib.suppress(Exception):
+            await client.connect()
+
+    assert fetch.await_count >= 1
+    assert fetch.await_args.kwargs["httpx_client"] is sentinel
+
+
+@pytest.mark.asyncio
+async def test_the_upgrade_refetch_uses_the_injected_client() -> None:
+    """The path that mattered most, because it builds one client per retry attempt.
+
+    A panel accepts MQTT before it serves HTTP, so this loop can run several times
+    in a row while the panel finishes booting -- each one previously a fresh
+    client, a fresh connection pool, thrown away on the next attempt.
+    """
+    sentinel = MagicMock(name="shared-client")
+    client = _client(sentinel)
+    client._loop = asyncio.get_running_loop()
+
+    fetch = AsyncMock(return_value=_Schema("1.0"))
+    with patch("span_panel_api.mqtt.client.get_homie_schema", fetch):
+        assert await client._fetch_schema_with_retry() is not None
+
+    assert fetch.await_args.kwargs["httpx_client"] is sentinel
+
+
+@pytest.mark.asyncio
+async def test_an_injected_client_is_never_closed_here() -> None:
+    """It belongs to the caller, and the caller may still be using it.
+
+    Home Assistant hands out one shared client to every integration and closes it
+    at shutdown; closing it from here would take the others down with it. HA
+    guards its own copy, but a library that relies on the caller guarding it is
+    relying on the caller.
+    """
+    sentinel = MagicMock(name="shared-client")
+    sentinel.aclose = AsyncMock()
+    client = _client(sentinel)
+
+    await client.close()
+
+    sentinel.aclose.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_no_injected_client_still_works() -> None:
+    """The default has to stay the default: this library is not Home Assistant's alone."""
+    client = _client(None)
+    client._loop = asyncio.get_running_loop()
+
+    fetch = AsyncMock(return_value=_Schema("1.0"))
+    with patch("span_panel_api.mqtt.client.get_homie_schema", fetch):
+        assert await client._fetch_schema_with_retry() is not None
+
+    assert fetch.await_args.kwargs["httpx_client"] is None