Skip to content

Commit 07c8d2e

Browse files
emaneman
committed
Update changelog for v7.2.0
1 parent 3d9bf9c commit 07c8d2e

1 file changed

Lines changed: 202 additions & 6 deletions

File tree

‎CHANGELOG.rst‎

Lines changed: 202 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,212 @@ Changelog
55
Version 7.2.0 (2025-12-23)
66
==========================
77

8+
**BREAKING CHANGES**: Class names renamed for consistency with MQTT-specific functionality
9+
10+
Removed
11+
-------
12+
13+
- **Renamed Classes**: Updated class names to clarify MQTT-specific implementations
14+
15+
.. code-block:: python
16+
17+
# OLD (removed)
18+
from nwp500 import DeviceCapabilityChecker, DeviceInfoCache
19+
20+
# NEW
21+
from nwp500 import MqttDeviceCapabilityChecker, MqttDeviceInfoCache
22+
23+
**Rationale**: The original names were too generic. These classes are specifically designed
24+
for MQTT client functionality (auto-fetching device info, caching, capability checking).
25+
The new names make it clear they're MQTT-specific implementations, leaving room for future
26+
REST API versions if needed.
27+
28+
**Migration**: Simple find-and-replace:
29+
30+
- ``DeviceCapabilityChecker`` → ``MqttDeviceCapabilityChecker``
31+
- ``DeviceInfoCache`` → ``MqttDeviceInfoCache``
32+
33+
All functionality remains identical - only the class names changed.
34+
835
Added
936
-----
1037

38+
- **Factory Function**: New ``create_navien_clients()`` factory for streamlined client initialization
39+
40+
.. code-block:: python
41+
42+
# Create both API and MQTT clients in one call
43+
from nwp500 import create_navien_clients
44+
45+
async with create_navien_clients(email, password) as (api_client, mqtt_client):
46+
devices = await api_client.get_devices()
47+
await mqtt_client.connect()
48+
# Both clients ready to use
49+
50+
- Automatic auth client management (created internally, shared by both clients)
51+
- Simplified initialization for common use case (API + MQTT)
52+
- Proper async context manager support
53+
- Reduces boilerplate in application code
54+
- Comprehensive documentation in ``docs/guides/authentication.rst``
55+
- Example: ``examples/intermediate/advanced_auth_patterns.py``
56+
57+
- **VolumeCode Enum**: Tank capacity identification with gallon values
58+
59+
.. code-block:: python
60+
61+
from nwp500 import VolumeCode
62+
63+
# Enum values: VOLUME_50GAL = 65, VOLUME_65GAL = 66, VOLUME_80GAL = 67
64+
# Human-readable text available in VOLUME_CODE_TEXT dict
65+
66+
- Maps device codes to actual tank capacities (50, 65, 80 gallons)
67+
- Used in ``DeviceFeature.volume_code`` field with automatic validation
68+
- Exported from main package for convenience
69+
- Includes ``VOLUME_CODE_TEXT`` mapping for display purposes
70+
71+
- **Temperature Conversion Classes**: Type-safe temperature handling with clear precision
72+
73+
- ``HalfCelsius`` class: 0.5°C precision (value / 2.0)
74+
- ``DeciCelsius`` class: 0.1°C precision (value / 10.0)
75+
- Base ``Temperature`` ABC with ``to_celsius()`` and ``to_fahrenheit()`` methods
76+
- ``from_fahrenheit()`` class methods for reverse conversions
77+
- Validator functions for Pydantic integration
78+
- Centralized in new ``temperature.py`` module
79+
- Better type safety and clearer intent than raw number conversions
80+
81+
- **Protocol Converters Module**: Centralized device protocol conversion logic
82+
83+
- ``device_bool_to_python()``: Convert device boolean (1=False, 2=True)
84+
- ``device_bool_from_python()``: Reverse conversion
85+
- ``tou_status_to_python()``: Time of Use status conversion
86+
- ``tou_override_to_python()``: TOU override status conversion
87+
- ``div_10()``: Divide by 10.0 utility
88+
- ``enum_validator()``: Generic enum factory
89+
- Comprehensive documentation explaining device protocol quirks
90+
- New ``converters.py`` module replacing scattered validators
91+
92+
- **MQTT Event System**: Structured event handling for MQTT operations
93+
94+
- ``MqttClientEvents`` class with type-safe event definitions
95+
- Feature monitoring and capability detection events
96+
- Enhanced device capability monitoring in MQTT control module
97+
- New ``mqtt_events.py`` module for event infrastructure
98+
- Improved separation of concerns for event-driven architectures
99+
100+
- **Pyright Type Checking**: Static type analysis integrated into CI/CD
101+
102+
- Added pyright>=1.1.0 to dev dependencies
103+
- Configured in ``pyproject.toml`` with strict mode for ``src/nwp500``
104+
- Integrated into tox lint environment and CI workflows
105+
- Runs automatically with ``make ci-lint`` or ``python3 scripts/lint.py``
106+
- All source code now passes strict type checking (0 errors)
107+
- Improved type annotations across codebase
108+
11109
- **Dynamic Unit Extraction in CLI**: CLI output now dynamically extracts units from DeviceStatus model metadata
110+
12111
- New helper functions: ``_get_unit_suffix()`` and ``_add_numeric_item()``
13112
- Eliminates hardcoded units in output formatter
14113
- Single source of truth: model metadata drives CLI display
15114

115+
- **Comprehensive Protocol Documentation**: Complete protocol reference documentation
116+
117+
- New ``docs/protocol/quick_reference.rst`` with command codes, field formats, and conversions
118+
- Converted protocol documentation to RST format for Sphinx integration
119+
- Added protocol reference links in source code comments
120+
- Improved cross-referencing between code and documentation
121+
122+
Changed
123+
-------
124+
125+
- **MQTT Module Reorganization**: Consolidated 9 separate modules into cohesive ``mqtt`` package
126+
127+
.. code-block:: python
128+
129+
# OLD imports (still work via compatibility layer)
130+
from nwp500.mqtt_client import NavienMqttClient
131+
from nwp500.mqtt_diagnostics import MqttDiagnosticsCollector
132+
from nwp500.mqtt_utils import MqttConnectionConfig
133+
134+
# NEW imports (preferred)
135+
from nwp500.mqtt import NavienMqttClient, MqttDiagnosticsCollector, MqttConnectionConfig
136+
# OR import from main package (recommended)
137+
from nwp500 import NavienMqttClient, MqttDiagnosticsCollector, MqttConnectionConfig
138+
139+
- Created ``src/nwp500/mqtt/`` package with organized submodules
140+
- Better package organization and structure
141+
- Clearer public vs internal APIs
142+
- New ``mqtt/__init__.py`` with clean public API exports
143+
- Backward compatibility maintained via main package exports
144+
- All 209 tests pass with zero type checking errors
145+
146+
- **CLI Framework Migration**: Migrated from argparse to Click framework
147+
148+
- Implemented ``async_command`` decorator for automatic loop and connection management
149+
- Added support for command groups (reservations, tou)
150+
- Improved argument and option parsing with built-in validation
151+
- Enhanced help text and version reporting
152+
- Centralized command registry in ``src/nwp500/cli/commands.py``
153+
- Reorganized CLI handlers into ``src/nwp500/cli/handlers.py``
154+
- Better separation of concerns between CLI framework and business logic
155+
- Industry-standard CLI framework with better maintainability
156+
- Added click>=8.0.0 dependency
157+
158+
- **Examples Reorganization**: Restructured examples into beginner/intermediate/advanced/testing categories
159+
160+
- Created structured hierarchy in ``examples/`` directory
161+
- Renamed and moved 35+ example scripts for better discoverability
162+
- Updated ``examples/README.md`` with 'Getting Started' guide and categorized index
163+
- Added 01-04 beginner series for smooth onboarding:
164+
165+
- ``beginner/01_authentication.py`` - Basic authentication patterns
166+
- ``beginner/02_list_devices.py`` - Retrieving device information
167+
- ``beginner/03_get_status.py`` - Getting device status
168+
- ``beginner/04_set_temperature.py`` - Basic device control
169+
170+
- Intermediate examples: event-driven control, error handling, MQTT monitoring
171+
- Advanced examples: demand response, recirculation, TOU schedules, diagnostics
172+
- Testing examples: connection testing, periodic updates, minimal examples
173+
- All examples updated with correct imports for new package structure
174+
175+
- **Authentication Documentation**: Major improvements to authentication guide
176+
177+
- Complete rewrite of ``docs/guides/authentication.rst``
178+
- Added factory function patterns and examples
179+
- Improved context manager documentation
180+
- Added best practices and common patterns
181+
- More comprehensive code examples
182+
183+
- **Model Refactoring**: Updated to use new converter modules
184+
185+
- Replaced 53 lines of scattered validators with imports
186+
- Updated ``fahrenheit_to_half_celsius()`` to use ``HalfCelsius`` class
187+
- Cleaner model definitions with centralized conversion logic
188+
- No breaking changes to public API
189+
190+
- **CLI Output Formatter Refactoring**: Restructured ``print_device_status()`` to use dynamic unit extraction
191+
192+
- Reduced code duplication by ~400 lines
193+
- Improved maintainability: field additions automatically get correct units
194+
- No breaking changes to CLI output format or behavior
195+
196+
- **Type Annotations**: Improved type safety across entire codebase
197+
198+
- Fixed datetime imports to use ``datetime.UTC`` (Python 3.13)
199+
- Fixed type annotations in ``rich_output.py`` for optional dependencies
200+
- Fixed type narrowing issues in ``encoding.py``
201+
- Updated ``MqttConnection`` callback signature to use ``AwsCrtError``
202+
- Added public properties and setters where needed for type checking
203+
16204
Fixed
17205
-----
18206

19207
- **Superheat Temperature Units**: Target and Current SuperHeat now correctly display in °F instead of °C
208+
20209
- Both fields use ``DeciCelsiusToF`` conversion, now properly reflected in CLI output
21210
- Fields were displaying inconsistent units compared to all other temperature readings
22211

23212
- **Missing CLI Output Units**: Multiple fields now display with proper units from model metadata
213+
24214
- ``current_dhw_flow_rate``: Now shows GPM unit
25215
- ``total_energy_capacity``: Now shows Wh unit
26216
- ``available_energy_capacity``: Now shows Wh unit
@@ -31,17 +221,23 @@ Fixed
31221
- ``wifi_rssi``: Now shows dBm unit
32222

33223
- **Invalid MQTT Topic Filter**: Fixed ``reservations get`` command subscription topic
224+
34225
- Changed invalid topic pattern ``cmd/52/navilink-+/#`` to valid ``cmd/52/+/#``
35226
- AWS IoT Core MQTT does not support wildcards within topic segments
36227
- Affected: ``handle_get_reservations_request()`` in commands.py
37228

38-
Changed
39-
-------
229+
- **DeviceFeature Documentation**: Clarified field descriptions and fixed documentation errors
40230

41-
- **CLI Output Formatter Refactoring**: Restructured ``print_device_status()`` to use dynamic unit extraction
42-
- Reduced code duplication by ~400 lines
43-
- Improved maintainability: field additions automatically get correct units
44-
- No breaking changes to CLI output format or behavior
231+
- Fixed ``country_code`` documentation (actual value is 3, not 1 as previously noted)
232+
- Clarified ``model_type_code``, ``control_type_code``, ``recirc_model_type_code`` field purposes
233+
- Updated ``volume_code`` to use new ``VolumeCode`` enum with validation
234+
235+
- **Type Checking Errors**: Resolved all pyright type checking errors in source code
236+
237+
- Fixed datetime imports and type annotations
238+
- Added missing public properties and setters
239+
- Removed unused imports and variables
240+
- All source code now passes strict type checking
45241

46242
Version 7.1.0 (2025-12-22)
47243
==========================

0 commit comments

Comments
 (0)