feat: type Controller's mqttc by what the SDK calls on an injected client

Closes #8.

mqttc was annotated with the concrete MqttClient, which nominally admits only
that class or a subclass. It works today only because ebus-mqtt-client ships no
py.typed, so downstream type checkers resolve the import to Any. When that marker
lands the annotation starts meaning what it says, and a consumer injecting its own
client needs a cast or a type-ignore to use a feature whose purpose is supplying
one.

Adds MqttTransport, a runtime_checkable Protocol of the three members the SDK
actually calls on an injected client — publish, subscribe, unsubscribe — and
widens the parameter to it. Signatures mirror MqttClient exactly, so MqttClient
satisfies it unchanged and every existing call site keeps type-checking.

Deliberately not the full client surface. An injected client is never started or
stopped: _connect_broker returns early when mqttc is already set, so the start()
beside from_config is unreachable, and stop() is behind if self._owns_client.
is_connected, is_running and publish_and_flush are Device/Property-path members
with no injection point. Typing the parameter with those would oblige consumers to
implement methods the SDK provably never calls on their object.

Two supporting edits, both behaviour-preserving: _connect_broker binds the
SDK-built client to a local of the concrete type so start() resolves, and
Controller keeps that client in _owned_client so stop() has a typed handle.
Assignment order in _connect_broker is unchanged, so a start() that raises leaves
self.mqttc exactly as it did before.

Author: cayossarian

src/ebus_sdk/__init__.py

@@ -78,6 +78,9 @@
 # MQTT client
 from ebus_mqtt_client import MqttClient
 
+# Structural type for a caller-supplied MQTT client
+from ebus_sdk.transport import MqttTransport
+
 __version__ = "0.14.0"
 
 __all__ = [
@@ -130,4 +133,5 @@
     "CONNECTION_NODE_TYPE",
     # MQTT
     "MqttClient",
+    "MqttTransport",
 ]

src/ebus_sdk/homie.py

@@ -62,6 +62,8 @@ class StrEnum(str, Enum):
 from typing import Any, Callable, List, Optional, Type, Union
 from ebus_mqtt_client import MqttClient
 
+from ebus_sdk.transport import MqttTransport
+
 # Optional: JSONSchema validation of a `json` property's `$format`. Kept optional
 # (see `ebus-sdk[validation]`) so a constrained build can omit it; absent it,
 # validation is gracefully skipped (see `validate_json_format`).
@@ -2176,7 +2178,7 @@ def __init__(
         device_id: Optional[str] = None,
         root_device_id: Optional[str] = None,
         qos: int = EBUS_HOMIE_MQTT_QOS,
-        mqttc: Optional[MqttClient] = None,
+        mqttc: Optional[MqttTransport] = None,
     ):
         """
         Initialize a Homie Controller
@@ -2221,8 +2223,13 @@ def __init__(
         # Bring-your-own-transport (SDK-61t.6): an injected client is used as-is
         # and its lifecycle stays the caller's; a None here means the SDK
         # constructs, starts, and owns the client (the default, unchanged path).
-        self.mqttc = mqttc
+        self.mqttc: Optional[MqttTransport] = mqttc
         self._owns_client = mqttc is None
+        # The SDK-constructed client, kept as its concrete type so start()/stop() —
+        # which exist only on a client we own — remain callable. Stays None for an
+        # injected client, which is what makes "never started, never stopped" a
+        # property of the types rather than a promise in a comment.
+        self._owned_client: Optional[MqttClient] = None
         self.devices = {}  # {device_id: DiscoveredDevice}
         # Tree-rooted mode: {parent_device_id: set_of_subscribed_child_ids}.
         # Authoritative record of what we've subscribed for under each parent,
@@ -2257,12 +2264,18 @@ def _connect_broker(self) -> None:
 
         client_id = f"homie-controller-{uuid.uuid4()}"
         try:
-            self.mqttc = MqttClient.from_config(
+            # Bound to a local of the concrete type so start() resolves — self.mqttc is
+            # MqttTransport, which deliberately has no start(). Assignment order is
+            # unchanged from before: both references are set before start(), so a
+            # start() that raises leaves self.mqttc set exactly as it did previously.
+            client = MqttClient.from_config(
                 mqtt_cfg=self._mqtt_cfg,
                 client_id=client_id,
                 on_connect_callback=partial(self._on_connect),
             )
-            self.mqttc.start(blocking=False)
+            self._owned_client = client
+            self.mqttc = client
+            client.start(blocking=False)
             logger.info(f"reason=controllerConnected,clientID={client_id}")
         except Exception as e:
             logger.exception(f"reason=controllerConnectException,error={e}")
@@ -2854,9 +2867,13 @@ def stop(self) -> None:
         """
         if self.mqttc:
             logger.info(f"reason=stoppingController,deviceCount={len(self.devices)}")
-            if self._owns_client:
-                self.mqttc.stop()
+            # Stops via the owned handle, never via self.mqttc: an injected client has no
+            # stop() in its contract, and _owned_client is None precisely when one was
+            # injected. Same condition as before — _owns_client still decides.
+            if self._owns_client and self._owned_client is not None:
+                self._owned_client.stop()
             self.mqttc = None
+            self._owned_client = None
         # Release DiscoveredDevice objects and their property dicts
         self.devices.clear()
         self._subscribed_children.clear()

src/ebus_sdk/transport.py

@@ -0,0 +1,51 @@
+"""Structural type for the MQTT transport the SDK is given.
+
+Its own module because it is public API rather than an internal detail: a consumer who
+cannot name the type gains nothing from the widening, so it is re-exported from ``ebus_sdk``
+beside ``MqttClient``. Keeping a small public type out of a ~2,900-line module is the only
+reason it is not in ``homie.py``; nothing else imports it today.
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MqttTransport(Protocol):
+    """What the SDK calls on a *caller-supplied* MQTT client.
+
+    Three members, deliberately — not the full ``MqttClient`` surface.
+
+    An injected client is never started or stopped by the SDK, and that is an invariant the
+    code enforces rather than a convention:
+
+    * ``Controller._connect_broker`` returns immediately when ``self.mqttc`` is already set,
+      so the ``start()`` beside ``MqttClient.from_config(...)`` is unreachable for an
+      injected client.
+    * ``Controller.stop`` calls ``stop()`` only behind ``if self._owns_client``, which is
+      ``mqttc is None`` fixed at construction.
+
+    ``is_connected``, ``is_running`` and ``publish_and_flush`` are likewise absent because
+    nothing on the ``Controller`` path calls them — they belong to the ``Device`` /
+    ``Property`` path, which has no injection point.
+
+    The narrowness is deliberate rather than incidental. Widening this to the full client
+    surface would type the injection point as *something the SDK may start and stop* — the
+    opposite of the ownership guarantee above — and would oblige every consumer to implement
+    two lifecycle methods the SDK provably never calls on their object; for a host supplying
+    a connection whose lifecycle it already manages elsewhere, those stubs are pure ceremony.
+
+    If ``Device`` gains an injection point later it needs a wider contract than this (it does
+    call ``is_connected``, ``is_running`` and ``publish_and_flush``) but still not
+    ``start``/``stop``. That would be a second protocol deriving from this one rather than an
+    edit to this one.
+
+    Signatures mirror ``ebus_mqtt_client.MqttClient`` exactly, including the ``Any`` on
+    ``subscribe``'s callback, so that ``MqttClient`` satisfies this unchanged. Returns are
+    ``object`` because every call site in the SDK discards them.
+    """
+
+    def publish(self, topic: str, data: str, qos: int = 1, retain: bool = False) -> object: ...
+
+    def subscribe(self, sub: str, param: Any, qos: int = 1) -> object: ...
+
+    def unsubscribe(self, sub: str) -> object: ...

tests/test_controller.py

@@ -1303,3 +1303,66 @@ def test_owned_client_is_constructed_started_and_stopped(self):
             client.start.assert_called_once()  # SDK starts an owned client
             ctrl.stop()
             client.stop.assert_called_once()  # and stops it
+
+
+class TestMqttTransportProtocol:
+    """The injection point is typed by what the SDK calls on an injected client (#8)."""
+
+    def test_mqtt_client_satisfies_the_protocol(self):
+        """The concrete client must keep satisfying the widened annotation."""
+        from ebus_mqtt_client import MqttClient as ConcreteClient
+
+        from ebus_sdk import MqttTransport
+
+        assert issubclass(ConcreteClient, MqttTransport)
+
+    def test_protocol_is_exported_from_the_package_root(self):
+        """A consumer who cannot name the type gets nothing from the widening."""
+        import ebus_sdk
+
+        assert "MqttTransport" in ebus_sdk.__all__
+        assert ebus_sdk.MqttTransport is not None
+
+    def test_a_three_member_client_is_a_valid_transport(self):
+        """publish / subscribe / unsubscribe is the whole injected-client contract.
+
+        Deliberately implements nothing else — no start, stop, is_connected, is_running
+        or publish_and_flush — because the SDK never calls those on an injected client.
+        """
+        from ebus_sdk import MqttTransport
+
+        class Minimal:
+            def publish(self, topic, data, qos=1, retain=False):
+                return None
+
+            def subscribe(self, sub, param, qos=1):
+                return None
+
+            def unsubscribe(self, sub):
+                return True
+
+        client = Minimal()
+        assert isinstance(client, MqttTransport)
+
+        ctrl = Controller(mqttc=client)
+        ctrl.start_discovery()
+        ctrl.stop()  # must not reach start()/stop() on a client that has neither
+
+    def test_owned_client_handle_is_none_when_injected(self):
+        """`_owned_client` is what makes 'never stopped' structural rather than promised."""
+        fake = MagicMock()
+        ctrl = Controller(mqttc=fake)
+        assert ctrl._owned_client is None
+        ctrl.stop()
+        fake.stop.assert_not_called()
+
+    def test_owned_client_handle_is_set_and_cleared_for_an_sdk_built_client(self):
+        with patch("ebus_sdk.homie.MqttClient.from_config") as mock_from_config:
+            client = MagicMock()
+            client.sub_callbacks = {}
+            mock_from_config.return_value = client
+            ctrl = Controller(mqtt_cfg={"host": "x"})
+            assert ctrl._owned_client is client
+            ctrl.stop()
+            client.stop.assert_called_once()
+            assert ctrl._owned_client is None