Merge pull request #50 from eman/improvement/diagnostics-and-docs

feat: enhance diagnostics, docs, and CLI tests

Author: eman

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.13', '3.14']
 
     steps:
       - uses: actions/checkout@v4

CHANGELOG.rst

@@ -2,10 +2,31 @@
 Changelog
 =========
 
-Version 6.2.0 (2025-12-17)
+Version 7.0.0 (2025-12-17)
 ==========================
 
-**BREAKING CHANGES**: Enumerations refactored for type safety and consistency
+**BREAKING CHANGES**: 
+- Minimum Python version raised to 3.13
+- Enumerations refactored for type safety and consistency
+
+Removed
+-------
+- **Python 3.9-3.12 Support**: Minimum Python version is now 3.13
+  
+  Home Assistant has deprecated Python 3.12 support, making Python 3.13 the de facto minimum for this ecosystem.
+  
+  Python 3.13 features and improvements:
+  
+  - **Experimental free-threaded mode** (PEP 703): Optional GIL removal for true parallelism
+  - **JIT compiler** (PEP 744): Just-in-time compilation for performance improvements
+  - **Better error messages**: Enhanced suggestions for NameError, AttributeError, and import errors
+  - **Type system enhancements**: TypeVars with defaults (PEP 696), @deprecated decorator (PEP 702), ReadOnly TypedDict (PEP 705)
+  - **Performance**: ~5-10% faster overall, optimized dictionary/set operations, better function calls
+  - PEP 695: New type parameter syntax for generics
+  - PEP 701: f-string improvements
+  - Built-in ``datetime.UTC`` constant
+  
+  If you need Python 3.12 support, use version 6.1.x of this library.
 
 - **CommandCode moved**: Import from ``nwp500.enums`` instead of ``nwp500.constants``
 
@@ -22,6 +43,13 @@ Version 6.2.0 (2025-12-17)
 Added
 -----
 
+- **Python 3.12+ Optimizations**: Leverage latest Python features
+  
+  - PEP 695: New type parameter syntax (``def func[T](...)`` instead of ``TypeVar``)
+  - Use ``datetime.UTC`` constant instead of ``datetime.timezone.utc``
+  - Native union syntax (``X | Y`` instead of ``Union[X, Y]``)
+  - Cleaner generic type annotations throughout codebase
+
 - **Enumerations Module (``src/nwp500/enums.py``)**: Comprehensive type-safe enums for device control and status
 
   - Status value enums: ``OnOffFlag``, ``Operation``, ``DhwOperationSetting``, ``CurrentOperationMode``, ``HeatSource``, ``DREvent``, ``WaterLevel``, ``FilterChange``, ``RecirculationMode``

README.rst

@@ -175,12 +175,10 @@ The library includes type-safe data models with automatic unit conversions:
 Requirements
 ============
 
-* Python 3.9+
+* Python 3.13+
 * aiohttp >= 3.8.0
-* websockets >= 10.0
-* cryptography >= 3.4.0
 * pydantic >= 2.0.0
-* awsiotsdk >= 1.21.0
+* awsiotsdk >= 1.27.0
 
 License
 =======

docs/development/history.rst

@@ -18,7 +18,7 @@ providing:
 - Automatic reconnection with exponential backoff
 - Command queuing for reliable communication
 - Historical energy usage data (EMS API)
-- Modern Python 3.9+ codebase with native type hints
+- Modern Python 3.13+ codebase with native type hints
 
 Current Status
 --------------
@@ -38,7 +38,7 @@ The library is feature-complete with:
 - Comprehensive documentation
 - Working examples for all features
 - Unit tests with good coverage
-- Python 3.9+ with modern type hints
+- Python 3.13+ with modern type hints
 
 Implementation Milestones
 -------------------------

docs/installation.rst

@@ -5,7 +5,7 @@ Installation
 Requirements
 ============
 
-* Python 3.9 or higher
+* Python 3.13 or higher
 * pip (Python package installer)
 * Navien Smart Control account
 
@@ -51,7 +51,7 @@ Core Dependencies
 The library requires:
 
 * ``aiohttp>=3.8.0`` - Async HTTP client for REST API
-* ``awsiotsdk>=1.20.0`` - AWS IoT SDK for MQTT
+* ``awsiotsdk>=1.27.0`` - AWS IoT SDK for MQTT
 * ``pydantic>=2.0.0`` - Data validation and models
 
 Optional Dependencies
@@ -128,7 +128,7 @@ The MQTT client requires the AWS IoT SDK:
 
 .. code-block:: bash
 
-   pip install awsiotsdk>=1.20.0
+   pip install awsiotsdk>=1.27.0
 
 Upgrading
 =========

docs/python_api/models.rst

@@ -292,7 +292,7 @@ Complete real-time device status with 100+ fields.
           # Water usage detection
           if status.dhw_use:
               print("Water usage detected (short-term)")
-          if status.dhw_useSustained:
+          if status.dhw_use_sustained:
               print("Water usage detected (sustained)")
 
           # Errors

docs/python_api/mqtt_client.rst

@@ -207,7 +207,7 @@ subscribe_device_status()
           print(f"Target: {status.dhw_temperature_setting}°F")
           print(f"Mode: {status.dhw_operation_setting.name}")
           print(f"Power: {status.current_inst_power}W")
-          print(f"Energy: {status.available_energy_capacity}%")
+          print(f"Energy: {status.dhw_charge_per}%")
           
           # Check if actively heating
           if status.operation_busy:
@@ -566,11 +566,15 @@ subscribe_energy_usage()
           print(f"Electric: {energy.total.heat_element_percentage:.1f}%")
           
           print("\nDaily Breakdown:")
-          for day_data in energy.data:
-              print(f"  Date: Day {len(energy.data)}")
-              print(f"    Total: {day_data.total_usage} Wh")
-              print(f"    HP: {day_data.hpUsage} Wh ({day_data.hpTime}h)")
-              print(f"    HE: {day_data.heUsage} Wh ({day_data.heTime}h)")
+          for monthly_data in energy.usage:
+              print(f"  Month: {monthly_data.year}-{monthly_data.month}")
+              for day_data in monthly_data.data:
+                  # Skip empty days (all zeros)
+                  if day_data.total_usage > 0:
+                      print(f"    Day {monthly_data.data.index(day_data) + 1}:")
+                      print(f"      Total: {day_data.total_usage} Wh")
+                      print(f"      HP: {day_data.heat_pump_usage} Wh ({day_data.heat_pump_time}h)")
+                      print(f"      HE: {day_data.heat_element_usage} Wh ({day_data.heat_element_time}h)")
       
       await mqtt.subscribe_energy_usage(device, on_energy)
       await mqtt.request_energy_usage(device, year=2024, months=[10])

docs/quickstart.rst

@@ -8,7 +8,7 @@ in just a few minutes.
 Prerequisites
 =============
 
-* Python 3.9 or higher
+* Python 3.13 or higher
 * Navien Smart Control account (via Navilink mobile app)
 * At least one Navien NWP500 device registered to your account
 * Valid email and password for your Navien account

examples/mask.py

@@ -7,15 +7,14 @@
 from __future__ import annotations
 
 import re
-from typing import Optional
 
 
-def mask_mac(mac: Optional[str]) -> str:
+def mask_mac(mac: str | None) -> str:
     """Always return fully redacted MAC address label, never expose partial values."""
     return "[REDACTED_MAC]"
 
 
-def mask_mac_in_topic(topic: str, mac_addr: Optional[str] = None) -> str:
+def mask_mac_in_topic(topic: str, mac_addr: str | None = None) -> str:
     """Return topic with any MAC-like substrings replaced.
 
     Also ensures a direct literal match of mac_addr is redacted.
@@ -33,7 +32,7 @@ def mask_mac_in_topic(topic: str, mac_addr: Optional[str] = None) -> str:
 __all__ = ["mask_mac", "mask_mac_in_topic"]
 
 
-def mask_any(value: Optional[str]) -> str:
+def mask_any(value: str | None) -> str:
     """Generic redaction for strings considered sensitive in examples.
 
     Always returns a short redaction tag; keep implementation simple so examples
@@ -51,7 +50,7 @@ def mask_any(value: Optional[str]) -> str:
         return "[REDACTED]"
 
 
-def mask_location(city: Optional[str], state: Optional[str]) -> str:
+def mask_location(city: str | None, state: str | None) -> str:
     """Redact location fields for examples.
 
     Returns a single redaction tag if either city or state are present.

pyproject.toml

@@ -11,7 +11,7 @@ version_scheme = "no-guess-dev"
 [tool.ruff]
 # Ruff configuration for code formatting and linting
 line-length = 80
-target-version = "py39"
+target-version = "py313"
 
 # Exclude directories
 exclude = [
@@ -99,7 +99,7 @@ line-ending = "auto"
 strict = true
 
 # Python version target
-python_version = "3.9"
+python_version = "3.13"
 
 # Module discovery
 files = ["src/nwp500", "tests"]