fix: log a missing MQTT client at debug when the tree is transport-free by design (#20)

A tree built with mqtt_cfg=None has no client because that is what was asked
for, so every traversal reports one: a 31-device tree emitted 1,593 WARNING
lines saying only that the caller got what they requested.

_transport_free() is true when the root holds no client and was given no config
to build one from. The twelve NoMqttClient sites log at debug when it holds and
keep their previous severity otherwise, so "you forgot to start the root" stays
as loud as it was. Bring-your-own-transport is not transport-free: the client is
present, so its absence would still be an anomaly.

Property and Node resolve the predicate through node -> device -> root, mirroring
the walk already in Property.start_mqtt_client. An incomplete chain falls through
as not transport-free, so a half-built tree stays loud rather than going quiet.

Closes #11.

Author: cayossarian

src/ebus_sdk/homie.py

@@ -74,6 +74,21 @@ class StrEnum(str, Enum):
 
 logger = logging.getLogger("homie")
 
+
+def _log_missing_client(message: str, *, by_design: bool, level: int = logging.WARNING) -> None:
+    """Log a missing MQTT client at the severity its cause deserves.
+
+    A tree built without transport has no client because that is what was asked for, so
+    every entity in it reports one on each traversal — thousands of lines saying only that
+    the caller got what they requested. That case is DEBUG.
+
+    Everywhere else a client was expected: the root was given a config, or handed one, and
+    its absence means something went wrong. That case keeps the severity it had, so the
+    "you forgot to start the root" warning stays as loud as it was.
+    """
+    logger.log(logging.DEBUG if by_design else level, message)
+
+
 # One-time warning when a `$format` JSONSchema is present but jsonschema is not.
 _jsonschema_warned = False
 
@@ -532,6 +547,14 @@ def node(self) -> Node:
         """
         return self._node
 
+    def _transport_free(self) -> bool:
+        """See ``Device._transport_free``. Resolved node -> device, mirroring the walk in
+        ``start_mqtt_client``; an incomplete chain falls through as *not* transport-free so
+        a half-built tree stays loud rather than going quiet."""
+        node = self.node()
+        device = node.device() if node is not None else None
+        return device._transport_free() if device is not None else False
+
     def get_node_id(self) -> str:
         """
         Why is this needed?
@@ -677,7 +700,9 @@ def get_mqtt_client(self) -> Optional[MqttDeviceTransport]:
             return None
         mqttc = node.get_mqtt_client()
         if not mqttc:
-            logger.warning(f"reason=propertyGetMqttClientNoMqttClient,propertyID={self._id}")
+            _log_missing_client(
+                f"reason=propertyGetMqttClientNoMqttClient,propertyID={self._id}", by_design=self._transport_free()
+            )
         return mqttc
 
     def start_mqtt_client(self) -> None:
@@ -686,7 +711,9 @@ def start_mqtt_client(self) -> None:
         """
         mqttc = self.get_mqtt_client()
         if not mqttc:
-            logger.warning(f"reason=propertyStartMqttClientNoMqttClient,propertyID={self._id}")
+            _log_missing_client(
+                f"reason=propertyStartMqttClientNoMqttClient,propertyID={self._id}", by_design=self._transport_free()
+            )
             return
         # Never start a caller-owned client (bring-your-own-transport): mirror the
         # ownership guard on Device.start_mqtt_client(), and start via the concrete
@@ -758,7 +785,9 @@ def publish_value(self) -> bool:
         # is_running covers the owned path (True after start()); for an owned client
         # connected implies running, so this does not change owned behavior.
         if not mqttc or not (mqttc.is_running or mqttc.is_connected()):
-            logger.warning(f"reason=propertyPublishValueNoMqttClient,id={self._id}")
+            _log_missing_client(
+                f"reason=propertyPublishValueNoMqttClient,id={self._id}", by_design=self._transport_free()
+            )
             return False
         node_id = self.get_node_id()
         device_id = self.get_device_id()
@@ -837,7 +866,9 @@ def clear_value(self) -> bool:
         # See publish_value: gate on connectivity so an injected (caller-driven)
         # client can retract a retained value even without the SDK's is_running.
         if not mqttc or not (mqttc.is_running or mqttc.is_connected()):
-            logger.warning(f"reason=propertyClearValueNoMqttClient,propertyID={self._id}")
+            _log_missing_client(
+                f"reason=propertyClearValueNoMqttClient,propertyID={self._id}", by_design=self._transport_free()
+            )
             return False
         node_id = self.get_node_id()
         device_id = self.get_device_id()
@@ -957,7 +988,7 @@ def set_subscribe(self) -> None:
         logger.debug(f"reason=propertySetSubscribe,id={self._id}")
         mqttc = self.get_mqtt_client()
         if not mqttc:
-            logger.warning("reason=propertySetSubscribeNoMqttClient")
+            _log_missing_client("reason=propertySetSubscribeNoMqttClient", by_design=self._transport_free())
             return
         if not self.settable():
             logger.debug(f"reason=propertySetSubscribePropertyNotSettable,id={self._id}")
@@ -1054,6 +1085,12 @@ def get_device_id(self) -> str:
     def device(self) -> Device:
         return self._device
 
+    def _transport_free(self) -> bool:
+        """See ``Device._transport_free``. An incomplete chain falls through as *not*
+        transport-free so a half-built tree stays loud rather than going quiet."""
+        device = self.device()
+        return device._transport_free() if device is not None else False
+
     def set_device(self, device: Device) -> None:
         self._device = device
 
@@ -1064,7 +1101,9 @@ def get_mqtt_client(self) -> Optional[MqttDeviceTransport]:
             return None
         mqttc = device.get_mqtt_client()
         if not mqttc:
-            logger.warning(f"reason=nodeGetMqttClientNoMqttClient,nodeID={self._id}")
+            _log_missing_client(
+                f"reason=nodeGetMqttClientNoMqttClient,nodeID={self._id}", by_design=self._transport_free()
+            )
         return mqttc
 
     def add_property(self, property: Property) -> Property:
@@ -1415,6 +1454,18 @@ def root(self) -> "Device":
         """
         return self if self._parent is None else self._parent.root()
 
+    def _transport_free(self) -> bool:
+        """True when this tree was deliberately built without transport.
+
+        The root holds no client and was given no config to build one from, so "no client"
+        is the requested state rather than a fault: the tree is serving as a naming and
+        structure model for topic derivation, ``$description``, or tests. A root that was
+        handed a client or given a config is the opposite case — there a missing client is
+        an anomaly and stays a warning.
+        """
+        root = self.root()
+        return root.mqttc is None and root._mqtt_cfg is None
+
     @staticmethod
     def now_ems() -> int:
         """
@@ -1500,7 +1551,9 @@ def get_mqtt_client(self) -> Optional[MqttDeviceTransport]:
         """
         mqttc = self.root().mqttc
         if not mqttc:
-            logger.warning(f"reason=deviceGetMqttClientNoMqttClient,id={self._id}")
+            _log_missing_client(
+                f"reason=deviceGetMqttClientNoMqttClient,id={self._id}", by_design=self._transport_free()
+            )
         return mqttc
 
     def start_mqtt_client(self) -> None:
@@ -1510,7 +1563,9 @@ def start_mqtt_client(self) -> None:
         """
         root = self.root()
         if root.mqttc is None:
-            logger.warning(f"reason=deviceStartMqttClientNoMqttClient,id={self._id}")
+            _log_missing_client(
+                f"reason=deviceStartMqttClientNoMqttClient,id={self._id}", by_design=self._transport_free()
+            )
             return
         if not root._owns_client:
             # Bring-your-own-transport: the caller owns the client's lifecycle, so
@@ -1566,7 +1621,7 @@ def stop(self, *, flush_timeout: float = 1.0, stop_timeout: float = 2.0) -> None
         root = self.root()
         mqttc = root.mqttc
         if mqttc is None:
-            logger.warning(f"reason=deviceStopNoMqttClient,id={self._id}")
+            _log_missing_client(f"reason=deviceStopNoMqttClient,id={self._id}", by_design=self._transport_free())
             return
         # Best-effort graceful $state=disconnected. publish_and_flush is bounded
         # and returns False (never blocks/raises) when the broker is unreachable,
@@ -1718,7 +1773,9 @@ def delete_all_from_mqtt(self) -> None:
 
         mqttc = self.get_mqtt_client()
         if not mqttc:
-            logger.warning(f"reason=deviceDeleteAllFromMqttNoMqttClient,deviceId={self._id}")
+            _log_missing_client(
+                f"reason=deviceDeleteAllFromMqttNoMqttClient,deviceId={self._id}", by_design=self._transport_free()
+            )
             return
 
         base_topic = f"{EBUS_HOMIE_DOMAIN}/{EBUS_HOMIE_VERSION_MAJOR}/{self._id}"
@@ -1808,7 +1865,9 @@ def clear_retained_topic(self, topic_path: str) -> bool:
         """
         mqttc = self.get_mqtt_client()
         if not mqttc:
-            logger.warning(f"reason=deviceClearTopicNoMqttClient,topic={topic_path}")
+            _log_missing_client(
+                f"reason=deviceClearTopicNoMqttClient,topic={topic_path}", by_design=self._transport_free()
+            )
             return False
         try:
             mqttc.publish(topic_path, "", retain=True, qos=self._qos)
@@ -1930,7 +1989,11 @@ def publish(self, attribute: str = "", value: Optional[Any] = None) -> None:
         """
         mqttc = self.get_mqtt_client()
         if not mqttc:
-            logger.info(f"reason=devicePublishNoMqttClient,attribute={attribute}")
+            _log_missing_client(
+                f"reason=devicePublishNoMqttClient,attribute={attribute}",
+                by_design=self._transport_free(),
+                level=logging.INFO,
+            )
             return
         if not self._id:
             logger.info("reason=devicePublishNoDeviceID")

tests/test_homie_device.py

@@ -1,6 +1,7 @@
 """Tests for ebus_sdk.homie device-role classes: Property, Node, Device, and helpers."""
 
 import json
+import logging
 from enum import Enum
 from unittest.mock import MagicMock, patch
 
@@ -2106,3 +2107,96 @@ def test_guard_still_fires_when_a_configured_root_has_no_client(self):
 
         with pytest.raises(RuntimeError, match="has no MQTT client"):
             Device(id="child", type="dev.child", parent=root)
+
+
+class TestTransportFreeLogSeverity:
+    """A tree built without transport reports "no client" at DEBUG, not WARNING (#11).
+
+    The message is right either way; only the cause differs. Transport-free means the caller
+    asked for no client, so every traversal announcing one is noise — a 31-device tree emitted
+    1,593 WARNING lines saying only that it got what it requested. A root that was given a
+    config, or handed a client, is the case where a missing client is a real fault, and that
+    one stays exactly as loud as it was.
+    """
+
+    @staticmethod
+    def _tree(**root_kwargs):
+        root = Device(id="root", name="Root", type="dev.root", **root_kwargs)
+        node = root.add_node_from_dict({"id": "meter", "name": "meter", "type": "cap.meter"})
+        prop = node.add_property_from_dict({"id": "power", "name": "power", "datatype": "float", "settable": True})
+        return root, node, prop
+
+    @staticmethod
+    def _no_client_records(caplog, level):
+        return [r for r in caplog.records if r.levelno == level and "NoMqttClient" in r.getMessage()]
+
+    def test_transport_free_tree_reports_missing_client_at_debug(self, caplog):
+        """The whole point: no WARNING anywhere in a tree that asked for no transport."""
+        root, _node, prop = self._tree()
+
+        with caplog.at_level(logging.DEBUG, logger="homie"):
+            prop.get_mqtt_client()  # property -> node -> device, three sites in one call
+            prop.publish_value()
+            prop.set_subscribe()
+            prop.start_mqtt_client()
+            root.start_mqtt_client()
+            root.stop()
+
+        assert self._no_client_records(caplog, logging.WARNING) == []
+        assert self._no_client_records(caplog, logging.DEBUG)
+
+    def test_a_root_given_a_config_still_warns(self, caplog):
+        """The "you forgot to start the root" case, which the issue is careful to preserve.
+
+        `_mqtt_cfg` is what separates it: a root that was told how to build a client and has
+        none is broken, where a root told nothing is simply passive.
+        """
+        with patch("ebus_sdk.homie.MqttClient.from_config") as mock_from_config:
+            mock_from_config.return_value = _mock_mqtt_client()
+            root, _node, prop = self._tree(mqtt_cfg={"host": "broker.invalid"})
+        root.mqttc = None  # client expected, absent — the genuine fault
+
+        with caplog.at_level(logging.DEBUG, logger="homie"):
+            prop.get_mqtt_client()
+
+        assert root._transport_free() is False
+        assert self._no_client_records(caplog, logging.WARNING)
+
+    def test_an_injected_client_is_not_transport_free(self):
+        """Bring-your-own-transport is the opposite of transport-free, even though both
+        leave `_mqtt_cfg` unset — the client is present, so its absence would be an anomaly."""
+        root = Device(id="root", type="dev.root", mqttc=_mock_mqtt_client())
+
+        assert root._transport_free() is False
+
+    def test_the_predicate_resolves_from_every_level(self):
+        """Property and Node answer for their tree, not for themselves."""
+        root, node, prop = self._tree()
+        child = Device(id="child", type="dev.child", parent=root)
+
+        assert root._transport_free() is True
+        assert child._transport_free() is True
+        assert node._transport_free() is True
+        assert prop._transport_free() is True
+
+    def test_a_detached_entity_stays_loud(self, caplog):
+        """An incomplete chain cannot prove the tree is transport-free, so it does not go
+        quiet: a property with no node is a bug, and silencing it would hide one."""
+        orphan = Property(id="power", name="power", datatype=PropertyDatatype.FLOAT)
+
+        assert orphan._transport_free() is False
+
+    def test_device_publish_keeps_its_own_severity_when_a_client_was_expected(self, caplog):
+        """`devicePublishNoMqttClient` was already INFO on main. Transport-free drops it to
+        DEBUG; the expected-a-client case keeps INFO rather than being escalated."""
+        with patch("ebus_sdk.homie.MqttClient.from_config") as mock_from_config:
+            mock_from_config.return_value = _mock_mqtt_client()
+            root, _node, _prop = self._tree(mqtt_cfg={"host": "broker.invalid"})
+        root.mqttc = None
+
+        with caplog.at_level(logging.DEBUG, logger="homie"):
+            root.publish(attribute="$state", value="ready")
+
+        assert [
+            r for r in caplog.records if r.levelno == logging.INFO and "devicePublishNoMqttClient" in r.getMessage()
+        ]