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

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/.gitignore

@@ -68,3 +68,6 @@ resources/*
 .ruff_cache/
 .bandit
 .agent/
+.agents/
+.env
+skills-lock.json

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

@@ -5,6 +5,308 @@ Changelog
 Unreleased
 ==========
 
+Version 9.0.0 (2026-07-05)
+==========================
+
+**BREAKING CHANGES**: Public API surface trimmed and dead code removed.
+These changes require a major version bump.
+
+Modernization (Python 3.14)
+---------------------------
+- **Removed** ``from __future__ import annotations`` **project-wide**
+  (57 files): redundant on a Python >=3.14-only package where lazy
+  annotation evaluation (PEP 649) is the default.
+- **Adopted additional ruff rule sets**: ``RUF`` (Ruff-specific),
+  ``DTZ`` (naive datetime), ``PTH`` (pathlib), ``ASYNC``, and ``PERF``,
+  with documented ignores for intentional patterns (grouped ``__all__``
+  lists, unicode degree signs, public ``timeout`` parameters). Fixes
+  applied for all resulting findings, including a timezone-naive
+  timestamp in CSV exports (now timezone-aware local time),
+  ``Path.open()`` usage, ``itertools.pairwise()`` in the CLI range
+  collapser, a ``ClassVar`` annotation on the capability map, and
+  dangling ``asyncio.create_task`` references in tests.
+- **PeriodicRequestType is now a StrEnum** (was a plain ``Enum`` with
+  string values), matching the enum style used elsewhere.
+- **Event payload dataclasses use** ``slots=True``: the frozen event
+  dataclasses in ``mqtt_events.py`` and ``events.EventListener`` are
+  created per state change; slots reduce their memory footprint.
+- **match statement** for the periodic request-type dispatch.
+
+Testing
+-------
+- New unit tests for previously untested modules:
+  ``topic_builder.py`` (full topic schema), ``field_factory.py``
+  (metadata defaults, overrides, merge semantics), and
+  ``models/_converters.py`` (unit-preference conversions and
+  round-trips).
+
+Removed
+-------
+- **Deprecated ``.control`` property**: removed
+  ``NavienMqttClient.control`` (deprecated shim slated for v9.0.0; the
+  project policy is to remove rather than deprecate). Use the delegated
+  methods on the client directly:
+
+  .. code-block:: python
+
+     # OLD (removed)
+     await client.control.set_power(device, True)
+
+     # NEW
+     await client.set_power(device, True)
+
+- **Unused exception classes**: removed ``TokenExpiredError``,
+  ``MqttSubscriptionError``, ``DeviceNotFoundError``,
+  ``DeviceOfflineError``, and ``DeviceOperationError``. None of them was
+  ever raised by the library, so no working error handling can break;
+  catch the parent classes (``AuthenticationError``, ``MqttError``,
+  ``DeviceError``) instead.
+- **Internal plumbing removed from the top-level namespace**: the
+  package no longer re-exports ``requires_capability``,
+  ``MqttDeviceInfoCache``, ``MqttDeviceCapabilityChecker``,
+  ``log_performance``, or the bit-encoding helpers
+  (``encode_week_bitfield``, ``decode_week_bitfield``,
+  ``encode_season_bitfield``, ``decode_season_bitfield``,
+  ``encode_price``, ``decode_price``, ``build_reservation_entry``,
+  ``build_tou_period``). Import them from their owning modules:
+
+  .. code-block:: python
+
+     # OLD (removed)
+     from nwp500 import build_reservation_entry, encode_price
+
+     # NEW
+     from nwp500.encoding import build_reservation_entry, encode_price
+
+- **Dead code**: removed the never-imported ``nwp500.cli.commands``
+  module (its metadata had drifted from the real click commands), the
+  unused ``converters.str_enum_validator``, the unused module-level
+  ``temperature.half_celsius_to_fahrenheit`` /
+  ``deci_celsius_to_fahrenheit`` wrappers, the no-op
+  ``NavienMqttClient._on_message_received`` placeholder, and unused
+  width calculations in the CLI formatters.
+
+Changed
+-------
+- **Temperature classes deduplicated**: ``HalfCelsius``, ``DeciCelsius``,
+  ``RawCelsius``, and ``DeciCelsiusDelta`` were four near-identical
+  copies differing only in a scale constant. All conversions are now
+  implemented once on the ``Temperature`` base class with a per-class
+  ``_scale``; only special rounding (``RawCelsius``) and delta semantics
+  (``DeciCelsiusDelta``) are overridden. Behavior is unchanged
+  (~200 lines removed).
+- **field_factory deduplicated**: the four field factories shared a
+  copy-pasted metadata-merge block, now extracted into a single private
+  helper. Behavior is unchanged.
+- **Device boolean encoding centralized**: ``mqtt/control.py`` now uses
+  ``converters.device_bool_from_python()`` instead of inline
+  ``2 if enabled else 1`` literals.
+- **Version resolution decoupled**: ``auth.py`` resolves the package
+  version from distribution metadata instead of ``from . import
+  __version__``, removing an order-dependent near-circular import.
+
+Bug Fixes
+---------
+- **Fix malformed weekly reservation and recirculation schedule
+  payloads**: ``update_weekly_reservation()`` and
+  ``configure_recirculation_schedule()`` dumped the schedule models
+  as-is, double-nesting the request (``request.reservation.reservation``
+  / ``request.schedule.schedule``) and leaking pydantic computed display
+  fields — including a unit-converted ``temperature`` alongside the raw
+  half-Celsius ``param`` — into device commands. Both now send the flat,
+  raw protocol shape used by ``update_reservations()``. A new
+  ``NavienBaseModel.to_protocol_dict()`` dumps only declared protocol
+  fields.
+- **Preserve command order when a queued flush fails**: a command that
+  failed mid-flush was re-queued at the tail, behind commands queued
+  after it, inverting order-sensitive sequences (e.g. ``set_temp``
+  replayed before ``power_on``). The queue is now a deque and failed
+  commands are re-inserted at the front.
+- **Expire stale queued commands**: queued commands stored a timestamp
+  that was never checked, so a multi-hour outage replayed hours-old
+  control commands (e.g. ``set_power``) to the appliance on reconnect.
+  Commands older than ``MqttConnectionConfig.max_queued_command_age``
+  (default 300 s, ``None`` to disable) are now discarded at send time.
+- **Fix Fahrenheit conversion for sub-zero temperatures** (ASYMMETRIC
+  formula): the rounding used Python's floored ``%``, which is always
+  non-negative, while the firmware/app uses a truncated remainder. Raw
+  ``-11`` (-5.5 °C) decoded to 22 °F instead of the app's 23 °F. Now
+  uses ``math.fmod`` semantics.
+- **Fix freeze protection default limits**: the defaults (43/65) were
+  Fahrenheit display values stored in raw half-Celsius fields, decoding
+  to 70.7 °F / 90.5 °F when the device omitted them. Corrected to raw
+  12/20 (43 °F / 50 °F), matching the documented fixed limits.
+- **Emit error_detected when the error code changes**: a transition
+  between two non-zero error codes (e.g. E799 → E407) emitted no event,
+  so consumers kept displaying the stale error.
+- **Fix TOU price encoding**: ``encode_price()`` used banker's rounding,
+  under-encoding exact half values at even boundaries (0.125 at
+  ``decimal_point=2`` encoded to 12 instead of 13) — now uses
+  ``Decimal`` half-up rounding. ``build_tou_period()`` also treated
+  ``bool`` prices as pre-encoded integers (``True`` sent as price 1).
+- **Fix protocol documentation errors**: ``decode_reservation_hex()``
+  documented the enable flag inverted (1=enabled instead of 2=enabled);
+  the ``build_reservation_entry()`` example showed ``week: 158`` for
+  Mon/Wed/Fri instead of the correct 84; temperature doctest examples
+  showed ``int`` raw values where ``float`` is returned.
+- **Run MQTT message dispatch on the event loop**: JSON parsing, pydantic
+  model validation, and user callbacks all executed directly on the AWS
+  CRT network thread. A slow or blocking callback (e.g. the CLI monitor's
+  CSV writes) stalled all MQTT message processing, user callbacks ran on
+  an undocumented SDK thread where asyncio operations are unsafe, and the
+  handler registry could be mutated on the event loop while the CRT
+  thread iterated it (``RuntimeError: dictionary changed size during
+  iteration``, dropping the message — most likely during the
+  reconnect/resubscribe window). The awscrt callback now only marshals
+  the raw payload onto the event loop; parsing and dispatch run there,
+  iterating snapshots of the handler registries.
+- **Stop one raising handler from aborting message delivery**: handler
+  dispatch caught only ``(TypeError, AttributeError, KeyError)``; a user
+  callback raising anything else (e.g. ``ValueError``) escaped into the
+  awscrt callback machinery and skipped the remaining handlers for that
+  message. Individual handler failures are now logged and isolated.
+- **Make the unit system preference process-wide**:
+  ``set_unit_system()`` stored the preference in a ``ContextVar`` set in
+  the caller's task. Tasks scheduled from AWS CRT callback threads never
+  inherit that context, so the preference silently reverted to
+  auto-detect for all MQTT-delivered data — ``nwp-cli --unit-system
+  metric monitor`` logged temperatures in the device's native unit while
+  labeling them °C. The preference is now a process-wide setting visible
+  from every task and thread.
+- **Fix once-listeners firing more than once**: ``EventEmitter.emit()``
+  removed one-time listeners only after invoking them, so a callback
+  that raised stayed registered forever, and two overlapping emits could
+  both fire the same once-listener. Once-listeners are now removed
+  before invocation.
+- **Fix wait_for() leaking its listener on cancellation**:
+  ``EventEmitter.wait_for()`` removed its listener only on timeout; a
+  cancelled waiter left the listener registered until the event next
+  fired, setting a result on a dead future. Cleanup now happens in a
+  ``finally`` block.
+- **Fix wait_for() docstring examples**: examples showed
+  ``args, _ = await emitter.wait_for(...)``, but ``wait_for`` returns
+  just the args tuple — following the documented pattern raised
+  ``ValueError`` or silently mis-assigned.
+- **Serialize concurrent token refresh**: ``ensure_valid_token()`` and
+  ``refresh_token()`` had no lock, so concurrent callers (API 401 retry,
+  MQTT reconnect, periodic requests) at token expiry fired parallel
+  refresh requests; with token rotation the losers were left holding
+  invalidated tokens. Refreshes are now serialized behind an
+  ``asyncio.Lock`` with a post-acquire re-check: callers that lose the
+  race receive the already-refreshed tokens, callers passing a stale
+  (pre-rotation) refresh token get the fresh tokens instead of a
+  guaranteed failure, and an explicit refresh with the current token
+  still forces a refresh (deep-reconnect behavior preserved).
+- **Preserve refresh_token/id_token across refreshes**: the refresh
+  response merge preserved AWS credential fields but not
+  ``refresh_token``/``id_token``. A refresh response omitting them wiped
+  the stored refresh token, so the next refresh posted an empty string
+  and failed unconditionally.
+- **Fix aiohttp session leak when authentication fails in**
+  ``__aenter__``: Python never calls ``__aexit__`` when ``__aenter__``
+  raises, so bad credentials or a network error leaked the owned
+  ``ClientSession`` (one per retry attempt). The session is now closed
+  before the exception propagates.
+- **Make** ``NavienAuthClient.__aenter__`` **idempotent**:
+  ``create_navien_clients()`` pre-enters the context and its docstring
+  instructs users to enter again with ``async with auth:``; the second
+  entry created a fresh session and orphaned the first — which the API
+  client was still pinned to. Re-entering now reuses the existing
+  session.
+- **Fall back to full sign-in when stored-token refresh fails**:
+  restoring expired stored tokens raised ``TokenRefreshError`` even
+  though credentials for a full ``sign_in()`` were available.
+- **Stop pinning the auth session in the API client**:
+  ``NavienAPIClient`` captured ``auth_client.session`` at construction
+  and kept using it after the auth client recreated its session
+  (``RuntimeError: Session is closed``). The session is now resolved per
+  request; an explicitly provided session still takes precedence.
+- **Add HTTP timeouts to unguarded sessions**: the standalone
+  ``refresh_access_token()`` helper and ``OpenEIClient`` created
+  ``ClientSession``s without a ``ClientTimeout``; requests could hang
+  indefinitely. Both now use a 30-second total timeout.
+- **Fix reconnection loop dying on authentication errors**: the backoff
+  loop caught only ``AwsCrtError`` and ``RuntimeError``, so
+  ``TokenRefreshError``, ``AuthenticationError``, and
+  ``MqttCredentialsError`` raised during quick/deep reconnection escaped
+  and silently killed the reconnect task. A routine outage coinciding
+  with token expiry left the client permanently offline despite unlimited
+  retries. All library errors (``Nwp500Error``) and operation timeouts
+  are now treated as failed attempts and retried; only
+  ``InvalidCredentialsError`` is fatal and stops the loop with a
+  ``reconnection_failed`` event.
+- **Fix disconnect() being a no-op while the connection is interrupted**:
+  calling ``disconnect()`` during an interruption returned early without
+  disabling automatic reconnection or stopping periodic tasks, so the
+  backoff loop would resurrect the connection after the application shut
+  the client down. ``disconnect()`` now always disables reconnection and
+  stops periodic tasks, and tears down the SDK connection even when not
+  connected.
+- **Fix queued commands being lost after active/deep reconnection**: the
+  command queue was only flushed from the SDK's ``on_connection_resumed``
+  callback, which never fires for the new connection built by
+  active/deep reconnection. Commands queued while offline were silently
+  dropped. Both reconnect paths now flush the queue after subscriptions
+  are restored.
+- **Fix periodic request tasks dying on MQTT errors**: the periodic loop
+  caught only ``AwsCrtError`` and ``RuntimeError``;
+  ``MqttNotConnectedError``/``MqttPublishError`` raised by a publish
+  racing a disconnection permanently killed the polling task while it
+  still appeared active. The loop now survives all library errors.
+- **Fix silent failures in thread-scheduled coroutines**: futures
+  returned by ``run_coroutine_threadsafe`` were discarded, so exceptions
+  from scheduled work (e.g. a failed resubscribe after a clean-session
+  resume, leaving the client connected but deaf) vanished. A done
+  callback now logs them.
+- **Fix CancelledError being swallowed in reconnection and periodic
+  loops**: both loops caught ``asyncio.CancelledError`` and ``break``-ed,
+  so cancelled tasks ended "successfully" (and the reconnection loop
+  could emit ``reconnection_failed`` during a manual disconnect).
+  Cancellation now propagates correctly.
+- **Fix AttributeError in configure_reservation_water_program**: The
+  ``NavienMqttClient`` proxy referenced ``self._control``, which is never
+  assigned (the attribute is ``_device_controller``), so every call raised
+  ``AttributeError``. Now delegates correctly; a regression test guards all
+  proxies against references to the undefined attribute.
+- **Fix broken CLI mode choices**: ``nwp-cli mode vacation`` always failed
+  because vacation mode (5) requires a day count that was never supplied, and
+  ``mode standby`` sent the invalid writable mode value ``0``. Both choices
+  were removed from the ``mode`` command; use the dedicated ``vacation DAYS``
+  and ``power off`` commands instead.
+- **Fix CLI exit codes**: click ignores command return values in standalone
+  mode, so the CLI always exited ``0`` even when a command failed. Failures
+  now propagate through ``ctx.exit()`` and produce a non-zero exit code for
+  scripts and automation.
+- **Fix cached tokens being reused for a different account**: passing
+  ``--email`` for account B while tokens for account A were cached silently
+  ran commands against account A's session. Cached tokens are now discarded
+  when the provided email does not match the cached one.
+- **Surface OpenEI application errors**: OpenEI reports errors such as an
+  invalid API key in the body of an HTTP 200 response; these were masked as
+  "no rate plans found". ``fetch_rates()`` now raises ``APIError`` with the
+  API's error message.
+- **Fix broken example import**: ``examples/advanced/mqtt_diagnostics.py``
+  imported ``MqttConnectionConfig`` from the nonexistent ``nwp500.mqtt_utils``
+  module and used the deprecated ``datetime.utcnow()``.
+
+Improvements
+------------
+- **MQTT operation acknowledgement timeouts**: connect, publish,
+  subscribe, unsubscribe, and disconnect acknowledgements are now awaited
+  with a timeout (``MqttConnectionConfig.operation_timeout``, default 30
+  seconds). Previously a half-open TCP connection could hang callers
+  until the 20-minute keep-alive expired.
+- **Reconnection backoff jitter**: reconnect delays are now randomized
+  (±50%, capped at ``max_reconnect_delay``) so fleets of clients
+  disconnected simultaneously (e.g. the AWS IoT 24-hour disconnect) no
+  longer reconnect in synchronized waves.
+
+Security
+--------
+- **Restrict token cache file permissions**: ``~/.nwp500_tokens.json``
+  (refresh token and AWS credentials) was written world-readable. It is now
+  created with mode ``0600``, and existing files are tightened on save.
+
 Version 8.1.3 (2026-06-15)
 ==========================
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 8.1.3
+Version: 9.0.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-8.1.3 → nwp500_python-9.0.0}/docs/how-to/optimize-tou.rst

@@ -418,7 +418,7 @@ Encodes a floating-point price into an integer for transmission.
 
 .. code-block:: python
 
-    from nwp500 import encode_price
+    from nwp500.encoding import encode_price
     
     # Encode $0.45000 per kWh
     encoded = encode_price(0.45, decimal_point=5)
@@ -437,7 +437,7 @@ Decodes an integer price back to floating-point.
 
 .. code-block:: python
 
-    from nwp500 import decode_price
+    from nwp500.encoding import decode_price
     
     # Decode price from device
     price = decode_price(45000, decimal_point=5)
@@ -466,7 +466,7 @@ Encodes a list of day names into a bitfield.
 
 .. code-block:: python
 
-    from nwp500 import encode_week_bitfield
+    from nwp500.encoding import encode_week_bitfield
     
     # Weekdays only
     bitfield = encode_week_bitfield([
@@ -487,7 +487,7 @@ Decodes a bitfield back into a list of day names.
 
 .. code-block:: python
 
-    from nwp500 import decode_week_bitfield
+    from nwp500.encoding import decode_week_bitfield
     
     # Decode weekday bitfield
     days = decode_week_bitfield(62)
@@ -504,7 +504,8 @@ Configure two rate periods - off-peak and peak pricing:
 .. code-block:: python
 
     import asyncio
-    from nwp500 import NavienAPIClient, NavienAuthClient, NavienMqttClient, build_tou_period
+    from nwp500 import NavienAPIClient, NavienAuthClient, NavienMqttClient
+    from nwp500.encoding import build_tou_period
 
     async def configure_simple_tou():
         async with NavienAuthClient("user@example.com", "password") as auth_client:
@@ -654,7 +655,7 @@ Query the device for its current TOU configuration:
 
 .. code-block:: python
 
-    from nwp500 import decode_week_bitfield, decode_price
+    from nwp500.encoding import decode_week_bitfield, decode_price
 
     async def check_tou_settings():
         async with NavienAuthClient("user@example.com", "password") as auth_client:

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/docs/how-to/schedule-operation.rst

@@ -64,8 +64,8 @@ Quick Example
        NavienAuthClient,
        NavienAPIClient,
        NavienMqttClient,
-       build_reservation_entry,
    )
+   from nwp500.encoding import build_reservation_entry
 
    async def main():
        async with NavienAuthClient(
@@ -279,7 +279,7 @@ Helper Functions
 
 .. code-block:: python
 
-   from nwp500 import build_reservation_entry
+   from nwp500.encoding import build_reservation_entry
 
    entry = build_reservation_entry(
        enabled=True,
@@ -589,8 +589,8 @@ want to send the whole weekly program as one typed object.
    from nwp500 import (
        WeeklyReservationEntry,
        WeeklyReservationSchedule,
-       build_reservation_entry,
    )
+   from nwp500.encoding import build_reservation_entry
 
    morning = WeeklyReservationEntry.model_validate(
        build_reservation_entry(

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/docs/reference/python_api/auth_client.rst

@@ -529,7 +529,6 @@ Error Handling
 
    from nwp500 import (
        InvalidCredentialsError,
-       TokenExpiredError,
        TokenRefreshError,
        AuthenticationError
    )
@@ -543,9 +542,6 @@ Error Handling
        except InvalidCredentialsError:
            print("Wrong email or password")
        
-       except TokenExpiredError:
-           print("Token expired and refresh failed")
-       
        except TokenRefreshError:
            print("Could not refresh token - sign in again")
        

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/docs/reference/python_api/cli.rst

@@ -224,12 +224,6 @@ Set operation mode.
    # High Demand (maximum capacity)
    python3 -m nwp500.cli mode high-demand
 
-   # Vacation Mode
-   python3 -m nwp500.cli mode vacation
-
-   # Standby
-   python3 -m nwp500.cli mode standby
-
 **Syntax:**
 
 .. code-block:: bash
@@ -238,12 +232,13 @@ Set operation mode.
 
 **Available Modes:**
 
-* ``standby`` - Device off but ready
-* ``heat-pump`` - Heat pump only (0)
+* ``heat-pump`` - Heat pump only (1)
 * ``electric`` - Electric heating only (2)
 * ``energy-saver`` - Hybrid/balanced mode (3) **recommended**
 * ``high-demand`` - Maximum heating capacity (4)
-* ``vacation`` - Extended vacancy mode (5)
+
+For vacation mode use the ``vacation`` command (it requires a day count);
+to power the unit off use the ``power`` command.
 
 **Output:** Confirmation message and updated device status.
 

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/docs/reference/python_api/exceptions.rst

@@ -15,22 +15,17 @@ All library exceptions inherit from ``Nwp500Error``::
     Nwp500Error (base)
     ├── AuthenticationError
     │   ├── InvalidCredentialsError
-    │   ├── TokenExpiredError
     │   └── TokenRefreshError
     ├── APIError
     ├── MqttError
     │   ├── MqttConnectionError
     │   ├── MqttNotConnectedError
     │   ├── MqttPublishError
-    │   ├── MqttSubscriptionError
     │   └── MqttCredentialsError
     ├── ValidationError
     │   ├── ParameterValidationError
     │   └── RangeValidationError
     └── DeviceError
-        ├── DeviceNotFoundError
-        ├── DeviceOfflineError
-        ├── DeviceOperationError
         └── DeviceCapabilityError
 
 Base Exception
@@ -134,16 +129,6 @@ InvalidCredentialsError
           print("Please check your email and password")
           # Prompt user to re-enter credentials
 
-TokenExpiredError
------------------
-
-.. py:class:: TokenExpiredError
-
-   Raised when an authentication token has expired.
-
-   Subclass of :py:class:`AuthenticationError`. Tokens have a limited lifetime
-   and must be refreshed periodically.
-
 TokenRefreshError
 -----------------
 
@@ -305,16 +290,6 @@ MqttPublishError
                   else:
                       raise  # Not retriable or max retries reached
 
-MqttSubscriptionError
----------------------
-
-.. py:class:: MqttSubscriptionError
-
-   Failed to subscribe to MQTT topic.
-
-   Raised when subscription to an MQTT topic fails. This may occur if the
-   connection is interrupted or if the client lacks permissions for the topic.
-
 MqttCredentialsError
 --------------------
 
@@ -409,38 +384,6 @@ DeviceError
 
    All device-related errors inherit from this base class.
 
-DeviceNotFoundError
--------------------
-
-.. py:class:: DeviceNotFoundError
-
-   Requested device not found.
-
-   Raised when a device cannot be found in the user's device list or when
-   attempting to access a non-existent device.
-
-DeviceOfflineError
-------------------
-
-.. py:class:: DeviceOfflineError
-
-   Device is offline or unreachable.
-
-   Raised when a device is offline and cannot respond to commands or status
-   requests. The device may be powered off, disconnected from the network,
-   or experiencing connectivity issues.
-
-DeviceOperationError
---------------------
-
-.. py:class:: DeviceOperationError
-
-   Device operation failed.
-
-   Raised when a device operation (mode change, temperature setting, etc.)
-   fails. This may occur due to invalid commands, device restrictions, or
-   device-side errors.
-
 DeviceCapabilityError
 ---------------------
 

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/docs/reference/python_api/mqtt_client.rst

@@ -467,7 +467,7 @@ update_reservations()
 
    .. code-block:: python
 
-      from nwp500 import build_reservation_entry
+      from nwp500.encoding import build_reservation_entry
 
       reservations = [
           build_reservation_entry(

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/examples/advanced/mqtt_diagnostics.py

@@ -27,8 +27,7 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from nwp500 import NavienAuthClient, NavienMqttClient
-from nwp500.mqtt import MqttDiagnosticsCollector
-from nwp500.mqtt_utils import MqttConnectionConfig
+from nwp500.mqtt import MqttConnectionConfig, MqttDiagnosticsCollector
 
 # Configure logging to show detailed MQTT information
 logging.basicConfig(
@@ -85,7 +84,7 @@ class MqttDiagnosticsExample:
                 output_file = self.output_dir / f"diagnostics_{timestamp}.json"
 
                 json_data = self.diagnostics.export_json()
-                with open(output_file, "w") as f:
+                with output_file.open("w") as f:
                     f.write(json_data)
 
                 _logger.info(f"Exported diagnostics to {output_file}")
@@ -275,9 +274,9 @@ class MqttDiagnosticsExample:
 
                     # Final export
                     _logger.info("Exporting final diagnostics...")
-                    timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+                    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
                     final_file = self.output_dir / f"diagnostics_final_{timestamp}.json"
-                    with open(final_file, "w") as f:
+                    with final_file.open("w") as f:
                         f.write(self.diagnostics.export_json())
                     _logger.info(f"Final diagnostics saved to {final_file}")
 

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/examples/advanced/tou_openei.py

@@ -21,6 +21,8 @@ from nwp500 import (
     NavienAuthClient,
     NavienMqttClient,
     OpenEIClient,
+)
+from nwp500.encoding import (
     decode_price,
     decode_week_bitfield,
 )

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/examples/mask.py

@@ -4,8 +4,6 @@ Place this file in the examples/ directory. Example scripts will try to import
 these helpers; if that import fails we leave a small fallback in each script.
 """
 
-from __future__ import annotations
-
 import re
 
 

{nwp500_python-8.1.3 → nwp500_python-9.0.0}/pyproject.toml

@@ -57,11 +57,30 @@ select = [
     "C4",    # flake8-comprehensions
     "SIM",   # flake8-simplify
     "S",     # flake8-bandit (security)
+    "RUF",   # Ruff-specific rules (incl. unused noqa)
+    "DTZ",   # flake8-datetimez (naive datetime usage)
+    "PTH",   # flake8-use-pathlib
+    "ASYNC", # flake8-async
+    "PERF",  # perflint
 ]
 
 ignore = [
     "E203",  # whitespace before ':' (conflicts with black/ruff format)
     "B904",  # raise from - will be addressed in a future update
+    # Async functions taking a `timeout:` parameter are a deliberate,
+    # documented public API of this library (e.g. wait_for, command
+    # helpers); switching callers to asyncio.timeout() would be a
+    # breaking change with no behavioral benefit.
+    "ASYNC109",
+    # Degree signs, en-dashes, and multiplication signs in docstrings
+    # and user-facing strings are intentional (temperature units,
+    # ranges), not typos of ASCII look-alikes.
+    "RUF001",
+    "RUF002",
+    "RUF003",
+    # __all__ lists are deliberately grouped by category with comments,
+    # not sorted alphabetically.
+    "RUF022",
 ]
 
 # Allow autofix for all enabled rules (when `--fix` is provided)