nwp500-python 7.1.0__tar.gz → 7.2.1__tar.gz

{nwp500_python-7.1.0 → nwp500_python-7.2.1}/.github/copilot-instructions.md

@@ -45,6 +45,15 @@ The version bump script:
 
 **Validation**: Run `make validate-version` to check for version-related mistakes before committing.
 
+### Review Comments
+
+When working on pull requests, use the GitHub CLI to access review comments:
+- **List review comments**: `gh pr review-comment list --repo=<owner>/<repo>`
+- **Get PR details with reviews**: `gh pr view <number> --repo=<owner>/<repo>`
+- **Apply review feedback** before final submission
+
+This ensures you can address all feedback from code reviewers systematically.
+
 ### Before Committing Changes
 Always run these checks before finalizing changes to ensure your code will pass CI:
 1. **Linting**: `make ci-lint` - Ensures code style matches CI requirements

{nwp500_python-7.1.0 → nwp500_python-7.2.1}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.13'
       
       - name: Install tox
         run: |
@@ -68,7 +68,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.13'
       
       - name: Install build dependencies
         run: |

{nwp500_python-7.1.0 → nwp500_python-7.2.1}/CHANGELOG.rst

@@ -2,6 +2,303 @@
 Changelog
 =========
 
+Version 7.2.1 (2025-12-25)
+==========================
+
+Added
+-----
+- **CLI Command**: New ``device-info`` command to retrieve basic device information from REST API
+  
+  .. code-block:: bash
+  
+     # Get basic device info (DeviceInfo model)
+     python3 -m nwp500.cli device-info
+     python3 -m nwp500.cli device-info --raw
+
+- **ConnectionStatus Enum**: New ``ConnectionStatus`` enum for device cloud connection state
+  
+  - ``ConnectionStatus.DISCONNECTED`` = 1 - Device offline/not connected
+  - ``ConnectionStatus.CONNECTED`` = 2 - Device online and reachable
+  - Used in ``DeviceInfo.connected`` field with automatic validation
+
+- **InstallType Enum**: New ``InstallType`` enum for device installation classification
+  
+  - ``InstallType.RESIDENTIAL`` = "R" - Residential use
+  - ``InstallType.COMMERCIAL`` = "C" - Commercial use
+  - Used in ``DeviceInfo.install_type`` field with automatic validation
+  - Includes ``INSTALL_TYPE_TEXT`` mapping for display purposes
+
+- **String Enum Validator**: New ``str_enum_validator()`` converter for string-based enums
+
+Changed
+-------
+- **DeviceInfo Model**: 
+  - ``connected`` field now uses ``ConnectionStatus`` enum instead of plain int
+  - ``install_type`` field now uses ``InstallType`` enum instead of plain string
+
+- **TOU Status Conversion**: Simplified TOU status to use standard ``device_bool_to_python`` converter (consistent with other OnOffFlag fields)
+  - Removed special-case ``tou_status_to_python()`` converter
+  - ``TouStatus`` annotated type now uses ``device_bool_to_python`` validator
+  - Device encoding: 1=OFF/disabled, 2=ON/enabled (consistent with all other boolean fields)
+
+- **CLI Documentation**: Clarified distinction between ``info`` (DeviceFeature via MQTT) and ``device-info`` (DeviceInfo via REST API) commands
+
+- **Type Annotations**: Fixed CLI rich_output console type annotation to declare at class level
+
+Removed
+-------
+- **constants.py Module**: Removed empty ``constants.py`` module. ``CommandCode`` enum was already moved to ``enums.py`` in version 4.2.0.
+  
+  .. code-block:: python
+  
+     # OLD (removed)
+     from nwp500.constants import CommandCode
+     
+     # NEW (use this)
+     from nwp500.enums import CommandCode
+
+- **Firmware Tracking**: Removed unused firmware tracking constants and documentation (``KNOWN_FIRMWARE_FIELD_CHANGES``, ``LATEST_KNOWN_FIRMWARE``, ``docs/protocol/firmware_tracking.rst``)
+
+- **TOU Status Converter**: Removed redundant ``tou_status_to_python()`` converter function and associated tests
+
+
+Version 7.2.0 (2025-12-23)
+==========================
+
+**BREAKING CHANGES**: Class names renamed for consistency with MQTT-specific functionality
+
+Removed
+-------
+
+- **Renamed Classes**: Updated class names to clarify MQTT-specific implementations
+
+  .. code-block:: python
+
+     # OLD (removed)
+     from nwp500 import DeviceCapabilityChecker, DeviceInfoCache
+     
+     # NEW
+     from nwp500 import MqttDeviceCapabilityChecker, MqttDeviceInfoCache
+
+  **Rationale**: The original names were too generic. These classes are specifically designed 
+  for MQTT client functionality (auto-fetching device info, caching, capability checking). 
+  The new names make it clear they're MQTT-specific implementations, leaving room for future 
+  REST API versions if needed.
+
+  **Migration**: Simple find-and-replace:
+  
+  - ``DeviceCapabilityChecker`` → ``MqttDeviceCapabilityChecker``
+  - ``DeviceInfoCache`` → ``MqttDeviceInfoCache``
+  
+  All functionality remains identical - only the class names changed.
+
+Added
+-----
+
+- **Factory Function**: New ``create_navien_clients()`` factory for streamlined client initialization
+
+  .. code-block:: python
+
+     # Create both API and MQTT clients in one call
+     from nwp500 import create_navien_clients
+     
+     async with create_navien_clients(email, password) as (api_client, mqtt_client):
+         devices = await api_client.get_devices()
+         await mqtt_client.connect()
+         # Both clients ready to use
+
+  - Automatic auth client management (created internally, shared by both clients)
+  - Simplified initialization for common use case (API + MQTT)
+  - Proper async context manager support
+  - Reduces boilerplate in application code
+  - Comprehensive documentation in ``docs/guides/authentication.rst``
+  - Example: ``examples/intermediate/advanced_auth_patterns.py``
+
+- **VolumeCode Enum**: Tank capacity identification with gallon values
+
+  .. code-block:: python
+
+     from nwp500 import VolumeCode
+     
+     # Enum values: VOLUME_50GAL = 65, VOLUME_65GAL = 66, VOLUME_80GAL = 67
+     # Human-readable text available in VOLUME_CODE_TEXT dict
+     
+  - Maps device codes to actual tank capacities (50, 65, 80 gallons)
+  - Used in ``DeviceFeature.volume_code`` field with automatic validation
+  - Exported from main package for convenience
+  - Includes ``VOLUME_CODE_TEXT`` mapping for display purposes
+
+- **Temperature Conversion Classes**: Type-safe temperature handling with clear precision
+
+  - ``HalfCelsius`` class: 0.5°C precision (value / 2.0)
+  - ``DeciCelsius`` class: 0.1°C precision (value / 10.0)
+  - Base ``Temperature`` ABC with ``to_celsius()`` and ``to_fahrenheit()`` methods
+  - ``from_fahrenheit()`` class methods for reverse conversions
+  - Validator functions for Pydantic integration
+  - Centralized in new ``temperature.py`` module
+  - Better type safety and clearer intent than raw number conversions
+
+- **Protocol Converters Module**: Centralized device protocol conversion logic
+
+  - ``device_bool_to_python()``: Convert device boolean (1=False, 2=True)
+  - ``device_bool_from_python()``: Reverse conversion
+  - ``tou_status_to_python()``: Time of Use status conversion
+  - ``tou_override_to_python()``: TOU override status conversion
+  - ``div_10()``: Divide by 10.0 utility
+  - ``enum_validator()``: Generic enum factory
+  - Comprehensive documentation explaining device protocol quirks
+  - New ``converters.py`` module replacing scattered validators
+
+- **MQTT Event System**: Structured event handling for MQTT operations
+
+  - ``MqttClientEvents`` class with type-safe event definitions
+  - Feature monitoring and capability detection events
+  - Enhanced device capability monitoring in MQTT control module
+  - New ``mqtt_events.py`` module for event infrastructure
+  - Improved separation of concerns for event-driven architectures
+
+- **Pyright Type Checking**: Static type analysis integrated into CI/CD
+
+  - Added pyright>=1.1.0 to dev dependencies
+  - Configured in ``pyproject.toml`` with strict mode for ``src/nwp500``
+  - Integrated into tox lint environment and CI workflows
+  - Runs automatically with ``make ci-lint`` or ``python3 scripts/lint.py``
+  - All source code now passes strict type checking (0 errors)
+  - Improved type annotations across codebase
+
+- **Dynamic Unit Extraction in CLI**: CLI output now dynamically extracts units from DeviceStatus model metadata
+
+  - New helper functions: ``_get_unit_suffix()`` and ``_add_numeric_item()``
+  - Eliminates hardcoded units in output formatter
+  - Single source of truth: model metadata drives CLI display
+
+- **Comprehensive Protocol Documentation**: Complete protocol reference documentation
+
+  - New ``docs/protocol/quick_reference.rst`` with command codes, field formats, and conversions
+  - Converted protocol documentation to RST format for Sphinx integration
+  - Added protocol reference links in source code comments
+  - Improved cross-referencing between code and documentation
+
+Changed
+-------
+
+- **MQTT Module Reorganization**: Consolidated 9 separate modules into cohesive ``mqtt`` package
+
+  .. code-block:: python
+
+     # OLD imports (still work via compatibility layer)
+     from nwp500.mqtt_client import NavienMqttClient
+     from nwp500.mqtt_diagnostics import MqttDiagnosticsCollector
+     from nwp500.mqtt_utils import MqttConnectionConfig
+     
+     # NEW imports (preferred)
+     from nwp500.mqtt import NavienMqttClient, MqttDiagnosticsCollector, MqttConnectionConfig
+     # OR import from main package (recommended)
+     from nwp500 import NavienMqttClient, MqttDiagnosticsCollector, MqttConnectionConfig
+
+  - Created ``src/nwp500/mqtt/`` package with organized submodules
+  - Better package organization and structure
+  - Clearer public vs internal APIs
+  - New ``mqtt/__init__.py`` with clean public API exports
+  - Backward compatibility maintained via main package exports
+  - All 209 tests pass with zero type checking errors
+
+- **CLI Framework Migration**: Migrated from argparse to Click framework
+
+  - Implemented ``async_command`` decorator for automatic loop and connection management
+  - Added support for command groups (reservations, tou)
+  - Improved argument and option parsing with built-in validation
+  - Enhanced help text and version reporting
+  - Centralized command registry in ``src/nwp500/cli/commands.py``
+  - Reorganized CLI handlers into ``src/nwp500/cli/handlers.py``
+  - Better separation of concerns between CLI framework and business logic
+  - Industry-standard CLI framework with better maintainability
+  - Added click>=8.0.0 dependency
+
+- **Examples Reorganization**: Restructured examples into beginner/intermediate/advanced/testing categories
+
+  - Created structured hierarchy in ``examples/`` directory
+  - Renamed and moved 35+ example scripts for better discoverability
+  - Updated ``examples/README.md`` with 'Getting Started' guide and categorized index
+  - Added 01-04 beginner series for smooth onboarding:
+    
+    - ``beginner/01_authentication.py`` - Basic authentication patterns
+    - ``beginner/02_list_devices.py`` - Retrieving device information
+    - ``beginner/03_get_status.py`` - Getting device status
+    - ``beginner/04_set_temperature.py`` - Basic device control
+    
+  - Intermediate examples: event-driven control, error handling, MQTT monitoring
+  - Advanced examples: demand response, recirculation, TOU schedules, diagnostics
+  - Testing examples: connection testing, periodic updates, minimal examples
+  - All examples updated with correct imports for new package structure
+
+- **Authentication Documentation**: Major improvements to authentication guide
+
+  - Complete rewrite of ``docs/guides/authentication.rst``
+  - Added factory function patterns and examples
+  - Improved context manager documentation
+  - Added best practices and common patterns
+  - More comprehensive code examples
+
+- **Model Refactoring**: Updated to use new converter modules
+
+  - Replaced 53 lines of scattered validators with imports
+  - Updated ``fahrenheit_to_half_celsius()`` to use ``HalfCelsius`` class
+  - Cleaner model definitions with centralized conversion logic
+  - No breaking changes to public API
+
+- **CLI Output Formatter Refactoring**: Restructured ``print_device_status()`` to use dynamic unit extraction
+
+  - Reduced code duplication by ~400 lines
+  - Improved maintainability: field additions automatically get correct units
+  - No breaking changes to CLI output format or behavior
+
+- **Type Annotations**: Improved type safety across entire codebase
+
+  - Fixed datetime imports to use ``datetime.UTC`` (Python 3.13)
+  - Fixed type annotations in ``rich_output.py`` for optional dependencies
+  - Fixed type narrowing issues in ``encoding.py``
+  - Updated ``MqttConnection`` callback signature to use ``AwsCrtError``
+  - Added public properties and setters where needed for type checking
+
+Fixed
+-----
+
+- **Superheat Temperature Units**: Target and Current SuperHeat now correctly display in °F instead of °C
+
+  - Both fields use ``DeciCelsiusToF`` conversion, now properly reflected in CLI output
+  - Fields were displaying inconsistent units compared to all other temperature readings
+
+- **Missing CLI Output Units**: Multiple fields now display with proper units from model metadata
+
+  - ``current_dhw_flow_rate``: Now shows GPM unit
+  - ``total_energy_capacity``: Now shows Wh unit
+  - ``available_energy_capacity``: Now shows Wh unit
+  - ``dr_override_status``: Now shows hours unit
+  - ``vacation_day_setting``: Now shows days unit
+  - ``vacation_day_elapsed``: Now shows days unit
+  - ``anti_legionella_period``: Fixed to show days unit (was incorrectly h)
+  - ``wifi_rssi``: Now shows dBm unit
+
+- **Invalid MQTT Topic Filter**: Fixed ``reservations get`` command subscription topic
+
+  - Changed invalid topic pattern ``cmd/52/navilink-+/#`` to valid ``cmd/52/+/#``
+  - AWS IoT Core MQTT does not support wildcards within topic segments
+  - Affected: ``handle_get_reservations_request()`` in commands.py
+
+- **DeviceFeature Documentation**: Clarified field descriptions and fixed documentation errors
+
+  - Fixed ``country_code`` documentation (actual value is 3, not 1 as previously noted)
+  - Clarified ``model_type_code``, ``control_type_code``, ``recirc_model_type_code`` field purposes
+  - Updated ``volume_code`` to use new ``VolumeCode`` enum with validation
+
+- **Type Checking Errors**: Resolved all pyright type checking errors in source code
+
+  - Fixed datetime imports and type annotations
+  - Added missing public properties and setters
+  - Removed unused imports and variables
+  - All source code now passes strict type checking
+
 Version 7.1.0 (2025-12-22)
 ==========================
 

{nwp500_python-7.1.0 → nwp500_python-7.2.1}/CONTRIBUTING.rst

@@ -85,6 +85,69 @@ The project is organized around a modular architecture:
 
 Design principles include separation of concerns, clear public APIs, and extensibility for new device features. Contributors should review the `src/nwp500/` directory for module structure and refer to the documentation for details on each component.
 
+Naming Conventions
+------------------
+
+Consistent naming conventions improve code readability and maintainability. Follow these patterns when adding new classes, methods, and exceptions.
+
+**Classes**
+
+- **Client classes**: Use ``Navien<Component>Client`` format for main client classes (e.g., ``NavienAuthClient``, ``NavienAPIClient``, ``NavienMqttClient``). This prefix clearly indicates these are the primary library clients.
+- **Manager/Controller classes**: Use ``<Domain><Responsibility>`` format for classes managing specific functionality (e.g., ``MqttConnectionManager``, ``DeviceInfoCache``). Avoid Navien prefix for utility/internal classes.
+- **Utility classes**: Use ``<Domain><Feature>`` or ``<Domain>Utilities`` format for helper classes (e.g., ``MqttDiagnostics``, ``DeviceCapabilityChecker``).
+
+**Methods**
+
+Follow these patterns for consistent method naming:
+
+- **Getters**: Use ``get_<resource>()`` for single item retrieval (e.g., ``get_device_info()``, ``get_firmware_info()``)
+- **Listers**: Use ``list_<resources>()`` for collection retrieval (e.g., ``list_devices()``)
+- **Setters**: Use ``set_<field>(value)`` for direct assignment or ``configure_<feature>()`` for complex configuration (e.g., ``set_power()``, ``set_dhw_temperature()``)
+- **Actions**: Use ``<action>_<resource>()`` format for operations that modify state (e.g., ``reset_filter()``, ``enable_anti_legionella()``)
+- **Requesters**: Use ``request_<data>()`` for async data fetching from devices (e.g., ``request_device_status()``, ``request_device_info()``)
+
+**Enums**
+
+- **Enum names**: Use descriptive names that indicate the device state or protocol value (e.g., ``OnOffFlag``, ``CurrentOperationMode``, ``HeatSource``). These names should reflect the Navien protocol directly.
+- **Enum values**: Document device protocol mappings in code comments. For example:
+
+  .. code-block:: python
+
+      class OnOffFlag(IntEnum):
+          """Device on/off state per Navien protocol."""
+          OFF = 0  # 0 = False per Navien protocol
+          ON = 1   # 1 = True per Navien protocol
+
+**Exceptions**
+
+Follow a clear exception hierarchy with consistent naming:
+
+- **Pattern**: ``<Domain><Situation>Error`` (e.g., ``MqttConnectionError``, ``AuthenticationError``, ``DeviceCapabilityError``)
+- **Grouping**: Group related errors under a base class that consumers can catch for broad error handling:
+
+  - ``AuthenticationError`` - Base for all authentication failures (covers ``InvalidCredentialsError``, ``TokenExpiredError``, ``TokenRefreshError``)
+  - ``MqttError`` - Base for all MQTT operations (covers ``MqttConnectionError``, ``MqttNotConnectedError``, ``MqttPublishError``, etc.)
+  - ``ValidationError`` - Base for all validation failures (covers ``ParameterValidationError``, ``RangeValidationError``)
+  - ``DeviceError`` - Base for all device operations (covers ``DeviceNotFoundError``, ``DeviceOfflineError``, ``DeviceCapabilityError``, etc.)
+
+- **Example usage**:
+
+  .. code-block:: python
+
+      try:
+          await mqtt_client.control.set_temperature(device, 150)
+      except MqttNotConnectedError:
+          # Handle specific case: not connected
+          print("Connect to device first")
+      except MqttError:
+          # Handle other MQTT errors
+          print("MQTT operation failed")
+      except RangeValidationError as e:
+          print(f"Invalid {e.field}: must be {e.min_value}-{e.max_value}")
+      except ValidationError:
+          # Handle other validation errors
+          print("Invalid parameter")
+
 Submit an issue
 ---------------
 

{nwp500_python-7.1.0 → nwp500_python-7.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 7.1.0
+Version: 7.2.1
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi
@@ -21,6 +21,9 @@ License-File: LICENSE.txt
 Requires-Dist: aiohttp>=3.8.0
 Requires-Dist: awsiotsdk>=1.27.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: click>=8.0.0
+Provides-Extra: cli
+Requires-Dist: rich>=13.0.0; extra == "cli"
 Provides-Extra: testing
 Requires-Dist: setuptools; extra == "testing"
 Requires-Dist: pytest; extra == "testing"
@@ -28,6 +31,7 @@ Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-asyncio; extra == "testing"
 Provides-Extra: dev
 Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pyright>=1.1.0; extra == "dev"
 Requires-Dist: setuptools; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -98,6 +102,34 @@ Basic Usage
             # Change operation mode
             await api_client.set_device_mode(device, "heat_pump")
 
+For more detailed authentication information, see the `Authentication & Session Management <https://nwp500-python.readthedocs.io/en/latest/guides/authentication.html>`_ guide.
+
+MQTT Real-Time Monitoring
+--------------------------
+
+Monitor your device in real-time using MQTT:
+
+.. code-block:: python
+
+    from nwp500 import NavienAuthClient, NavienMqttClient
+
+    async with NavienAuthClient("your_email@example.com", "your_password") as auth_client:
+        # Create MQTT client
+        mqtt_client = NavienMqttClient(auth_client=auth_client)
+        await mqtt_client.connect()
+        
+        # Subscribe to device status updates
+        def on_status(status):
+            print(f"Temperature: {status.dhw_temperature}°F")
+            print(f"Mode: {status.operation_mode}")
+        
+        device = (await api_client.list_devices())[0]
+        await mqtt_client.subscribe_device_status(device, on_status)
+        
+        # Keep the connection alive
+        await mqtt_client.wait()
+
+
 Command Line Interface
 ======================
 
@@ -112,9 +144,12 @@ The library includes a command line interface for monitoring and controlling you
     # Get current device status
     python3 -m nwp500.cli status
 
-    # Get device information and firmware
+    # Get device information and firmware (via MQTT - DeviceFeature)
     python3 -m nwp500.cli info
 
+    # Get basic device info from REST API (DeviceInfo)
+    python3 -m nwp500.cli device-info
+
     # Get controller serial number
     python3 -m nwp500.cli serial
 

{nwp500_python-7.1.0 → nwp500_python-7.2.1}/README.rst

@@ -62,6 +62,34 @@ Basic Usage
             # Change operation mode
             await api_client.set_device_mode(device, "heat_pump")
 
+For more detailed authentication information, see the `Authentication & Session Management <https://nwp500-python.readthedocs.io/en/latest/guides/authentication.html>`_ guide.
+
+MQTT Real-Time Monitoring
+--------------------------
+
+Monitor your device in real-time using MQTT:
+
+.. code-block:: python
+
+    from nwp500 import NavienAuthClient, NavienMqttClient
+
+    async with NavienAuthClient("your_email@example.com", "your_password") as auth_client:
+        # Create MQTT client
+        mqtt_client = NavienMqttClient(auth_client=auth_client)
+        await mqtt_client.connect()
+        
+        # Subscribe to device status updates
+        def on_status(status):
+            print(f"Temperature: {status.dhw_temperature}°F")
+            print(f"Mode: {status.operation_mode}")
+        
+        device = (await api_client.list_devices())[0]
+        await mqtt_client.subscribe_device_status(device, on_status)
+        
+        # Keep the connection alive
+        await mqtt_client.wait()
+
+
 Command Line Interface
 ======================
 
@@ -76,9 +104,12 @@ The library includes a command line interface for monitoring and controlling you
     # Get current device status
     python3 -m nwp500.cli status
 
-    # Get device information and firmware
+    # Get device information and firmware (via MQTT - DeviceFeature)
     python3 -m nwp500.cli info
 
+    # Get basic device info from REST API (DeviceInfo)
+    python3 -m nwp500.cli device-info
+
     # Get controller serial number
     python3 -m nwp500.cli serial