nwp500-python 7.2.2__tar.gz → 7.2.3__tar.gz

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/.readthedocs.yml

@@ -19,7 +19,7 @@ formats:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.13"
 
 python:
   install:

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/CHANGELOG.rst

@@ -2,6 +2,57 @@
 Changelog
 =========
 
+Version 7.2.3 (2026-01-15)
+==========================
+
+Added
+-----
+- **Daily Energy Breakdown by Month**: New ``--month`` option for energy command to show daily energy data for a specific month
+  
+  .. code-block:: bash
+  
+     # Daily breakdown for a single month
+     nwp-cli energy --year 2025 --month 12
+     
+     # Monthly summary for multiple months (existing)
+     nwp-cli energy --year 2025 --months 10,11,12
+  
+  - Displays daily energy consumption, efficiency, and heat source breakdown
+  - Rich formatted output with progress bars and color-coded efficiency percentages
+  - Plain text fallback for non-Rich environments
+  - Smart routing: single month shows daily data, multiple months show summary
+
+Fixed
+-----
+- **Documentation**: Fixed all warnings and broken cross-references in documentation
+  
+  - Fixed docstring formatting in field_factory.py module
+  - Fixed broken cross-reference links in enumerations.rst, mqtt_diagnostics.rst, cli.rst, and models.rst
+  - Fixed invalid JSON syntax in code examples (removed invalid [...] and ... tokens)
+  - Suppressed duplicate object description warnings from re-exported classes
+  
+- **CLI Documentation**: Updated documentation for all 19 CLI commands
+  
+  - Added missing device-info command documentation
+  - Added --raw flag documentation for status, info, and device-info commands
+  - Added --month option documentation to energy command
+  - Clarified mutually exclusive options (--months vs --month)
+  
+- **RST Title Hierarchy**: Fixed title level inconsistencies in device_control.rst
+
+- **Read the Docs Configuration**: Updated Python version requirement to 3.13 in Read the Docs config
+
+- **CI Test Failures**: Fixed ``ModuleNotFoundError`` when running tests without CLI dependencies installed
+  
+  - Wrapped CLI module imports in try-except blocks in test modules
+  - Tests are skipped gracefully when optional dependencies (click, rich) are not installed
+  - Allows pytest to run without CLI extra, while supporting full test suite with tox
+  - Network errors in authentication are now marked as retriable for better resilience
+
+Changed
+-------
+- **Installation Documentation**: Updated installation instructions to clarify optional CLI and Rich dependencies
+
 Version 7.2.2 (2025-12-25)
 ==========================
 

{nwp500_python-7.2.2/src/nwp500_python.egg-info → nwp500_python-7.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 7.2.2
+Version: 7.2.3
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi
@@ -21,8 +21,8 @@ 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: click>=8.0.0; extra == "cli"
 Requires-Dist: rich>=13.0.0; extra == "cli"
 Provides-Extra: testing
 Requires-Dist: setuptools; extra == "testing"
@@ -69,10 +69,28 @@ Quick Start
 Installation
 ------------
 
+Basic Installation (Library Only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For using the library as a Python package without the CLI:
+
 .. code-block:: bash
 
     pip install nwp500-python
 
+This installs the core library with support for API and MQTT clients. No CLI framework is required.
+
+Installation with CLI Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the command-line interface with rich formatting and colors:
+
+.. code-block:: bash
+
+    pip install nwp500-python[cli]
+
+This includes both the ``click`` CLI framework and the ``rich`` formatting library for enhanced terminal output with formatted tables, progress bars, and colored output.
+
 Basic Usage
 -----------
 
@@ -133,7 +151,16 @@ Monitor your device in real-time using MQTT:
 Command Line Interface
 ======================
 
-The library includes a command line interface for monitoring and controlling your Navien water heater:
+The library includes a command line interface for monitoring and controlling your Navien water heater.
+
+**Installation Requirement:** The CLI requires the ``cli`` extra:
+
+.. code-block:: bash
+
+    pip install nwp500-python[cli]
+
+Quick Reference
+---------------
 
 .. code-block:: bash
 

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/README.rst

@@ -29,10 +29,28 @@ Quick Start
 Installation
 ------------
 
+Basic Installation (Library Only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For using the library as a Python package without the CLI:
+
 .. code-block:: bash
 
     pip install nwp500-python
 
+This installs the core library with support for API and MQTT clients. No CLI framework is required.
+
+Installation with CLI Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the command-line interface with rich formatting and colors:
+
+.. code-block:: bash
+
+    pip install nwp500-python[cli]
+
+This includes both the ``click`` CLI framework and the ``rich`` formatting library for enhanced terminal output with formatted tables, progress bars, and colored output.
+
 Basic Usage
 -----------
 
@@ -93,7 +111,16 @@ Monitor your device in real-time using MQTT:
 Command Line Interface
 ======================
 
-The library includes a command line interface for monitoring and controlling your Navien water heater:
+The library includes a command line interface for monitoring and controlling your Navien water heater.
+
+**Installation Requirement:** The CLI requires the ``cli`` extra:
+
+.. code-block:: bash
+
+    pip install nwp500-python[cli]
+
+Quick Reference
+---------------
 
 .. code-block:: bash
 

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/api/nwp500.rst

@@ -8,6 +8,7 @@ Subpackages
    :maxdepth: 4
 
    nwp500.cli
+   nwp500.mqtt
 
 Submodules
 ----------
@@ -28,6 +29,14 @@ nwp500.auth module
    :show-inheritance:
    :undoc-members:
 
+nwp500.command\_decorators module
+---------------------------------
+
+.. automodule:: nwp500.command_decorators
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 nwp500.config module
 --------------------
 
@@ -36,106 +45,106 @@ nwp500.config module
    :show-inheritance:
    :undoc-members:
 
-nwp500.constants module
------------------------
+nwp500.converters module
+------------------------
 
-.. automodule:: nwp500.constants
+.. automodule:: nwp500.converters
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.encoding module
-----------------------
+nwp500.device\_capabilities module
+----------------------------------
 
-.. automodule:: nwp500.encoding
+.. automodule:: nwp500.device_capabilities
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.events module
---------------------
+nwp500.device\_info\_cache module
+---------------------------------
 
-.. automodule:: nwp500.events
+.. automodule:: nwp500.device_info_cache
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.exceptions module
-------------------------
+nwp500.encoding module
+----------------------
 
-.. automodule:: nwp500.exceptions
+.. automodule:: nwp500.encoding
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.models module
---------------------
+nwp500.enums module
+-------------------
 
-.. automodule:: nwp500.models
+.. automodule:: nwp500.enums
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_client module
---------------------------
+nwp500.events module
+--------------------
 
-.. automodule:: nwp500.mqtt_client
+.. automodule:: nwp500.events
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_command\_queue module
-----------------------------------
+nwp500.exceptions module
+------------------------
 
-.. automodule:: nwp500.mqtt_command_queue
+.. automodule:: nwp500.exceptions
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_connection module
-------------------------------
+nwp500.factory module
+---------------------
 
-.. automodule:: nwp500.mqtt_connection
+.. automodule:: nwp500.factory
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_device\_control module
------------------------------------
+nwp500.field\_factory module
+----------------------------
 
-.. automodule:: nwp500.mqtt_device_control
+.. automodule:: nwp500.field_factory
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_periodic module
-----------------------------
+nwp500.models module
+--------------------
 
-.. automodule:: nwp500.mqtt_periodic
+.. automodule:: nwp500.models
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_reconnection module
---------------------------------
+nwp500.mqtt\_events module
+--------------------------
 
-.. automodule:: nwp500.mqtt_reconnection
+.. automodule:: nwp500.mqtt_events
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_subscriptions module
----------------------------------
+nwp500.temperature module
+-------------------------
 
-.. automodule:: nwp500.mqtt_subscriptions
+.. automodule:: nwp500.temperature
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_utils module
--------------------------
+nwp500.topic\_builder module
+----------------------------
 
-.. automodule:: nwp500.mqtt_utils
+.. automodule:: nwp500.topic_builder
    :members:
    :show-inheritance:
    :undoc-members:

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/conf.py

@@ -78,6 +78,7 @@ extensions = [
 # Suppress warnings for classes/functions exported in multiple modules
 suppress_warnings = [
     "ref.python",  # Suppress "more than one target found" warnings
+    "py.duplicate",  # Suppress all "duplicate" warnings including duplicate_description
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -289,4 +290,17 @@ intersphinx_mapping = {
     "pyscaffold": ("https://pyscaffold.org/en/stable", None),
 }
 
+# Suppress duplicate object description warnings from re-exported classes
+import logging
+
+class DuplicateWarningFilter(logging.Filter):
+    def filter(self, record):
+        # Suppress "duplicate object description" warnings
+        return "duplicate object description" not in record.getMessage()
+
+# Install the filter when Sphinx initializes
+def setup(app):
+    logger = logging.getLogger("sphinx")
+    logger.addFilter(DuplicateWarningFilter())
+
 print(f"loading configurations for {project} {version} ...", file=sys.stderr)

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/enumerations.rst

@@ -10,6 +10,7 @@ Device Control Commands
 .. autoclass:: nwp500.enums.CommandCode
    :members:
    :undoc-members:
+   :no-index:
 
 These command IDs are used in MQTT control messages to change device settings
 and trigger actions. The most commonly used commands include:
@@ -37,6 +38,7 @@ OnOffFlag
 .. autoclass:: nwp500.enums.OnOffFlag
    :members:
    :undoc-members:
+   :no-index:
 
 Generic on/off flag used throughout status fields for power status, TOU status,
 recirculation status, vacation mode, anti-legionella, and other boolean settings.
@@ -49,6 +51,7 @@ Operation
 .. autoclass:: nwp500.enums.Operation
    :members:
    :undoc-members:
+   :no-index:
 
 Device operation state indicating overall device activity.
 
@@ -58,6 +61,7 @@ DhwOperationSetting
 .. autoclass:: nwp500.enums.DhwOperationSetting
    :members:
    :undoc-members:
+   :no-index:
 
 User-configured DHW heating mode preference. This determines which heat source(s)
 the device will use when heating is needed:
@@ -83,6 +87,7 @@ CurrentOperationMode
 .. autoclass:: nwp500.enums.CurrentOperationMode
    :members:
    :undoc-members:
+   :no-index:
 
 Real-time operational state (read-only). This reflects what the device is actually
 doing right now, which may differ from the configured mode setting:
@@ -106,6 +111,7 @@ HeatSource
 .. autoclass:: nwp500.enums.HeatSource
    :members:
    :undoc-members:
+   :no-index:
 
 Currently active heat source (read-only status). This reflects what the device
 is *currently* using, not what mode it's set to. In Hybrid mode, this field
@@ -117,6 +123,7 @@ DREvent
 .. autoclass:: nwp500.enums.DREvent
    :members:
    :undoc-members:
+   :no-index:
 
 Demand Response event status. Allows utilities to manage grid load by signaling
 water heaters to reduce consumption (shed) or pre-heat (load up) before peak periods.
@@ -127,6 +134,7 @@ WaterLevel
 .. autoclass:: nwp500.enums.WaterLevel
    :members:
    :undoc-members:
+   :no-index:
 
 Hot water level indicator displayed as gauge in app. IDs are non-sequential,
 likely represent bit positions for multi-level displays.
@@ -137,6 +145,7 @@ FilterChange
 .. autoclass:: nwp500.enums.FilterChange
    :members:
    :undoc-members:
+   :no-index:
 
 Air filter status for heat pump models. Indicates when air filter maintenance
 is needed.
@@ -147,6 +156,7 @@ RecirculationMode
 .. autoclass:: nwp500.enums.RecirculationMode
    :members:
    :undoc-members:
+   :no-index:
 
 Recirculation pump operation mode:
 
@@ -164,6 +174,7 @@ TouWeekType
 .. autoclass:: nwp500.enums.TouWeekType
    :members:
    :undoc-members:
+   :no-index:
 
 Day grouping for TOU schedules. Allows separate schedules for weekdays and
 weekends to account for different electricity rates and usage patterns.
@@ -174,6 +185,7 @@ TouRateType
 .. autoclass:: nwp500.enums.TouRateType
    :members:
    :undoc-members:
+   :no-index:
 
 Electricity rate period type. Device behavior can be configured for each period:
 
@@ -190,6 +202,7 @@ TemperatureType
 .. autoclass:: nwp500.enums.TemperatureType
    :members:
    :undoc-members:
+   :no-index:
 
 Temperature display unit preference (Celsius or Fahrenheit).
 
@@ -201,6 +214,7 @@ TempFormulaType
 .. autoclass:: nwp500.enums.TempFormulaType
    :members:
    :undoc-members:
+   :no-index:
 
 Temperature conversion formula type. Different device models use slightly different
 rounding algorithms when converting internal Celsius values to Fahrenheit:
@@ -219,6 +233,7 @@ UnitType
 .. autoclass:: nwp500.enums.UnitType
    :members:
    :undoc-members:
+   :no-index:
 
 Navien device/unit model types. Common values:
 
@@ -236,6 +251,7 @@ DeviceType
 .. autoclass:: nwp500.enums.DeviceType
    :members:
    :undoc-members:
+   :no-index:
 
 Communication device type (WiFi module model).
 
@@ -245,6 +261,7 @@ FirmwareType
 .. autoclass:: nwp500.enums.FirmwareType
    :members:
    :undoc-members:
+   :no-index:
 
 Firmware component types. Devices may have multiple firmware components that
 can be updated independently.
@@ -290,4 +307,4 @@ For detailed protocol documentation, see:
 
 - :doc:`protocol/device_status` - Status field definitions
 - :doc:`guides/time_of_use` - TOU scheduling and rate types
-- :doc:`protocol/control_commands` - Control command usage
+- :doc:`protocol/quick_reference` - Quick reference and control commands

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/guides/mqtt_diagnostics.rst

@@ -1116,8 +1116,8 @@ Investigation Checklist
 See Also
 ========
 
-- :doc:`/docs/DEVICE_STATUS_FIELDS` - Device status field reference
-- :doc:`/docs/MQTT_CLIENT` - MQTT client API documentation
+- :doc:`../protocol/device_status` - Device status field reference
+- :doc:`../python_api/mqtt_client` - MQTT client API documentation
 
 External Resources
 

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/protocol/mqtt_protocol.rst

@@ -770,8 +770,7 @@ Status Response
          "operationBusy": 2,
          "compUse": 2,
          "heatUpperUse": 1,
-         "errorCode": 0,
-         ...
+         "errorCode": 0
        }
      }
    }
@@ -796,8 +795,7 @@ Feature/Info Response
          "controller_sw_version": 184614912,
          "dhw_temperature_min": 75,
          "dhw_temperature_max": 130,
-         "energy_usage_use": 1,
-         ...
+         "energy_usage_use": 1
        }
      }
    }

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/python_api/cli.rst

@@ -94,6 +94,13 @@ Get current device status (one-time query).
 .. code-block:: bash
 
    python3 -m nwp500.cli status
+   python3 -m nwp500.cli status --raw
+
+**Options:**
+
+.. option:: --raw
+
+   Output raw JSON response (unformatted).
 
 **Output:** Device status including water temperature, target temperature, mode,
 power consumption, tank charge percentage, and component states.
@@ -122,10 +129,38 @@ Show comprehensive device information (firmware, model, capabilities, serial).
 .. code-block:: bash
 
    python3 -m nwp500.cli info
+   python3 -m nwp500.cli info --raw
+
+**Options:**
+
+.. option:: --raw
+
+   Output raw JSON response (unformatted).
 
 **Output:** Device name, MAC address, firmware versions, features supported,
 temperature ranges, and capabilities.
 
+device-info
+^^^^^^^^^^^
+
+Show basic device information from REST API (DeviceInfo model).
+
+.. code-block:: bash
+
+   python3 -m nwp500.cli device-info
+   python3 -m nwp500.cli device-info --raw
+
+**Options:**
+
+.. option:: --raw
+
+   Output raw JSON response (unformatted).
+
+**Output:** Basic device information from REST API.
+
+**Note:** Use ``info`` command for MQTT-based comprehensive information, or
+``device-info`` for REST API-based basic information.
+
 serial
 ^^^^^^
 
@@ -386,24 +421,27 @@ Energy & Utility Commands
 energy
 ^^^^^^
 
-Query historical energy usage data by month.
+Query historical energy usage data by month or daily breakdown.
 
 .. code-block:: bash
 
-   # Get October 2024
+   # Get monthly summary for October 2024
    python3 -m nwp500.cli energy --year 2024 --months 10
 
    # Get multiple months
    python3 -m nwp500.cli energy --year 2024 --months 8,9,10
 
-   # Get full year
+   # Get daily breakdown for October 2024
+   python3 -m nwp500.cli energy --year 2024 --month 10
+
+   # Get full year summary
    python3 -m nwp500.cli energy --year 2024 --months 1,2,3,4,5,6,7,8,9,10,11,12
 
 **Syntax:**
 
 .. code-block:: bash
 
-   python3 -m nwp500.cli energy --year <year> --months <month-list>
+   python3 -m nwp500.cli energy --year <year> [--months <month-list> | --month <month>]
 
 **Options:**
 
@@ -413,7 +451,13 @@ Query historical energy usage data by month.
 
 .. option:: --months MONTHS
 
-   Comma-separated list of months (1-12). **Required.**
+   Comma-separated list of months (1-12) for monthly summary. Use either
+   ``--months`` OR ``--month``, not both.
+
+.. option:: --month MONTH
+
+   Show daily breakdown for a specific month (1-12). Use either ``--month``
+   OR ``--months``, not both.
 
 **Output:** Energy usage breakdown by heat pump vs. electric heating.
 
@@ -427,7 +471,7 @@ Query historical energy usage data by month.
      "heat_pump_hours": 245,
      "electric_wh": 302469,
      "electric_hours": 67,
-     "by_day": [...]
+     "by_day": []
    }
 
 tou
@@ -717,4 +761,4 @@ Related Documentation
 * :doc:`auth_client` - Python authentication API
 * :doc:`api_client` - Python REST API
 * :doc:`mqtt_client` - Python MQTT API
-* :doc:`../guides/mqtt_basics` - MQTT protocol guide
+* :doc:`../guides/auto_recovery` - Connection recovery and resilience

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/python_api/device_control.rst

@@ -744,7 +744,7 @@ device capabilities without requiring individual checker functions.
    ^^^^^^^^^^^^^
 
 supports()
-""""""""""
+----------
 
 .. py:staticmethod:: supports(feature, device_features)
 
@@ -780,7 +780,7 @@ supports()
           print("Device doesn't support recirculation pump")
 
 assert_supported()
-""""""""""""""""""
+------------------
 
 .. py:staticmethod:: assert_supported(feature, device_features)
 
@@ -807,7 +807,7 @@ assert_supported()
           print(f"Cannot set recirculation: {e}")
 
 get_available_controls()
-""""""""""""""""""""""""
+------------------------
 
 .. py:staticmethod:: get_available_controls(device_features)
 
@@ -830,7 +830,7 @@ get_available_controls()
           print(f"{status} {feature}")
 
 register_capability()
-"""""""""""""""""""""
+---------------------
 
 .. py:staticmethod:: register_capability(name, check_fn)
 

{nwp500_python-7.2.2 → nwp500_python-7.2.3}/docs/python_api/models.rst

@@ -608,4 +608,3 @@ Related Documentation
 * :doc:`auth_client` - Authentication
 * :doc:`api_client` - REST API
 * :doc:`mqtt_client` - MQTT client
-* :doc:`constants` - Command codes and constants