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

nwp500_python-2.0.0/BREAKING_CHANGES_V3.md

@@ -0,0 +1,122 @@
+# Breaking Changes for v3.0.0
+
+This document outlines the breaking changes planned for nwp500-python v3.0.0.
+
+## Overview
+
+Version 3.0.0 will be the first major version to include breaking changes since the library's initial release. The primary focus is removing deprecated functionality and improving type safety.
+
+## Scheduled Removals
+
+### OperationMode Enum Removal
+
+**Target**: v3.0.0  
+**Current Status**: Deprecated in v2.0.0  
+**Migration Period**: v2.x series (minimum 6 months)
+
+The original `OperationMode` enum will be completely removed and replaced with:
+- `DhwOperationSetting` for user-configured mode preferences
+- `CurrentOperationMode` for real-time operational states
+
+#### Impact Assessment
+- **High Impact**: Code using direct enum comparisons
+- **Medium Impact**: Type hints and function signatures
+- **Low Impact**: Display-only usage (`.name` attribute)
+
+#### Required Actions
+1. Replace all `OperationMode` imports with specific enum imports
+2. Update enum comparisons to use appropriate enum type
+3. Update type hints in function signatures
+4. Remove any `OperationMode` references from custom code
+
+#### Migration Tools Available
+- `MIGRATION.md` - Comprehensive migration guide
+- `migrate_operation_mode_usage()` - Programmatic guidance
+- `enable_deprecation_warnings()` - Runtime warning system
+- Updated documentation with new enum usage patterns
+
+## Pre-3.0 Checklist
+
+Before releasing v3.0.0, ensure:
+
+### Code Removal
+- [ ] Remove `OperationMode` enum class from `models.py`
+- [ ] Remove `OperationMode` from package exports (`__init__.py`)
+- [ ] Remove deprecation warning infrastructure
+- [ ] Update all internal references to use new enums
+
+### Documentation Updates  
+- [ ] Update all documentation to remove `OperationMode` references
+- [ ] Update `MIGRATION.md` to reflect completed migration
+- [ ] Update API documentation
+- [ ] Update example scripts if any still reference old enum
+
+### Testing
+- [ ] Ensure all tests pass without `OperationMode`
+- [ ] Add tests to verify enum removal
+- [ ] Test that import errors are clear and helpful
+- [ ] Validate all examples work with new enums only
+
+### Communication
+- [ ] Update CHANGELOG.rst with breaking changes
+- [ ] Release notes highlighting breaking changes
+- [ ] GitHub release with migration guidance
+- [ ] Consider blog post or announcement for major users
+
+## Timeline
+
+```
+v2.0.0 (Current)
+├── OperationMode deprecated
+├── New enums introduced  
+├── Migration tools provided
+└── Backward compatibility maintained
+
+v2.1.0 (Optional)
+├── Optional deprecation warnings
+├── Enhanced migration tools
+└── Continued compatibility
+
+v2.x.x (6+ months)
+├── Migration period
+├── User feedback collection
+└── Migration assistance
+
+v3.0.0 (Target)
+├── OperationMode removed
+├── Breaking changes implemented
+└── Type safety improvements
+```
+
+## Rollback Plan
+
+If breaking changes cause significant issues:
+
+1. **Emergency Patch**: Revert breaking changes in v3.0.1
+2. **Deprecation Extension**: Extend deprecation period to v4.0.0
+3. **Enhanced Migration**: Provide additional migration tools
+4. **Communication**: Clear messaging about timeline changes
+
+## Version Support
+
+- **v2.x**: Long-term support with security fixes
+- **v3.x**: Current development branch
+- **v1.x**: End-of-life (security fixes only if critical)
+
+## Migration Support
+
+Migration support will be available:
+- **During v2.x**: Full backward compatibility + new enums
+- **During v3.0 beta**: Migration warnings and testing
+- **After v3.0**: Documentation and examples only
+
+## Contact
+
+For questions about breaking changes or migration assistance:
+- File GitHub issues with "migration" label
+- Reference `MIGRATION.md` for detailed guidance
+- Use `migrate_operation_mode_usage()` for programmatic help
+
+---
+
+*This document will be updated as v3.0.0 approaches with more specific details and timelines.*

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

@@ -2,6 +2,65 @@
 Changelog
 =========
 
+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)
+  - See ``MIGRATION.md`` for detailed migration guide
+
+Added
+-----
+
+- **Enhanced Type Safety**: Split ``OperationMode`` into semantically distinct enums
+
+  - ``DhwOperationSetting``: User-configured mode preferences (HEAT_PUMP, ELECTRIC, ENERGY_SAVER, HIGH_DEMAND, VACATION, POWER_OFF)
+  - ``CurrentOperationMode``: Real-time operational states (STANDBY, HEAT_PUMP_MODE, HYBRID_EFFICIENCY_MODE, HYBRID_BOOST_MODE)
+  - Prevents accidental comparison of user preferences with real-time states
+  - Better IDE support with more specific enum types
+
+- **Migration Support**: Comprehensive tools for smooth migration
+
+  - ``migrate_operation_mode_usage()`` helper function with programmatic guidance
+  - ``MIGRATION.md`` with step-by-step migration instructions
+  - Value mappings and common usage pattern examples
+  - Backward compatibility preservation during transition
+
+- **Documentation Updates**: Updated all documentation to reflect new enum structure
+
+  - ``DEVICE_STATUS_FIELDS.rst`` updated with new enum types
+  - Code examples use new enums with proper imports
+  - Clear distinction between configuration vs real-time status
+
+Changed
+-------
+
+- **DeviceStatus Model**: Updated to use specific enum types
+
+  - ``operationMode`` field now uses ``CurrentOperationMode`` type
+  - ``dhwOperationSetting`` field now uses ``DhwOperationSetting`` type
+  - Maintains backward compatibility through value preservation
+
+- **Example Scripts**: Updated to demonstrate new enum usage
+
+  - ``event_emitter_demo.py`` updated to use ``CurrentOperationMode``
+  - Fixed incorrect enum references (HEAT_PUMP_ONLY → HEAT_PUMP_MODE)
+  - All examples remain functional with new type system
+
+Deprecated
+----------
+
+- **OperationMode enum**: Will be removed in v3.0.0
+
+  - All functionality preserved for backward compatibility
+  - Migration guide available in ``MIGRATION.md``
+  - Helper function ``migrate_operation_mode_usage()`` provides guidance
+  - Original enum remains available during transition period
+
 Version 1.2.2 (2025-10-17)
 ==========================
 

nwp500_python-2.0.0/MIGRATION.md

@@ -0,0 +1,217 @@
+# Migration Guide: OperationMode → DhwOperationSetting & CurrentOperationMode
+
+## Overview
+
+In version 2.x of nwp500-python, the `OperationMode` enum has been split into two more specific enums to improve code clarity and type safety:
+
+- **`DhwOperationSetting`**: User-configured mode preferences (values 1-6)
+- **`CurrentOperationMode`**: Real-time operational states (values 0, 32, 64, 96)
+
+This change clarifies the distinction between "what mode the user has configured" vs "what the device is doing right now."
+
+## Why This Change?
+
+The original `OperationMode` enum mixed two different concepts:
+1. **User preferences** (1-6): What heating mode should be used when heating is needed
+2. **Real-time status** (0, 32, 64, 96): What the device is actively doing right now
+
+This led to confusion and potential bugs. The new enums provide:
+- **Type safety**: Can't accidentally compare user preferences with real-time states
+- **Clarity**: Clear distinction between configuration and current operation
+- **Better IDE support**: More specific autocomplete and type checking
+
+## Migration Steps
+
+### 1. Update Imports
+
+**Before:**
+```python
+from nwp500 import OperationMode
+```
+
+**After:**
+```python
+from nwp500 import DhwOperationSetting, CurrentOperationMode
+# or keep the old import during transition:
+from nwp500 import OperationMode, DhwOperationSetting, CurrentOperationMode
+```
+
+### 2. Update DHW Operation Setting Comparisons
+
+**Before:**
+```python
+if status.dhwOperationSetting == OperationMode.ENERGY_SAVER:
+    print("Device configured for Energy Saver mode")
+
+if status.dhwOperationSetting == OperationMode.POWER_OFF:
+    print("Device is powered off")
+```
+
+**After:**
+```python
+if status.dhwOperationSetting == DhwOperationSetting.ENERGY_SAVER:
+    print("Device configured for Energy Saver mode")
+
+if status.dhwOperationSetting == DhwOperationSetting.POWER_OFF:
+    print("Device is powered off")
+```
+
+### 3. Update Operation Mode Comparisons
+
+**Before:**
+```python
+if status.operationMode == OperationMode.STANDBY:
+    print("Device is idle")
+
+if status.operationMode == OperationMode.HEAT_PUMP_MODE:
+    print("Heat pump is running")
+```
+
+**After:**
+```python
+if status.operationMode == CurrentOperationMode.STANDBY:
+    print("Device is idle")
+
+if status.operationMode == CurrentOperationMode.HEAT_PUMP_MODE:
+    print("Heat pump is running")
+```
+
+### 4. Update Type Hints
+
+**Before:**
+```python
+def handle_mode_change(old_mode: OperationMode, new_mode: OperationMode):
+    pass
+
+def check_dhw_setting(setting: OperationMode) -> bool:
+    pass
+```
+
+**After:**
+```python
+def handle_mode_change(old_mode: CurrentOperationMode, new_mode: CurrentOperationMode):
+    pass
+
+def check_dhw_setting(setting: DhwOperationSetting) -> bool:
+    pass
+```
+
+### 5. Update Command Sending Logic
+
+**Before:**
+```python
+# Vacation mode check
+if mode_id == OperationMode.VACATION.value:
+    # handle vacation days parameter
+```
+
+**After:**
+```python
+# Vacation mode check  
+if mode_id == DhwOperationSetting.VACATION.value:
+    # handle vacation days parameter
+```
+
+## Value Mappings
+
+### DhwOperationSetting (User Preferences)
+```python
+DhwOperationSetting.HEAT_PUMP = 1      # Heat Pump Only
+DhwOperationSetting.ELECTRIC = 2       # Electric Only  
+DhwOperationSetting.ENERGY_SAVER = 3   # Energy Saver (default)
+DhwOperationSetting.HIGH_DEMAND = 4    # High Demand
+DhwOperationSetting.VACATION = 5       # Vacation Mode
+DhwOperationSetting.POWER_OFF = 6      # Device Powered Off
+```
+
+### CurrentOperationMode (Real-time States)  
+```python
+CurrentOperationMode.STANDBY = 0                 # Device idle
+CurrentOperationMode.HEAT_PUMP_MODE = 32         # Heat pump active
+CurrentOperationMode.HYBRID_EFFICIENCY_MODE = 64 # Energy Saver mode heating
+CurrentOperationMode.HYBRID_BOOST_MODE = 96      # High Demand mode heating
+```
+
+## Common Migration Patterns
+
+### Event Handlers
+**Before:**
+```python
+def on_mode_change(old_mode: OperationMode, new_mode: OperationMode):
+    if new_mode == OperationMode.HEAT_PUMP_MODE:
+        print("Heat pump started")
+```
+
+**After:**
+```python
+def on_mode_change(old_mode: CurrentOperationMode, new_mode: CurrentOperationMode):
+    if new_mode == CurrentOperationMode.HEAT_PUMP_MODE:
+        print("Heat pump started")
+```
+
+### Status Display Logic
+**Before:**
+```python
+def get_device_status(status: DeviceStatus) -> dict:
+    return {
+        'mode': status.dhwOperationSetting.name,  # User's setting
+        'active': status.operationMode != OperationMode.STANDBY,  # Currently heating?
+        'powered_on': status.dhwOperationSetting != OperationMode.POWER_OFF
+    }
+```
+
+**After:**
+```python
+def get_device_status(status: DeviceStatus) -> dict:
+    return {
+        'mode': status.dhwOperationSetting.name,  # User's setting
+        'active': status.operationMode != CurrentOperationMode.STANDBY,  # Currently heating?
+        'powered_on': status.dhwOperationSetting != DhwOperationSetting.POWER_OFF
+    }
+```
+
+## Backward Compatibility
+
+The original `OperationMode` enum remains available for backward compatibility but is **deprecated**:
+
+```python
+# Still works, but deprecated
+from nwp500 import OperationMode
+if status.dhwOperationSetting == OperationMode.ENERGY_SAVER:
+    pass
+```
+
+**Note**: The deprecated enum will be removed in a future major version (3.0+).
+
+## Testing Your Migration
+
+Use the migration helper to validate your changes:
+
+```python
+from nwp500 import migrate_operation_mode_usage
+
+# Get migration guidance
+guide = migrate_operation_mode_usage()
+print(guide['migration_examples'])
+```
+
+## Timeline
+
+- **Current (2.x)**: Both old and new enums available, old enum deprecated
+- **Next minor (2.x+1)**: Deprecation warnings added  
+- **Future major (3.0)**: `OperationMode` enum removed
+
+## Need Help?
+
+- Check the [documentation](docs/DEVICE_STATUS_FIELDS.rst) for detailed explanations
+- Use the `migrate_operation_mode_usage()` helper function for guidance
+- Look at updated examples in the `examples/` directory
+- File an issue if you encounter migration problems
+
+## Benefits After Migration
+
+1. **Type Safety**: Compiler/IDE catches enum mismatches
+2. **Clarity**: Clear distinction between user preferences and device state  
+3. **Better Documentation**: Each enum has focused, specific documentation
+4. **Future-Proof**: Easier to extend either enum independently
+5. **Reduced Bugs**: Impossible to accidentally compare incompatible concepts

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 1.2.3
+Version: 2.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-1.2.3 → nwp500_python-2.0.0}/docs/DEVICE_STATUS_FIELDS.rst

@@ -44,7 +44,7 @@ This document lists the fields found in the ``status`` object of device status m
      - Sub error code providing additional error details. See ERROR_CODES.rst for details.
      - None
    * - ``operationMode``
-     - OperationMode
+     - CurrentOperationMode
      - None
      - The current **actual operational state** of the device (what it's doing RIGHT NOW). Reports status values: 0=Standby, 32=Heat Pump active, 64=Energy Saver active, 96=High Demand active. See Operation Modes section below for the critical distinction between this and ``dhwOperationSetting``.
      - None
@@ -229,9 +229,9 @@ This document lists the fields found in the ``status`` object of device status m
      - Type of program reservation.
      - None
    * - ``dhwOperationSetting``
-     - OperationMode
+     - DhwOperationSetting
      - None
-     - User's configured DHW operation mode preference. This field uses the same ``OperationMode`` enum as ``operationMode`` but contains command mode values (1=HEAT_PUMP, 2=ELECTRIC, 3=ENERGY_SAVER, 4=HIGH_DEMAND, 5=VACATION, 6=POWER_OFF). When the device is powered off via the power-off command, this field will show 6 (POWER_OFF). This is how to distinguish between "powered off" vs "on but in standby". See the Operation Modes section below for details.
+     - User's configured DHW operation mode preference. This field uses the ``DhwOperationSetting`` enum (separate from ``CurrentOperationMode``) and contains command mode values (1=HEAT_PUMP, 2=ELECTRIC, 3=ENERGY_SAVER, 4=HIGH_DEMAND, 5=VACATION, 6=POWER_OFF). When the device is powered off via the power-off command, this field will show 6 (POWER_OFF). This is how to distinguish between "powered off" vs "on but in standby". See the Operation Modes section below for details.
      - None
    * - ``temperatureType``
      - integer
@@ -533,10 +533,10 @@ These two fields serve different purposes and it's critical to understand their
 Field Definitions
 ^^^^^^^^^^^^^^^^^
 
-**dhwOperationSetting** (OperationMode enum with command values 1-5)
+**dhwOperationSetting** (DhwOperationSetting enum with command values 1-6)
   The user's **configured mode preference** - what heating mode the device should use when it needs to heat water. This is set via the ``dhw-mode`` command and persists until changed by the user or device.
   
-  * Type: ``OperationMode`` enum
+  * Type: ``DhwOperationSetting`` enum
   * Values: 
     
     * 1 = ``HEAT_PUMP`` (Heat Pump Only)
@@ -551,10 +551,10 @@ Field Definitions
   * Meaning: "When heating is needed, use this mode" OR "I'm powered off" (if value is 6)
   * Value 6 (``POWER_OFF``) indicates the device was powered off via the power-off command. This is how to distinguish between "powered off" and "on but idle".
 
-**operationMode** (OperationMode enum with status values 0, 32, 64, 96)
+**operationMode** (CurrentOperationMode enum with status values 0, 32, 64, 96)
   The device's **current actual operational state** - what the device is doing RIGHT NOW. This reflects real-time operation and changes automatically based on whether the device is idle or actively heating.
   
-  * Type: ``OperationMode`` enum
+  * Type: ``CurrentOperationMode`` enum
   * Values:
     
     * 0 = ``STANDBY`` (Idle, not heating)
@@ -661,11 +661,13 @@ For user-facing applications, follow these guidelines:
 **Code Example**
   .. code-block:: python
 
+    from nwp500.models import DeviceStatus, DhwOperationSetting, CurrentOperationMode
+
     def format_mode_display(status: DeviceStatus) -> dict:
         """Format mode and status for UI display."""
         
         # Check if device is powered off first
-        if status.dhwOperationSetting == OperationMode.POWER_OFF:
+        if status.dhwOperationSetting == DhwOperationSetting.POWER_OFF:
             return {
                 'configured_mode': 'Off',
                 'operational_state': 'Powered Off',
@@ -678,16 +680,16 @@ For user-facing applications, follow these guidelines:
         configured_mode = status.dhwOperationSetting.name.replace('_', ' ').title()
         
         # Current operational state
-        if status.operationMode == OperationMode.STANDBY:
+        if status.operationMode == CurrentOperationMode.STANDBY:
             operational_state = "Idle"
             is_heating = False
-        elif status.operationMode == OperationMode.HEAT_PUMP_MODE:
+        elif status.operationMode == CurrentOperationMode.HEAT_PUMP_MODE:
             operational_state = "Heating (Heat Pump)"
             is_heating = True
-        elif status.operationMode == OperationMode.HYBRID_EFFICIENCY_MODE:
+        elif status.operationMode == CurrentOperationMode.HYBRID_EFFICIENCY_MODE:
             operational_state = "Heating (Energy Saver)"
             is_heating = True
-        elif status.operationMode == OperationMode.HYBRID_BOOST_MODE:
+        elif status.operationMode == CurrentOperationMode.HYBRID_BOOST_MODE:
             operational_state = "Heating (High Demand)"
             is_heating = True
         else:
@@ -712,9 +714,9 @@ For user-facing applications, follow these guidelines:
 
 4. **operationMode changes automatically** - you cannot directly set this; it changes based on device operation
 
-5. **Both fields use OperationMode enum** - but different value ranges (1-6 for dhwOperationSetting, 0/32/64/96 for operationMode)
+5. **Separate enum types provide clarity** - ``DhwOperationSetting`` (values 1-6) for user preferences, ``CurrentOperationMode`` (values 0/32/64/96) for real-time states
 
-6. **Power off detection** - Check if ``dhwOperationSetting == 6`` (``POWER_OFF``) to determine if device is powered off vs just idle
+6. **Power off detection** - Check if ``dhwOperationSetting == DhwOperationSetting.POWER_OFF`` to determine if device is powered off vs just idle
 
 Technical Notes
 ---------------

{nwp500_python-1.2.3 → nwp500_python-2.0.0}/examples/event_emitter_demo.py

@@ -29,7 +29,7 @@ logging.basicConfig(
 )
 
 from nwp500 import NavienAPIClient, NavienAuthClient, NavienMqttClient
-from nwp500.models import DeviceStatus, OperationMode
+from nwp500.models import DeviceStatus, CurrentOperationMode
 
 
 # Example 1: Multiple listeners for the same event
@@ -52,16 +52,18 @@ async def save_temperature_to_db(old_temp: float, new_temp: float):
 
 
 # Example 2: Mode change handlers
-def log_mode_change(old_mode: OperationMode, new_mode: OperationMode):
+def log_mode_change(old_mode: CurrentOperationMode, new_mode: CurrentOperationMode):
     """Log operation mode changes."""
     print(f"🔄 [Mode] Changed from {old_mode.name} to {new_mode.name}")
 
 
-def optimize_on_mode_change(old_mode: OperationMode, new_mode: OperationMode):
+def optimize_on_mode_change(
+    old_mode: CurrentOperationMode, new_mode: CurrentOperationMode
+):
     """Optimization handler."""
-    if new_mode == OperationMode.HEAT_PUMP_ONLY:
+    if new_mode == CurrentOperationMode.HEAT_PUMP_MODE:
         print("♻️  [Optimizer] Heat pump mode - maximum efficiency!")
-    elif new_mode == OperationMode.HIGH_DEMAND:
+    elif new_mode == CurrentOperationMode.HYBRID_BOOST_MODE:
         print("⚡ [Optimizer] High demand mode - fast recovery!")
 
 

{nwp500_python-1.2.3 → nwp500_python-2.0.0}/examples/periodic_requests.py

@@ -75,7 +75,7 @@ async def main():
         print(f"\n--- Status Response #{status_count} ---")
         print(f"  Temperature: {status.dhwTemperature:.1f}°F")
         print(f"  Power: {status.currentInstPower:.1f}W")
-        print(f"  Available Energy: {status.availableEnergyCapacity:.1f}%")
+        print(f"  Available Energy: {status.availableEnergyCapacity:.0f} Wh")
 
     def on_device_feature(feature: DeviceFeature):
         """Callback receives parsed DeviceFeature objects."""

{nwp500_python-1.2.3 → nwp500_python-2.0.0}/examples/tou_schedule_example.py

@@ -17,8 +17,13 @@ async def _wait_for_controller_serial(mqtt_client: NavienMqttClient, device) ->
         if not feature_future.done():
             feature_future.set_result(feature)
 
-    mqtt_client.once("feature_received", capture_feature)
+    # Subscribe to device feature messages first
+    await mqtt_client.subscribe_device_feature(device, capture_feature)
+
+    # Then request device info
     await mqtt_client.request_device_info(device)
+
+    # Wait for the response
     feature = await asyncio.wait_for(feature_future, timeout=15)
     return feature.controllerSerialNumber