nwp500-python 9.0.0__tar.gz → 9.2.0__tar.gz

{nwp500_python-9.0.0 → nwp500_python-9.2.0}/CHANGELOG.rst

@@ -5,6 +5,115 @@ Changelog
 Unreleased
 ==========
 
+Version 9.2.0 (2026-07-06)
+==========================
+
+Changed
+-------
+- **CLI formatting stacks merged; Rich is the sole human renderer**
+  (`#100 <https://github.com/eman/nwp500-python/issues/100>`_): a new
+  ``src/nwp500/cli/presentation.py`` owns all data-shaping for CLI output
+  (field selection, labels, units, ordering, value formatting and energy
+  aggregation) as presentation-neutral structures. Because the CLI
+  hard-requires ``rich`` (there is no plain-text fallback), the redundant
+  plain-text human renderer and the Rich-vs-plain fallback machinery were
+  removed: ``rich_output.py`` no longer contains ``_should_use_rich``,
+  ``_rich_available``, the ``NWP500_NO_RICH`` toggle, or any
+  ``_print_*_plain`` methods, and now renders the neutral structures
+  (including the energy ``TOTAL SUMMARY``) exclusively with Rich, consuming
+  the presentation dataclasses directly instead of dict adapters.
+  ``output_formatters.py`` keeps only JSON/CSV rendering plus thin
+  human-output dispatch. Net CLI code drops from ~2088 to ~1838 lines with a
+  single data-shaping layer and a single human renderer. Non-energy output
+  is byte-for-byte unchanged (verified by golden capture and the existing
+  CLI tests); energy output now renders a summary table plus a breakdown
+  table entirely in Rich rather than printing plain text and a Rich table.
+- **mqtt/client.py slimmed toward a thin façade** (`#99
+  <https://github.com/eman/nwp500-python/issues/99>`_): the ~40 device
+  control command proxies and the typed ``subscribe_*``/``unsubscribe_*``
+  device-subscription proxies were moved out of ``NavienMqttClient`` into
+  two focused mixins, ``DeviceControlCommandsMixin``
+  (``mqtt/_control_commands.py``) and ``DeviceSubscriptionsMixin``
+  (``mqtt/_device_subscriptions.py``). ``NavienMqttClient`` now inherits
+  both, so its public API is unchanged, while ``mqtt/client.py`` shrinks
+  from ~1572 to ~1196 lines and reads more clearly as connection
+  orchestration plus a public façade. No behavior change.
+- **Event system relationship clarified and de-duplicated** (`#102
+  <https://github.com/eman/nwp500-python/issues/102>`_): ``events.py`` and
+  ``mqtt_events.py`` are not two competing event mechanisms.
+  ``EventEmitter`` (``events.py``) is the sole delivery mechanism, while
+  ``mqtt_events.py`` provides the event-name registry
+  (``MqttClientEvents``) and the typed dataclass payloads it carries.
+  Internal ``emit`` call sites in ``mqtt/state_tracker.py``,
+  ``mqtt/client.py`` and ``mqtt/subscriptions.py`` now reference the
+  ``MqttClientEvents`` constants instead of duplicating the raw event-name
+  strings, so each event name is defined in exactly one place. Module
+  docstrings and the event-system reference docs were updated to document
+  the relationship, and typed-payload delivery is now covered by tests.
+- **awscrt types wrapped out of public MQTT signatures** (`#101
+  <https://github.com/eman/nwp500-python/issues/101>`_): the library no
+  longer exposes ``awscrt`` SDK types on its own public/semi-public API
+  surface. A library-owned ``nwp500.mqtt.QoS`` ``IntEnum`` (also exported
+  as ``nwp500.QoS``) now replaces ``awscrt.mqtt.QoS`` on the ``publish``
+  and ``subscribe`` methods of ``NavienMqttClient``, ``MqttConnection``
+  and ``MqttSubscriptionManager``, on ``MqttCommandQueue.enqueue`` and on
+  the ``QueuedCommand`` dataclass. ``awscrt.mqtt.Connection`` handles are
+  typed behind the ``MqttConnectionHandle`` alias, and translation to/from
+  ``awscrt`` happens only at the connection-layer boundary
+  (``nwp500/mqtt/types.py``). ``NavienMqttClient.publish`` now wraps
+  otherwise-uncaught ``AwsCrtError`` in ``MqttPublishError`` so ``awscrt``
+  exceptions no longer leak out of the public boundary.
+
+  .. code-block:: python
+
+     # OLD
+     from awscrt import mqtt
+     await client.publish(topic, payload, qos=mqtt.QoS.AT_LEAST_ONCE)
+
+     # NEW
+     from nwp500 import QoS
+     await client.publish(topic, payload, qos=QoS.AT_LEAST_ONCE)
+
+Fixed
+-----
+- **MQTT ack futures now consumed on abandonment** (`#97
+  <https://github.com/eman/nwp500-python/issues/97>`_): ``_await_ack()``
+  in ``mqtt/connection.py`` and the inline subscribe/unsubscribe
+  acknowledgement waits in ``mqtt/subscriptions.py`` shield the AWS CRT
+  future so a timeout or cancellation doesn't propagate into the SDK
+  future. Previously, if the shielded future later completed with an
+  exception (e.g. ``AwsCrtError`` from clean-session cancellation during
+  reconnect) after the awaiting task had already given up, nobody
+  retrieved that exception, and asyncio logged a "Future exception was
+  never retrieved" warning at garbage-collection time. A done callback
+  is now attached whenever a wait is abandoned so the eventual
+  result/exception is always retrieved and logged at debug level
+  instead of leaking as an unhandled asyncio warning.
+
+Documentation
+-------------
+- **Unit-system preference is a deliberate process-wide global** (`#103
+  <https://github.com/eman/nwp500-python/issues/103>`_): clarified and
+  locked in that the preference in ``nwp500.unit_system`` is an intentional
+  process-wide module-level global rather than a
+  ``contextvars.ContextVar``. A context-local value silently reverted to
+  auto-detect for real-time data because MQTT message handling runs in tasks
+  scheduled from AWS CRT callback threads whose context never inherits from
+  the application task. Added prominent docstring notes to the affected
+  models (``DeviceStatus``, ``DeviceFeature``, ``ReservationEntry``,
+  ``WeeklyReservationEntry``, and ``TOUPeriod``) explaining that unit-aware
+  computed fields read the preference at access time and share it across all
+  async tasks and threads. This is a non-breaking documentation and test
+  change; no API changes.
+
+Added
+-----
+- **Tests for process-wide unit-system semantics** (`#103
+  <https://github.com/eman/nwp500-python/issues/103>`_): new
+  ``tests/test_unit_system_process_wide.py`` verifies that setting the global
+  preference affects already-constructed model instances at access time and
+  that the preference is visible across async tasks and threads.
+
 Version 9.0.0 (2026-07-05)
 ==========================
 

{nwp500_python-9.0.0/src/nwp500_python.egg-info → nwp500_python-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.0.0
+Version: 9.2.0
 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.0.0 → nwp500_python-9.2.0}/docs/reference/python_api/events.rst

@@ -17,6 +17,23 @@ Use the event system when you want to react to connection changes, status
 transitions, or derived state changes such as temperature deltas and error
 conditions.
 
+How the pieces fit together
+---------------------------
+
+The event system is split across two complementary modules:
+
+* :mod:`nwp500.events` provides the delivery **mechanism** — the generic
+  :class:`~nwp500.events.EventEmitter` (multiple listeners, async handlers,
+  one-time listeners, priority ordering). ``NavienMqttClient`` extends it.
+* :mod:`nwp500.mqtt_events` provides the **vocabulary** — the
+  :class:`~nwp500.mqtt_events.MqttClientEvents` name registry and the typed,
+  frozen dataclass payloads carried by each event.
+
+These are not two competing systems. Internal ``emit`` call sites reference the
+``MqttClientEvents`` constants and emit the matching payload dataclass, and you
+subscribe with the same constants, so an event name is defined in exactly one
+place.
+
 Two Subscription Patterns
 =========================
 

{nwp500_python-9.0.0 → nwp500_python-9.2.0}/scripts/bump_version.py

@@ -20,17 +20,20 @@ field is for the PyScaffold tool version, not the package version!
 """
 
 import re
+import shutil
 import subprocess
 import sys
-from datetime import date
+from datetime import datetime
 from pathlib import Path
 
+GIT = shutil.which("git") or "git"
 
-def run_git_command(args: list) -> str:
+
+def run_git_command(args: list[str]) -> str:
     """Run a git command and return the output."""
     try:
-        result = subprocess.run(
-            ["git"] + args,
+        result = subprocess.run(  # noqa: S603
+            [GIT, *args],
             capture_output=True,
             text=True,
             check=True,
@@ -142,6 +145,73 @@ def check_working_directory_clean() -> None:
         sys.exit(1)
 
 
+def check_up_to_date_with_remote() -> None:
+    """Ensure the local branch is in sync with its remote before bumping.
+
+    Running the version bump from a stale local checkout can silently drop
+    CHANGELOG.rst entries: the local file is missing changes (e.g. a prior
+    release's changelog section) that already exist upstream, so the diff
+    inserted by update_changelog() is based on outdated content and the
+    upstream entry never makes it back in once pushed/merged.
+    """
+    branch = run_git_command(["rev-parse", "--abbrev-ref", "HEAD"])
+    upstream = subprocess.run(  # noqa: S603
+        [GIT, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+        capture_output=True,
+        text=True,
+    )
+    if upstream.returncode != 0:
+        print(
+            f"Warning: Branch '{branch}' has no upstream tracking branch; "
+            "skipping remote sync check.",
+            file=sys.stderr,
+        )
+        return
+
+    upstream_ref = upstream.stdout.strip()
+
+    # Fetch quietly so the comparison below reflects the latest remote state.
+    fetch = subprocess.run(  # noqa: S603
+        [GIT, "fetch", "--quiet"],
+        capture_output=True,
+        text=True,
+    )
+    if fetch.returncode != 0:
+        print(
+            f"Warning: 'git fetch' failed, remote sync check may be stale: "
+            f"{fetch.stderr.strip()}",
+            file=sys.stderr,
+        )
+
+    local_sha = run_git_command(["rev-parse", "HEAD"])
+    upstream_sha = run_git_command(["rev-parse", upstream_ref])
+
+    if local_sha == upstream_sha:
+        return
+
+    behind = run_git_command(["rev-list", "--count", f"HEAD..{upstream_ref}"])
+    ahead = run_git_command(["rev-list", "--count", f"{upstream_ref}..HEAD"])
+
+    if int(behind) > 0:
+        print(
+            f"Error: Local branch '{branch}' is {behind} commit(s) behind "
+            f"'{upstream_ref}'.",
+            file=sys.stderr,
+        )
+        print(
+            "Pull the latest changes before bumping the version, otherwise "
+            "CHANGELOG.rst entries from other releases may be lost.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if int(ahead) > 0:
+        print(
+            f"Warning: Local branch '{branch}' is {ahead} commit(s) ahead of "
+            f"'{upstream_ref}' (unpushed commits)."
+        )
+
+
 def update_changelog(version: str) -> None:
     """Insert a version heading into CHANGELOG.rst below the Unreleased section.
 
@@ -169,7 +239,8 @@ def update_changelog(version: str) -> None:
 
     content = changelog_path.read_text(encoding="utf-8")
 
-    heading = f"Version {version} ({date.today().isoformat()})"
+    today = datetime.now().astimezone().date().isoformat()
+    heading = f"Version {version} ({today})"
     underline = "=" * len(heading)
     version_block = f"{heading}\n{underline}\n"
 
@@ -177,7 +248,7 @@ def update_changelog(version: str) -> None:
     # one or more blank lines, then insert the version block after them.
     pattern = re.compile(
         r"(Unreleased\n=+\n)"  # group 1: Unreleased heading
-        r"(\n+)",              # group 2: blank line(s) separator
+        r"(\n+)",  # group 2: blank line(s) separator
         re.MULTILINE,
     )
 
@@ -192,10 +263,7 @@ def update_changelog(version: str) -> None:
 
     # Insert the version block after the blank lines that follow "Unreleased"
     new_content = (
-        content[: match.end()]
-        + version_block
-        + "\n"
-        + content[match.end() :]
+        content[: match.end()] + version_block + "\n" + content[match.end() :]
     )
 
     changelog_path.write_text(new_content, encoding="utf-8")
@@ -205,20 +273,18 @@ def update_changelog(version: str) -> None:
 def commit_changelog(version: str) -> None:
     """Stage and commit the CHANGELOG.rst update."""
     run_git_command(["add", "CHANGELOG.rst"])
-    run_git_command(
-        ["commit", "-m", f"Update changelog for v{version}"]
-    )
+    run_git_command(["commit", "-m", f"Update changelog for v{version}"])
     print("[OK] Committed changelog update")
 
 
-def create_tag(version: str, message: str = None) -> None:
+def create_tag(version: str, message: str | None = None) -> None:
     """Create a git tag for the version."""
     tag_name = f"v{version}"
 
     # Check if tag already exists
     try:
-        subprocess.run(
-            ["git", "rev-parse", tag_name],
+        subprocess.run(  # noqa: S603
+            [GIT, "rev-parse", tag_name],
             capture_output=True,
             check=True,
         )
@@ -283,6 +349,10 @@ def main() -> None:
     # Check working directory is clean
     check_working_directory_clean()
 
+    # Ensure we're not bumping from a stale checkout, which can silently
+    # drop CHANGELOG.rst entries from releases made on the remote branch.
+    check_up_to_date_with_remote()
+
     # Get current version
     current_version = get_current_version()
     print(f"Current version: {current_version}")

{nwp500_python-9.0.0 → nwp500_python-9.2.0}/src/nwp500/__init__.py

@@ -110,6 +110,7 @@ from nwp500.mqtt import (
     MqttMetrics,
     NavienMqttClient,
     PeriodicRequestType,
+    QoS,
 )
 from nwp500.mqtt_events import (
     MqttClientEvents,
@@ -221,6 +222,7 @@ __all__ = [
     "MqttMetrics",
     "ConnectionDropEvent",
     "ConnectionEvent",
+    "QoS",
     # Event Emitter
     "EventEmitter",
     "EventListener",

nwp500_python-9.2.0/src/nwp500/cli/output_formatters.py

@@ -0,0 +1,172 @@
+"""CSV and JSON renderers plus human-output dispatch for the CLI.
+
+Data-shaping (which fields, labels, units, ordering, aggregation) lives in
+:mod:`.presentation`; human-readable rendering is delegated to the Rich
+renderer in :mod:`.rich_output`, which consumes the same neutral structures.
+This module additionally handles the genuinely different CSV and JSON outputs.
+"""
+
+import csv
+import json
+import logging
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from nwp500 import DeviceStatus
+
+from .presentation import (
+    build_daily_energy_report,
+    build_device_info_rows,
+    build_device_status_rows,
+    build_energy_report,
+)
+from .rich_output import get_formatter
+
+_logger = logging.getLogger(__name__)
+
+
+def _json_default_serializer(obj: Any) -> Any:
+    """Serialize objects not serializable by default json code.
+
+    Note: Enums are handled by model.model_dump() which converts them to names.
+    This function handles any remaining non-JSON-serializable types that might
+    appear in raw MQTT messages.
+
+    Args:
+        obj: Object to serialize
+
+    Returns:
+        JSON-serializable representation of the object
+
+    Raises:
+        TypeError: If object cannot be serialized
+    """
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, Enum):
+        return obj.name  # Fallback for any enums not in model output
+    # Handle Pydantic models
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump()
+    raise TypeError(f"Type {type(obj)} not serializable")
+
+
+def print_energy_usage(energy_response: Any) -> None:
+    """Print energy usage data (summary + monthly breakdown) via Rich.
+
+    Args:
+        energy_response: EnergyUsageResponse object
+    """
+    report = build_energy_report(energy_response)
+    get_formatter().print_energy_table(report)
+
+
+def print_daily_energy_usage(
+    energy_response: Any, year: int, month: int
+) -> None:
+    """Print daily energy usage for a specific month via Rich.
+
+    Args:
+        energy_response: EnergyUsageResponse object
+        year: Year to filter for (e.g., 2025)
+        month: Month to filter for (1-12)
+    """
+    report = build_daily_energy_report(energy_response, year, month)
+    formatter = get_formatter()
+    if report is None:
+        formatter.print_info(
+            f"No daily energy data available for {month}/{year}"
+        )
+        return
+    formatter.print_daily_energy_table(report)
+
+
+def write_status_to_csv(file_path: str, status: DeviceStatus) -> None:
+    """
+    Append device status to a CSV file.
+
+    Args:
+        file_path: Path to the CSV file
+        status: DeviceStatus object to write
+    """
+    try:
+        # Convert status to dict (enums are already converted to names)
+        status_dict = status.model_dump()
+
+        # Add a timestamp to the beginning of the data (timezone-aware,
+        # in the local timezone)
+        status_dict["timestamp"] = datetime.now().astimezone().isoformat()
+
+        # Check if file exists to determine if we need to write the header
+        file_exists = Path(file_path).exists()
+
+        with Path(file_path).open("a", newline="") as csvfile:
+            # Get the field names from the dict keys
+            fieldnames = list(status_dict.keys())
+            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+
+            # Write header only if this is a new file
+            if not file_exists:
+                writer.writeheader()
+
+            writer.writerow(status_dict)
+
+        _logger.debug(f"Status written to {file_path}")
+
+    except OSError as e:
+        _logger.error(f"Failed to write to CSV: {e}")
+
+
+def format_json_output(data: Any, indent: int = 2) -> str:
+    """
+    Format data as JSON string with custom serialization.
+
+    Args:
+        data: Data to format
+        indent: Number of spaces for indentation (default: 2)
+
+    Returns:
+        JSON-formatted string
+    """
+    return json.dumps(data, indent=indent, default=_json_default_serializer)
+
+
+def print_json(data: Any, indent: int = 2) -> None:
+    """
+    Print data as formatted JSON with optional syntax highlighting.
+
+    Uses Rich highlighting when available, falls back to plain JSON otherwise.
+
+    Args:
+        data: Data to print
+        indent: Number of spaces for indentation (default: 2)
+    """
+    json_str = format_json_output(data, indent)
+    formatter = get_formatter()
+    formatter.print_json_highlighted(json.loads(json_str))
+
+
+def print_device_status(device_status: Any) -> None:
+    """
+    Print device status with aligned columns and dynamic width calculation.
+
+    Units are automatically extracted from the DeviceStatus model metadata.
+
+    Args:
+        device_status: DeviceStatus object
+    """
+    formatter = get_formatter()
+    formatter.print_status_table(build_device_status_rows(device_status))
+
+
+def print_device_info(device_feature: Any) -> None:
+    """
+    Print device information with aligned columns and dynamic width calculation.
+
+    Args:
+        device_feature: DeviceFeature object
+    """
+    formatter = get_formatter()
+    formatter.print_status_table(build_device_info_rows(device_feature))