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

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

@@ -5,6 +5,36 @@ 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)
+==========================
+
+Fixed
+-----
+- **The reconnect attempt counter never reset after a successful quick or
+  deep reconnect.** Both build a new connection, so the SDK never calls
+  ``on_connection_resumed``, the only place the counter was reset. Each
+  later interruption started where the last one stopped: its first delay
+  was longer and it reached the deep-reconnect threshold sooner. A
+  long-running client saw the first delay grow from about 1 s to 12 s
+  over five daily AWS IoT disconnects. The counter now resets whenever the
+  backoff loop ends connected.
+
 Version 9.4.0 (2026-09-12)
 ==========================
 

{nwp500_python-9.4.0 → 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.0/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.0
+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.0 → nwp500_python-9.4.2}/docs/explanation/tank-energy.rst

@@ -3,7 +3,7 @@ Tank Energy
 ===========
 
 The NWP500 reports two energy figures, ``totalEnergyCapacity`` and
-``availableEnergyCapacity``. Both names mislead, and before v10.0 this
+``availableEnergyCapacity``. Both names mislead, and before v9.3.0 this
 library also scaled them wrongly. This page explains what they
 actually measure and shows the evidence for the correction.
 
@@ -33,7 +33,7 @@ The short version
        whenever the setpoint moves.
 
 Both are raw counts of 4 Wh each, not Watt-hours. Library versions before
-10.0 multiplied by 10, overstating tank energy by 2.5x.
+9.3.0 multiplied by 10, overstating tank energy by 2.5x.
 
 Both are also measured **from the setpoint**, so both describe potential
 rather than content: move the setpoint and both change while the water in
@@ -226,7 +226,7 @@ coefficient of performance:
    * - 4 Wh/count (corrected)
      - 2.89
      - Normal for a heat pump water heater
-   * - 10 Wh/count (pre-10.0)
+   * - 10 Wh/count (pre-9.3.0)
      - 7.02
      - Physically impossible
 
@@ -236,7 +236,7 @@ A heat pump water heater in a 72 degF room runs at a COP of roughly 2 to
 This argument is worth stating separately because it needs no tank
 volume, specific heat or stratification model - only the device's own
 reported energy and its own reported power. It cannot tell you what the
-quantum *is*, but it rules out the pre-10.0 value regardless of anything
+quantum *is*, but it rules out the pre-9.3.0 value regardless of anything
 assumed elsewhere on this page.
 
 .. _two branches:
@@ -403,8 +403,8 @@ the heat capacity is 156 Wh per degF:
    drawable_Wh = 156 * (tank_mean_temperature - your_floor_degF)
 
 
-Migrating from before v10.0
-===========================
+Migrating from before v9.3.0
+============================
 
 .. list-table::
    :header-rows: 1
@@ -429,7 +429,7 @@ rename that is missed fails immediately with ``AttributeError`` instead
 of silently returning a number 2.5x too large.
 
 If you logged these values historically, the stored series needs
-rescaling by 0.4 to be comparable with values from v10.0 onward.
+rescaling by 0.4 to be comparable with values from v9.3.0 onward.
 
 
 See also

{nwp500_python-9.4.0 → nwp500_python-9.4.2}/docs/reference/protocol/data_conversions.rst

@@ -367,7 +367,7 @@ Power and Energy Fields
    candidate implying a water volume below the nameplate. Two further
    checks agree -- 183 heating recoveries give 4.11 Wh/count by a
    noisier route, and the same recoveries imply a heat-pump COP of 2.89.
-   The library uses 4.0. Versions before 10.0 used 10, which overstated
+   The library uses 4.0. Versions before 9.3.0 used 10, which overstated
    reported tank energy by 2.5x and implied a physically impossible COP
    of 7.0. See :doc:`../../explanation/tank-energy`.
 

{nwp500_python-9.4.0 → nwp500_python-9.4.2}/docs/reference/python_api/models.rst

@@ -263,7 +263,7 @@ Complete real-time device status with 100+ fields.
 
    .. warning::
       These replace ``total_energy_capacity`` and
-      ``available_energy_capacity``, which were **removed** in v10.0. The
+      ``available_energy_capacity``, which were **removed** in v9.3.0. The
       old names were misleading -- ``available_energy_capacity`` is the
       energy *needed*, not the energy available -- and both were scaled
       2.5x too large. For energy you can actually draw, see

{nwp500_python-9.4.0 → nwp500_python-9.4.2}/src/nwp500/converters.py

@@ -45,7 +45,7 @@ __all__ = [
 #:   p90 4.45), agreeing to within 2% by a noisier route
 #: * the same recoveries imply a heat pump COP of 2.89 at 4 Wh/count
 #:
-#: Library versions before 10.0 used 10 Wh/count, which overstated reported
+#: Library versions before 9.3.0 used 10 Wh/count, which overstated reported
 #: tank energy by 2.5x and implied a physically impossible COP of 7.0.
 #:
 #: See ``docs/explanation/tank-energy.rst`` for the full derivation.

{nwp500_python-9.4.0 → nwp500_python-9.4.2}/src/nwp500/mqtt/reconnection.py

@@ -347,6 +347,13 @@ class MqttReconnectionHandler:
                     f"Error during reconnection attempt: {e}", exc_info=True
                 )
 
+        # A successful quick or deep reconnect builds a new connection, so
+        # the SDK never calls on_connection_resumed for it. Reset the
+        # counter here, or every later interruption starts with a longer
+        # backoff and an earlier deep reconnect than the first one did.
+        if self._is_connected_func():
+            self._reconnect_attempts = 0
+
         # Check final state: report failure when retries are exhausted
         # (limited mode) or a fatal error stopped the loop.
         attempts_exhausted = (

{nwp500_python-9.4.0 → 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.0 → 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.0
+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.0 → nwp500_python-9.4.2}/tests/test_mqtt_reliability.py

@@ -231,6 +231,45 @@ class TestReconnectLoopExceptionHandling:
         assert all(d <= config.max_reconnect_delay for d in sleeps)
         assert all(d > 0 for d in sleeps)
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("deep", [False, True])
+    async def test_successful_reconnect_resets_attempt_count(self, deep):
+        """Regression: a quick or deep reconnect makes a new connection, so
+        on_connection_resumed never fires and the counter kept growing
+        across interruptions, lengthening each later backoff."""
+        connected = False
+        attempts = []
+
+        async def reconnect():
+            nonlocal connected
+            attempts.append(1)
+            # Fail the first try of each interruption, then succeed.
+            if len(attempts) % 2 == 0:
+                connected = True
+                return
+            raise MqttNotConnectedError("down")
+
+        kwargs = {"deep_reconnect_func": reconnect} if deep else {}
+        config = _fast_config(
+            max_reconnect_attempts=-1,
+            deep_reconnect_threshold=1,
+        )
+        handler = _make_handler(
+            config,
+            lambda: connected,
+            reconnect,
+            **kwargs,
+        )
+        handler.enable()
+
+        for _ in range(3):
+            connected = False
+            await handler._reconnect_with_backoff()
+            assert connected
+            assert handler.attempt_count == 0
+
+        assert len(attempts) == 6
+
 
 class TestDisconnectDuringInterruption:
     """disconnect() must fully shut down even when not connected."""

{nwp500_python-9.4.0 → 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.0/src/nwp500_python.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "9.4.0",
-  "distance": 0,
-  "node": "g14ff7fc4c8672df4b22b6ec222f49a67fcf78a50",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-13"
-}