nwp500-python 9.4.1__tar.gz → 9.4.2__tar.gz

{nwp500_python-9.4.1 → nwp500_python-9.4.2}/CHANGELOG.rst

@@ -5,6 +5,22 @@ Changelog
 Unreleased
 ==========
 
+Version 9.4.2 (2026-09-17)
+==========================
+
+Changed
+-------
+- **A dropped response message now says why it was dropped.** The typed
+  response handlers declined a message in three places without a word: a
+  topic that does not end in the required suffix, a payload with no data
+  under the expected key, and a reply whose ``macAddress`` names another
+  device. A caller watching for a reply that never reached its callback
+  could not tell a dropped message from one the cloud never published, and
+  the two want opposite fixes. Each branch now logs its reason at DEBUG,
+  with the topic and MAC redacted as elsewhere, and guarded by
+  ``isEnabledFor`` so the redaction regexes do not run on the normal
+  dispatch path when debug logging is off.
+
 Version 9.4.1 (2026-09-17)
 ==========================
 

{nwp500_python-9.4.1 → nwp500_python-9.4.2}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install install-dev lint format test clean build release check-release ci-lint ci-format ci-check version-bump validate-version
+.PHONY: help install install-dev lint format test test-cov require-python clean build release check-release ci-lint ci-format ci-check version-bump validate-version
 
 help:  ## Show this help message
 	@echo 'Usage: make [target]'
@@ -35,11 +35,19 @@ ci-format:  ## Run formatting exactly as CI does (via tox format)
 ci-check: ci-lint  ## Run the same checks as CI (ensures local/CI consistency)
 	@echo "🎉 All CI checks passed locally!"
 
-test:  ## Run tests with pytest
-	pytest
+# The package declares python_requires = >=3.14 and uses 3.14 syntax, but
+# that floor is only enforced when installing - running pytest against the
+# source tree happens on whatever interpreter is active. Fail with a clear
+# message instead of a SyntaxError in every test module.
+require-python:
+	@python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 14) else 1)' \
+		|| { echo "Python 3.14+ required, found $$(python3 -V 2>&1). Activate the project environment."; exit 1; }
 
-test-cov:  ## Run tests with coverage report
-	pytest --cov=nwp500 --cov-report=html --cov-report=term-missing
+test: require-python  ## Run tests with pytest
+	python3 -m pytest
+
+test-cov: require-python  ## Run tests with coverage report
+	python3 -m pytest --cov=nwp500 --cov-report=html --cov-report=term-missing
 
 clean:  ## Remove build artifacts and cache files
 	rm -rf build dist *.egg-info .eggs

{nwp500_python-9.4.1/src/nwp500_python.egg-info → nwp500_python-9.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.4.1
+Version: 9.4.2
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

{nwp500_python-9.4.1 → nwp500_python-9.4.2}/src/nwp500/mqtt/subscriptions.py

@@ -40,7 +40,12 @@ from ..mqtt_events import (
 from ..topic_builder import MqttTopicBuilder
 from .state_tracker import DeviceStateTracker
 from .types import QoS, to_awscrt_qos
-from .utils import get_response_data, redact_topic, topic_matches_pattern
+from .utils import (
+    get_response_data,
+    redact_mac,
+    redact_topic,
+    topic_matches_pattern,
+)
 
 if TYPE_CHECKING:
     from ..device_info_cache import MqttDeviceInfoCache
@@ -614,13 +619,45 @@ class MqttSubscriptionManager:
         """
 
         def handler(topic: str, message: dict[str, Any]) -> None:
+            # Every branch that declines a message says so at debug level.
+            # Silence here is expensive to diagnose: a caller watching for a
+            # reply that never reaches its callback cannot tell a dropped
+            # message from one the cloud never sent, and the two want
+            # opposite fixes. The logs are the only evidence either way.
+            #
+            # Each log is guarded: redact_topic runs a dozen regexes, and
+            # these branches are the normal case for a handler registered
+            # under the device wildcard, which sees every message for that
+            # device and keeps only its own.
             if topic_suffix and not topic.endswith(topic_suffix):
+                if _logger.isEnabledFor(logging.DEBUG):
+                    _logger.debug(
+                        "Ignoring a message on %s: the topic does not end "
+                        "with %r, which this handler requires",
+                        redact_topic(topic),
+                        topic_suffix,
+                    )
                 return
             try:
                 data = get_response_data(message, key)
                 if not data:
+                    if _logger.isEnabledFor(logging.DEBUG):
+                        _logger.debug(
+                            "Ignoring a message on %s: no %s data to parse "
+                            "as %s",
+                            redact_topic(topic),
+                            f"{key!r}" if key else "response",
+                            model.__name__,
+                        )
                     return
                 if only_mac and not _same_device(data, message, only_mac):
+                    if _logger.isEnabledFor(logging.DEBUG):
+                        _logger.debug(
+                            "Ignoring a message on %s: it names another "
+                            "device, not %s",
+                            redact_topic(topic),
+                            redact_mac(only_mac),
+                        )
                     return
 
                 parsed = parse(data) if parse else model.model_validate(data)

{nwp500_python-9.4.1 → nwp500_python-9.4.2/src/nwp500_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.4.1
+Version: 9.4.2
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

nwp500_python-9.4.2/src/nwp500_python.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "9.4.2",
+  "distance": 0,
+  "node": "gfe7fe156d7d292a934e3bfa48eb7f274b00ffe33",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-18"
+}

{nwp500_python-9.4.1 → nwp500_python-9.4.2}/tests/test_multi_device.py

@@ -1,3 +1,4 @@
+import logging
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
@@ -5,6 +6,7 @@ import pytest
 from nwp500.enums import CurrentOperationMode
 from nwp500.events import EventEmitter
 from nwp500.models import DeviceFeature, DeviceStatus
+from nwp500.mqtt import subscriptions as subscriptions_module
 from nwp500.mqtt.state_tracker import DeviceStateTracker
 from nwp500.mqtt.subscriptions import MqttSubscriptionManager
 from nwp500.mqtt_events import (
@@ -241,3 +243,150 @@ def test_make_handler_injects_mac():
     parsed = callback_called[0]
     assert isinstance(parsed, DeviceStatus)
     assert parsed.mac_address == mac
+
+
+def _manager() -> MqttSubscriptionManager:
+    return MqttSubscriptionManager(
+        connection=MagicMock(),
+        client_id="test_client",
+        event_emitter=MagicMock(),
+        schedule_coroutine=MagicMock(),
+    )
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "topic", "message", "expected"),
+    [
+        (
+            {"topic_suffix": "st/rsv"},
+            "cmd/52/client/res/td/rd",
+            {"response": {"reservation": []}},
+            "does not end with",
+        ),
+        (
+            {"key": "status"},
+            "cmd/52/client/res/st",
+            {"response": {}},
+            "no 'status' data to parse",
+        ),
+        (
+            {"key": "status", "only_mac": "00:11:22:33:44:55"},
+            "cmd/52/client/res/st",
+            {"status": {"macAddress": "aa:bb:cc:dd:ee:ff"}},
+            "names another device",
+        ),
+    ],
+    ids=["topic-suffix", "no-data", "other-device"],
+)
+def test_a_declined_message_says_why(kwargs, topic, message, expected, caplog):
+    """Every branch that drops a message logs its reason.
+
+    Silence here cost real diagnosis time: a reply that never reaches its
+    callback looks identical to one the cloud never sent, and the two want
+    opposite fixes.
+    """
+    delivered = []
+    handler = _manager()._make_handler(
+        model=DeviceStatus, callback=delivered.append, **kwargs
+    )
+
+    with caplog.at_level(logging.DEBUG, logger="nwp500.mqtt.subscriptions"):
+        handler(topic, message)
+
+    assert delivered == []
+    assert any(expected in r.getMessage() for r in caplog.records), caplog.text
+
+
+def test_a_declined_message_never_logs_a_raw_identifier(caplog):
+    """The reason is logged; the MAC in it is not.
+
+    These lines carry a topic and a MAC straight from the wire, so the
+    redaction is the whole reason they are safe to emit at all.
+    """
+    mac = "04786332fca0"
+    other = "aabbccddeeff"
+    topic = f"cmd/52/navilink-{mac}/st/td/rd"
+    delivered = []
+    handler = _manager()._make_handler(
+        model=DeviceStatus,
+        callback=delivered.append,
+        key="status",
+        only_mac=mac,
+        parse=lambda data: data,
+    )
+
+    with caplog.at_level(logging.DEBUG, logger="nwp500.mqtt.subscriptions"):
+        handler(topic, {"status": {"macAddress": other, "command": 0}})
+
+    assert delivered == []
+    assert "names another device" in caplog.text
+    assert mac not in caplog.text
+    assert other not in caplog.text
+    assert "REDACTED" in caplog.text
+
+
+@pytest.mark.parametrize(
+    ("level", "redactions"),
+    [(logging.INFO, 0), (logging.DEBUG, 1)],
+    ids=["debug-off", "debug-on"],
+)
+def test_declining_a_message_redacts_only_when_debug_is_on(
+    level, redactions, monkeypatch
+):
+    """The guard, not just the log level.
+
+    redact_topic is a dozen regexes, and a handler registered under the
+    device wildcard declines most of what it sees, so an unguarded call
+    would run them on the normal dispatch path for nothing.
+    """
+    calls = []
+    real = subscriptions_module.redact_topic
+
+    def counting_redact_topic(topic):
+        calls.append(topic)
+        return real(topic)
+
+    monkeypatch.setattr(
+        subscriptions_module, "redact_topic", counting_redact_topic
+    )
+    # setLevel, not the attribute: isEnabledFor caches its answer, and
+    # only setLevel invalidates that cache.
+    logger = subscriptions_module._logger
+    original_level = logger.level
+    logger.setLevel(level)
+    monkeypatch.setattr(logger, "propagate", False)
+
+    handler = _manager()._make_handler(
+        model=DeviceStatus,
+        callback=lambda parsed: None,
+        key="status",
+        topic_suffix="st/rsv",
+    )
+    try:
+        handler("cmd/52/client/res/td/rd", {"status": {"command": 0}})
+    finally:
+        logger.setLevel(original_level)
+
+    assert len(calls) == redactions
+
+
+def test_a_message_for_this_device_is_still_delivered(caplog):
+    """The mac filter accepts its own device, and says nothing about it."""
+    mac = "00:11:22:33:44:55"
+    delivered = []
+    handler = _manager()._make_handler(
+        model=DeviceStatus,
+        callback=delivered.append,
+        key="status",
+        only_mac=mac,
+        parse=lambda data: data,
+    )
+
+    with caplog.at_level(logging.DEBUG, logger="nwp500.mqtt.subscriptions"):
+        handler(
+            "cmd/52/client/res/st",
+            {"response": {"status": {"macAddress": mac, "command": 0}}},
+        )
+
+    assert len(delivered) == 1
+    assert "Ignoring" not in caplog.text

nwp500_python-9.4.1/src/nwp500_python.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "9.4.1",
-  "distance": 0,
-  "node": "g36a97ba8f8ce20912973b352fe380686a4f46ad1",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-17"
-}