nwp500-python 2.0.0__tar.gz → 3.1.0__tar.gz

{nwp500_python-2.0.0 → nwp500_python-3.1.0}/.github/copilot-instructions.md

@@ -14,11 +14,25 @@
 - **Lint/format**: `ruff format --check src/ tests/ examples/` (use `ruff format ...` to auto-format)
 - **CI-compatible linting**: `make ci-lint` (run before finalizing changes to ensure CI will pass)
 - **CI-compatible formatting**: `make ci-format` (auto-fix formatting issues)
+- **Type checking**: `python3 -m mypy src/nwp500 --config-file pyproject.toml` (static type analysis)
 - **Build docs**: `tox -e docs` (Sphinx docs in `docs/`)
 - **Preview docs**: `python3 -m http.server --directory docs/_build/html`
 
 ### Before Committing Changes
-Always run `make ci-lint` before finalizing changes to ensure your code will pass CI checks. This runs the exact same linting configuration as the CI pipeline, preventing "passes locally but fails in CI" issues.
+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
+2. **Type checking**: `python3 -m mypy src/nwp500 --config-file pyproject.toml` - Catches type errors
+3. **Tests**: `pytest` - Ensures functionality isn't broken
+
+This prevents "passes locally but fails in CI" issues.
+
+### After Completing a Task
+Always run these checks after completing a task to validate your changes:
+1. **Type checking**: `python3 -m mypy src/nwp500 --config-file pyproject.toml` - Verify no type errors were introduced
+2. **Linting**: `make ci-lint` - Verify code style compliance
+3. **Tests** (if applicable): `pytest` - Verify functionality works as expected
+
+Report the results of these checks in your final summary.
 
 ## Patterns & Conventions
 - **Async context managers** for authentication: `async with NavienAuthClient(email, password) as auth_client:`
@@ -44,6 +58,22 @@ Always run `make ci-lint` before finalizing changes to ensure your code will pas
 - If tests hang, check network connectivity and API endpoint status
 - For MQTT, ensure AWS credentials are valid and endpoint is reachable
 
+## Communication Style
+- **Progress updates**: Save summaries for the end of work. Don't provide interim status reports.
+- **Final summaries**: Keep them concise. Example format:
+  ```
+  ## Final Results
+  **Starting point:** X errors
+  **Ending point:** 0 errors ✅
+  **Tests:** All passing ✓
+  
+  ## What Was Fixed
+  - Module 1 - Brief description (N errors)
+  - Module 2 - Brief description (N errors)
+  ```
+- **No markdown files**: Don't create separate summary files. Provide summaries inline when requested.
+- **Focus on execution**: Perform the work, then summarize results at the end.
+
 ---
 
 If any section is unclear or missing important project-specific details, please provide feedback so this guide can be improved for future AI agents.

{nwp500_python-2.0.0 → nwp500_python-3.1.0}/CHANGELOG.rst

@@ -2,12 +2,32 @@
 Changelog
 =========
 
+Version 3.0.0 (Unreleased)
+==========================
+
+**Breaking Changes**
+
+- **REMOVED**: ``OperationMode`` enum has been removed
+  
+  - This enum was deprecated in v2.0.0 and has now been fully removed
+  - Use ``DhwOperationSetting`` for user-configured mode preferences (values 1-6)
+  - Use ``CurrentOperationMode`` for real-time operational states (values 0, 32, 64, 96)
+  - Migration was supported throughout the v2.x series
+
+- **REMOVED**: Migration helper functions and deprecation infrastructure
+  
+  - Removed ``migrate_operation_mode_usage()`` function
+  - Removed ``enable_deprecation_warnings()`` function
+  - Removed migration documentation files (MIGRATION.md, BREAKING_CHANGES_V3.md)
+  - All functionality available through ``DhwOperationSetting`` and ``CurrentOperationMode``
+
 Version 2.0.0 (Unreleased)
 ==========================
 
 **Breaking Changes (Planned for v3.0.0)**
 
 - **DEPRECATION**: ``OperationMode`` enum is deprecated and will be removed in v3.0.0
+
   
   - Use ``DhwOperationSetting`` for user-configured mode preferences (values 1-6)
   - Use ``CurrentOperationMode`` for real-time operational states (values 0, 32, 64, 96)

{nwp500_python-2.0.0 → nwp500_python-3.1.0}/CONTRIBUTING.rst

@@ -120,7 +120,7 @@ Clone the repository
 
 #. You should run::
 
-   pip install -U pip setuptools -e .
+       pip install -U pip setuptools -e .
 
 .. note::
 

{nwp500_python-2.0.0/src/nwp500_python.egg-info → nwp500_python-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 2.0.0
+Version: 3.1.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-3.1.0/docs/configuration.rst

@@ -0,0 +1,331 @@
+=============
+Configuration
+=============
+
+This guide covers configuring the nwp500-python library for your
+environment.
+
+Credentials
+===========
+
+The library requires your Navien Smart Control credentials (email and
+password used in the Navilink mobile app).
+
+Environment Variables (Recommended)
+------------------------------------
+
+Store credentials in environment variables for security:
+
+**Linux/macOS:**
+
+.. code-block:: bash
+
+   export NAVIEN_EMAIL="your-email@example.com"
+   export NAVIEN_PASSWORD="your-password"
+
+**Windows (PowerShell):**
+
+.. code-block:: powershell
+
+   $env:NAVIEN_EMAIL="your-email@example.com"
+   $env:NAVIEN_PASSWORD="your-password"
+
+**Windows (Command Prompt):**
+
+.. code-block:: bat
+
+   set NAVIEN_EMAIL=your-email@example.com
+   set NAVIEN_PASSWORD=your-password
+
+Then in your code:
+
+.. code-block:: python
+
+   import os
+   from nwp500 import NavienAuthClient
+
+   email = os.getenv("NAVIEN_EMAIL")
+   password = os.getenv("NAVIEN_PASSWORD")
+
+   async with NavienAuthClient(email, password) as auth:
+       # ...
+
+Configuration File
+------------------
+
+Create a config file (keep this private!):
+
+.. code-block:: ini
+
+   # config.ini
+   [navien]
+   email = your-email@example.com
+   password = your-password
+
+Load it in your code:
+
+.. code-block:: python
+
+   import configparser
+   from nwp500 import NavienAuthClient
+
+   config = configparser.ConfigParser()
+   config.read('config.ini')
+
+   email = config['navien']['email']
+   password = config['navien']['password']
+
+   async with NavienAuthClient(email, password) as auth:
+       # ...
+
+.. warning::
+   Never commit configuration files with credentials to version control!
+   Add ``config.ini`` to your ``.gitignore`` file.
+
+Direct in Code (Not Recommended)
+---------------------------------
+
+Only for testing:
+
+.. code-block:: python
+
+   from nwp500 import NavienAuthClient
+
+   async with NavienAuthClient(
+       "your-email@example.com",
+       "your-password"
+   ) as auth:
+       # ...
+
+Authentication Options
+======================
+
+Timeout Settings
+----------------
+
+Configure request timeouts:
+
+.. code-block:: python
+
+   from nwp500 import NavienAuthClient
+
+   # Increase timeout for slow connections
+   async with NavienAuthClient(
+       email,
+       password,
+       timeout=60  # seconds
+   ) as auth:
+       # ...
+
+Custom Base URL
+---------------
+
+Use a different API endpoint (for testing or proxies):
+
+.. code-block:: python
+
+   from nwp500 import NavienAuthClient, NavienAPIClient
+
+   async with NavienAuthClient(email, password) as auth:
+       api = NavienAPIClient(
+           auth,
+           base_url="https://custom.api.url/api/v2.1"
+       )
+
+MQTT Configuration
+==================
+
+The MQTT client supports various configuration options through
+``MqttConnectionConfig``:
+
+Basic Configuration
+-------------------
+
+.. code-block:: python
+
+   from nwp500 import NavienMqttClient, MqttConnectionConfig
+   from nwp500.mqtt_utils import MqttConnectionConfig
+
+   config = MqttConnectionConfig(
+       client_id="my-custom-client",  # or None for auto-generated
+       clean_session=True,
+       keep_alive_secs=1200
+   )
+
+   mqtt = NavienMqttClient(auth, config=config)
+
+Reconnection Settings
+---------------------
+
+Configure automatic reconnection behavior:
+
+.. code-block:: python
+
+   config = MqttConnectionConfig(
+       auto_reconnect=True,
+       max_reconnect_attempts=15,
+       initial_reconnect_delay=1.0,  # seconds
+       max_reconnect_delay=120.0,    # seconds
+       reconnect_backoff_multiplier=2.0
+   )
+
+Command Queue Settings
+----------------------
+
+Configure command queueing when disconnected:
+
+.. code-block:: python
+
+   config = MqttConnectionConfig(
+       enable_command_queue=True,
+       max_queued_commands=100
+   )
+
+Complete Example
+----------------
+
+.. code-block:: python
+
+   from nwp500 import NavienMqttClient
+   from nwp500.mqtt_utils import MqttConnectionConfig
+
+   config = MqttConnectionConfig(
+       # Connection
+       endpoint="a1t30mldyslmuq-ats.iot.us-east-1.amazonaws.com",
+       region="us-east-1",
+       client_id="my-app-client",
+       clean_session=True,
+       keep_alive_secs=1200,
+       
+       # Reconnection
+       auto_reconnect=True,
+       max_reconnect_attempts=10,
+       initial_reconnect_delay=1.0,
+       max_reconnect_delay=120.0,
+       reconnect_backoff_multiplier=2.0,
+       
+       # Command queue
+       enable_command_queue=True,
+       max_queued_commands=100
+   )
+
+   mqtt = NavienMqttClient(auth, config=config)
+
+Logging Configuration
+=====================
+
+The library uses Python's standard logging module:
+
+Basic Logging
+-------------
+
+.. code-block:: python
+
+   import logging
+
+   # Enable all library logs
+   logging.basicConfig(
+       level=logging.DEBUG,
+       format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+   )
+
+Selective Logging
+-----------------
+
+.. code-block:: python
+
+   import logging
+
+   # Only log from nwp500 library
+   nwp_logger = logging.getLogger('nwp500')
+   nwp_logger.setLevel(logging.INFO)
+
+   # Only log MQTT messages
+   mqtt_logger = logging.getLogger('nwp500.mqtt_client')
+   mqtt_logger.setLevel(logging.DEBUG)
+
+Log to File
+-----------
+
+.. code-block:: python
+
+   import logging
+
+   logging.basicConfig(
+       level=logging.INFO,
+       format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+       handlers=[
+           logging.FileHandler('navien.log'),
+           logging.StreamHandler()
+       ]
+   )
+
+Best Practices
+==============
+
+1. **Never hardcode credentials** - Use environment variables or config
+   files
+2. **Use async context managers** - Ensures proper cleanup
+3. **Enable logging** - Helps debug issues
+4. **Handle exceptions** - Network errors are common
+5. **Rate limit API calls** - Use MQTT for real-time updates
+6. **Secure config files** - Set proper file permissions (chmod 600)
+
+Example: Production Configuration
+==================================
+
+.. code-block:: python
+
+   import os
+   import logging
+   from nwp500 import NavienAuthClient, NavienMqttClient
+   from nwp500.mqtt_utils import MqttConnectionConfig
+
+   # Configure logging
+   logging.basicConfig(
+       level=logging.INFO,
+       format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+       handlers=[
+           logging.FileHandler('/var/log/navien.log'),
+           logging.StreamHandler()
+       ]
+   )
+
+   # Get credentials from environment
+   email = os.getenv("NAVIEN_EMAIL")
+   password = os.getenv("NAVIEN_PASSWORD")
+
+   if not email or not password:
+       raise ValueError(
+           "NAVIEN_EMAIL and NAVIEN_PASSWORD must be set"
+       )
+
+   # Configure MQTT with reconnection
+   mqtt_config = MqttConnectionConfig(
+       auto_reconnect=True,
+       max_reconnect_attempts=15,
+       enable_command_queue=True
+   )
+
+   async def main():
+       try:
+           async with NavienAuthClient(
+               email,
+               password,
+               timeout=30
+           ) as auth:
+               mqtt = NavienMqttClient(auth, config=mqtt_config)
+               await mqtt.connect()
+               # ... your application code ...
+               await mqtt.disconnect()
+       except Exception as e:
+           logging.error(f"Application error: {e}", exc_info=True)
+           raise
+
+Next Steps
+==========
+
+* :doc:`quickstart` - Build your first application
+* :doc:`python_api/auth_client` - Authentication details
+* :doc:`python_api/mqtt_client` - MQTT client configuration
+* :doc:`guides/auto_recovery` - Automatic reconnection guide

nwp500_python-3.1.0/docs/development/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst

nwp500_python-2.0.0/docs/DEVELOPMENT.rst → nwp500_python-3.1.0/docs/development/history.rst

@@ -87,8 +87,8 @@ compatibility - Automatic credential handling from authentication API -
 Session ID generation for connection tracking
 
 **Key Files:** - ``src/nwp500/mqtt_client.py`` - MQTT client
-implementation - :doc:`MQTT_CLIENT` - Complete documentation -
-:doc:`MQTT_MESSAGES` - Message format reference
+implementation - :doc:`../python_api/mqtt_client` - Complete documentation -
+:doc:`../protocol/mqtt_protocol` - Message format reference
 
 Device Status & Feature Callbacks (October 7, 2025)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -268,7 +268,7 @@ Complete event-driven architecture for device state changes:
 - ``src/nwp500/mqtt_client.py`` - MQTT integration with event emitter
 - ``examples/event_emitter_demo.py`` - Comprehensive demonstration
 - ``tests/test_events.py`` - Unit tests (19 tests)
-- :doc:`EVENT_EMITTER` - Feature documentation
+- :doc:`../python_api/events` - Feature documentation
 
 **Thread Safety Implementation:**
 
@@ -337,8 +337,8 @@ References
 ----------
 
 - `OpenAPI Specification <openapi.yaml>`__ - API specification
-- :doc:`MQTT_MESSAGES` - MQTT message reference
-- :doc:`DEVICE_STATUS_FIELDS` - Device status fields
-- :doc:`AUTHENTICATION` - Authentication guide
-- :doc:`API_CLIENT` - API client guide
-- :doc:`MQTT_CLIENT` - MQTT client guide
+- :doc:`../protocol/mqtt_protocol` - MQTT message reference
+- :doc:`../protocol/device_status` - Device status fields
+- :doc:`../python_api/auth_client` - Authentication guide
+- :doc:`../python_api/api_client` - API client guide
+- :doc:`../python_api/mqtt_client` - MQTT client guide

nwp500_python-2.0.0/docs/AUTO_RECOVERY.rst → nwp500_python-3.1.0/docs/guides/auto_recovery.rst

@@ -1,6 +1,6 @@
-========================================
+===============================================
 Automatic Reconnection After Connection Failure
-========================================
+===============================================
 
 This guide explains how to automatically recover from permanent MQTT connection failures (after max reconnection attempts are exhausted).
 

nwp500_python-2.0.0/docs/COMMAND_QUEUE.rst → nwp500_python-3.1.0/docs/guides/command_queue.rst

@@ -300,9 +300,9 @@ Technical Notes
 See Also
 ========
 
-- :doc:`MQTT_CLIENT` - MQTT client documentation
-- :doc:`EVENT_EMITTER` - Event emitter documentation
-- :doc:`AUTHENTICATION` - Authentication and tokens
+- :doc:`../python_api/mqtt_client` - MQTT client documentation
+- :doc:`../python_api/events` - Event emitter documentation
+- :doc:`../python_api/auth_client` - Authentication and tokens
 
 Example Code
 ============

nwp500_python-2.0.0/docs/ENERGY_MONITORING.rst → nwp500_python-3.1.0/docs/guides/energy_monitoring.rst

@@ -334,6 +334,6 @@ Notes
 See Also
 --------
 
-- :doc:`DEVICE_STATUS_FIELDS` - Complete list of all status fields
-- :doc:`MQTT_CLIENT` - How to connect and subscribe to device updates
-- :doc:`MQTT_MESSAGES` - Message format reference
+- :doc:`../protocol/device_status` - Complete list of all status fields
+- :doc:`../python_api/mqtt_client` - How to connect and subscribe to device updates
+- :doc:`../protocol/mqtt_protocol` - Message format reference