nwp500-python 8.1.2__py3-none-any.whl → 9.0.0__py3-none-any.whl

nwp500/__init__.py

@@ -4,8 +4,6 @@ This package provides Python bindings for Navien Smart Control API and MQTT
 communication for NWP500 heat pump water heaters.
 """
 
-from __future__ import annotations
-
 from importlib.metadata import (
     PackageNotFoundError,
     version,
@@ -32,25 +30,6 @@ from nwp500.auth import (
     authenticate,
     refresh_access_token,
 )
-from nwp500.command_decorators import (
-    requires_capability,
-)
-from nwp500.device_capabilities import (
-    MqttDeviceCapabilityChecker,
-)
-from nwp500.device_info_cache import (
-    MqttDeviceInfoCache,
-)
-from nwp500.encoding import (
-    build_reservation_entry,
-    build_tou_period,
-    decode_price,
-    decode_season_bitfield,
-    decode_week_bitfield,
-    encode_price,
-    encode_season_bitfield,
-    encode_week_bitfield,
-)
 from nwp500.enums import (
     CommandCode,
     CurrentOperationMode,
@@ -79,20 +58,15 @@ from nwp500.exceptions import (
     AuthenticationError,
     DeviceCapabilityError,
     DeviceError,
-    DeviceNotFoundError,
-    DeviceOfflineError,
-    DeviceOperationError,
     InvalidCredentialsError,
     MqttConnectionError,
     MqttCredentialsError,
     MqttError,
     MqttNotConnectedError,
     MqttPublishError,
-    MqttSubscriptionError,
     Nwp500Error,
     ParameterValidationError,
     RangeValidationError,
-    TokenExpiredError,
     TokenRefreshError,
     ValidationError,
 )
@@ -154,17 +128,11 @@ from nwp500.unit_system import (
     reset_unit_system,
     set_unit_system,
 )
-from nwp500.utils import (
-    log_performance,
-)
 
 __all__ = [
     "__version__",
-    # Device Capabilities & Caching
-    "MqttDeviceCapabilityChecker",
+    # Device Capabilities
     "DeviceCapabilityError",
-    "MqttDeviceInfoCache",
-    "requires_capability",
     # Factory functions
     "create_navien_clients",
     # Models
@@ -225,22 +193,17 @@ __all__ = [
     "Nwp500Error",
     "AuthenticationError",
     "InvalidCredentialsError",
-    "TokenExpiredError",
     "TokenRefreshError",
     "APIError",
     "MqttError",
     "MqttConnectionError",
     "MqttNotConnectedError",
     "MqttPublishError",
-    "MqttSubscriptionError",
     "MqttCredentialsError",
     "ValidationError",
     "ParameterValidationError",
     "RangeValidationError",
     "DeviceError",
-    "DeviceNotFoundError",
-    "DeviceOfflineError",
-    "DeviceOperationError",
     # API Client
     "NavienAPIClient",
     # OpenEI Client
@@ -262,17 +225,6 @@ __all__ = [
     "EventEmitter",
     "EventListener",
     "MqttClientEvents",
-    # Encoding utilities
-    "encode_week_bitfield",
-    "decode_week_bitfield",
-    "encode_season_bitfield",
-    "decode_season_bitfield",
-    "encode_price",
-    "decode_price",
-    "build_reservation_entry",
-    "build_tou_period",
-    # Utilities
-    "log_performance",
     # Unit system management
     "set_unit_system",
     "get_unit_system",

nwp500/_base.py

@@ -5,8 +5,6 @@ enum serialization) so that both the authentication models and the device
 protocol models share a single base class.
 """
 
-from __future__ import annotations
-
 from typing import Any
 
 from pydantic import BaseModel, ConfigDict
@@ -39,6 +37,17 @@ class NavienBaseModel(BaseModel):
         converted: dict[str, Any] = self._convert_enums_to_names(result)
         return converted
 
+    def to_protocol_dict(self) -> dict[str, Any]:
+        """Dump only the declared protocol fields, by alias.
+
+        Excludes pydantic ``computed_field`` properties, which are
+        display-oriented (formatted times, weekday names, unit-converted
+        temperatures) and must never be sent to the device.
+        """
+        return self.model_dump(
+            by_alias=True, include=set(type(self).model_fields)
+        )
+
     @staticmethod
     def _convert_enums_to_names(
         data: Any, visited: set[int] | None = None

nwp500/api_client.py

@@ -4,10 +4,8 @@ Client for interacting with the Navien NWP500 API.
 This module provides an async HTTP client for device management and control.
 """
 
-from __future__ import annotations
-
 import logging
-from typing import Any, Self, cast
+from typing import Any, Self
 
 import aiohttp
 
@@ -79,9 +77,13 @@ class NavienAPIClient:
         self.base_url = base_url.rstrip("/")
         self._auth_client = auth_client
         self._unit_system = unit_system
-        self._session = session or auth_client.session
+        # An explicitly provided session always wins; otherwise the auth
+        # client's session is resolved per request (never cached) so the
+        # API client keeps working if the auth client recreates its
+        # session.
+        self._session_override = session
 
-        if self._session is None:
+        if self._session_override is None and auth_client.session is None:
             raise ValueError(
                 "auth_client must have an active session or a session "
                 "must be provided"
@@ -89,6 +91,11 @@ class NavienAPIClient:
         self._owned_session = False
         self._owned_auth = False
 
+    @property
+    def _session(self) -> aiohttp.ClientSession | None:
+        """The session used for requests, resolved dynamically."""
+        return self._session_override or self._auth_client.session
+
     async def __aenter__(self) -> Self:
         """Enter async context manager."""
         return self
@@ -152,7 +159,12 @@ class NavienAPIClient:
 
         try:
             _logger.debug(f"Starting {method} request to {url}")
-            session = cast(aiohttp.ClientSession, self._session)
+            session = self._session
+            if session is None:
+                raise APIError(
+                    "No active session available. The auth client session "
+                    "has been closed."
+                )
             async with session.request(
                 method,
                 url,
@@ -217,7 +229,7 @@ class NavienAPIClient:
 
         except aiohttp.ClientError as e:
             _logger.error(f"Network error: {e}")
-            raise APIError(f"Network error: {str(e)}") from e
+            raise APIError(f"Network error: {e!s}") from e
 
     # Device Management Endpoints
 

nwp500/auth.py

@@ -11,11 +11,12 @@ The API uses JWT (JSON Web Tokens) for authentication with the following flow:
 4. Refresh tokens when accessToken expires
 """
 
-from __future__ import annotations
-
+import asyncio
 import json
 import logging
 from datetime import UTC, datetime, timedelta
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
 from typing import Any, Self, cast
 
 import aiohttp
@@ -26,7 +27,6 @@ from pydantic import (
     model_validator,
 )
 
-from . import __version__
 from ._base import NavienBaseModel
 from .config import API_BASE_URL, REFRESH_ENDPOINT, SIGN_IN_ENDPOINT
 from .exceptions import (
@@ -36,6 +36,15 @@ from .exceptions import (
 )
 from .unit_system import UnitSystemType
 
+# Resolve the package version directly from distribution metadata instead
+# of importing it from the package __init__ (which imports this module,
+# making `from . import __version__` an order-dependent near-circular
+# import).
+try:
+    __version__ = _dist_version("nwp500-python")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+
 __author__ = "Emmanuel Levijarvi"
 __copyright__ = "Emmanuel Levijarvi"
 __license__ = "MIT"
@@ -328,6 +337,12 @@ class NavienAuthClient:
         self._auth_response: AuthenticationResponse | None = None
         self._user_email: str | None = None
 
+        # Serializes token refresh / re-authentication so concurrent
+        # callers (API 401 retry, MQTT reconnect, periodic requests)
+        # cannot stampede the refresh endpoint and invalidate each
+        # other's tokens.
+        self._refresh_lock = asyncio.Lock()
+
         # Restore tokens if provided
         if stored_tokens:
             # Create a minimal AuthenticationResponse with stored tokens
@@ -339,27 +354,53 @@ class NavienAuthClient:
             self._user_email = user_id
 
     async def __aenter__(self) -> Self:
-        """Async context manager entry."""
-        if self._owned_session:
+        """Async context manager entry.
+
+        Idempotent with respect to session creation: entering an
+        already-entered client reuses the existing session instead of
+        creating (and orphaning) a new one.
+
+        If authentication fails, the owned session is closed before the
+        exception propagates, because ``__aexit__`` is never called when
+        ``__aenter__`` raises.
+        """
+        if self._owned_session and self._session is None:
             self._session = self._create_session()
 
-        # Check if we have valid stored tokens
-        if self._auth_response and self._auth_response.tokens:
-            tokens = self._auth_response.tokens
-            # If tokens are expired, refresh or re-authenticate
-            if tokens.are_aws_credentials_expired:
-                _logger.info(
-                    "Stored AWS credentials expired, re-authenticating..."
-                )
-                await self.sign_in(self._user_id, self._password)
-            elif tokens.is_expired:
-                _logger.info("Stored JWT token expired, refreshing...")
-                await self.refresh_token(tokens.refresh_token)
+        try:
+            # Check if we have valid stored tokens
+            if self._auth_response and self._auth_response.tokens:
+                tokens = self._auth_response.tokens
+                # If tokens are expired, refresh or re-authenticate
+                if tokens.are_aws_credentials_expired:
+                    _logger.info(
+                        "Stored AWS credentials expired, re-authenticating..."
+                    )
+                    await self.sign_in(self._user_id, self._password)
+                elif tokens.is_expired:
+                    _logger.info("Stored JWT token expired, refreshing...")
+                    try:
+                        await self.refresh_token(tokens.refresh_token)
+                    except TokenRefreshError as e:
+                        if not self.has_stored_credentials:
+                            raise
+                        _logger.warning(
+                            "Stored token refresh failed: %s. Falling back "
+                            "to full sign-in...",
+                            e,
+                        )
+                        await self.sign_in(self._user_id, self._password)
+                else:
+                    _logger.info("Using stored tokens, skipping authentication")
             else:
-                _logger.info("Using stored tokens, skipping authentication")
-        else:
-            # No stored tokens, perform full authentication
-            await self.sign_in(self._user_id, self._password)
+                # No stored tokens, perform full authentication
+                await self.sign_in(self._user_id, self._password)
+        except BaseException:
+            # __aexit__ won't run; don't leak the owned session.
+            if self._owned_session and self._session:
+                await self._session.close()
+                self._session = None
+            raise
 
         return self
 
@@ -367,6 +408,7 @@ class NavienAuthClient:
         """Async context manager exit."""
         if self._owned_session and self._session:
             await self._session.close()
+            self._session = None
 
     def _create_session(self) -> aiohttp.ClientSession:
         """Create an aiohttp ClientSession with ThreadedResolver.
@@ -462,14 +504,12 @@ class NavienAuthClient:
         except aiohttp.ClientError as e:
             _logger.error(f"Network error during sign-in: {e}")
             raise AuthenticationError(
-                f"Network error: {str(e)}",
+                f"Network error: {e!s}",
                 retriable=True,
             ) from e
         except (KeyError, ValueError, json.JSONDecodeError) as e:
             _logger.error(f"Failed to parse authentication response: {e}")
-            raise AuthenticationError(
-                f"Invalid response format: {str(e)}"
-            ) from e
+            raise AuthenticationError(f"Invalid response format: {e!s}") from e
 
     async def refresh_token(
         self, refresh_token: str | None = None
@@ -477,6 +517,11 @@ class NavienAuthClient:
         """
         Refresh access token using refresh token.
 
+        Refreshes are serialized: if another task is already refreshing,
+        this call waits for it and — when no explicit ``refresh_token``
+        was given and the stored tokens are now valid — returns the
+        already-refreshed tokens instead of issuing a duplicate request.
+
         Args:
             refresh_token: The refresh token obtained from sign-in.
                 If not provided, uses the stored refresh token.
@@ -487,6 +532,25 @@ class NavienAuthClient:
         Raises:
             TokenRefreshError: If token refresh fails or no token available
         """
+        async with self._refresh_lock:
+            current = self.current_tokens
+            # Another task may have refreshed while we waited for the
+            # lock; don't hit the endpoint again with valid tokens. An
+            # explicit refresh_token equal to the stored one is a forced
+            # refresh and proceeds; a differing one is stale (rotated by
+            # the concurrent refresh) and would be rejected anyway.
+            if (
+                current
+                and not current.is_expired
+                and refresh_token != current.refresh_token
+            ):
+                return current
+            return await self._refresh_token_unlocked(refresh_token)
+
+    async def _refresh_token_unlocked(
+        self, refresh_token: str | None = None
+    ) -> AuthTokens:
+        """Perform the actual token refresh. Caller must hold _refresh_lock."""
         if refresh_token is None:
             if self._auth_response and self._auth_response.tokens.refresh_token:
                 refresh_token = self._auth_response.tokens.refresh_token
@@ -521,10 +585,20 @@ class NavienAuthClient:
                 data = response_data.get("data", {})
                 new_tokens = AuthTokens.model_validate(data)
 
-                # Preserve AWS credentials from old tokens if not in refresh
-                # response
+                # Preserve fields the refresh response may omit. The
+                # refresh endpoint does not return AWS credentials, and it
+                # may not echo the refresh token itself — without this,
+                # new_tokens.refresh_token would be "" and every
+                # subsequent refresh would fail.
                 if self._auth_response and self._auth_response.tokens:
                     old_tokens = self._auth_response.tokens
+                    if (
+                        not new_tokens.refresh_token
+                        and old_tokens.refresh_token
+                    ):
+                        new_tokens.refresh_token = old_tokens.refresh_token
+                    if not new_tokens.id_token and old_tokens.id_token:
+                        new_tokens.id_token = old_tokens.id_token
                     if (
                         not new_tokens.access_key_id
                         and old_tokens.access_key_id
@@ -563,12 +637,12 @@ class NavienAuthClient:
         except aiohttp.ClientError as e:
             _logger.error(f"Network error during token refresh: {e}")
             raise TokenRefreshError(
-                f"Network error: {str(e)}",
+                f"Network error: {e!s}",
                 retriable=True,
             ) from e
         except (KeyError, ValueError, json.JSONDecodeError) as e:
             _logger.error(f"Failed to parse refresh response: {e}")
-            raise TokenRefreshError(f"Invalid response format: {str(e)}") from e
+            raise TokenRefreshError(f"Invalid response format: {e!s}") from e
 
     async def re_authenticate(self) -> AuthenticationResponse:
         """
@@ -621,15 +695,28 @@ class NavienAuthClient:
 
         # Check if AWS credentials have expired
         if tokens.are_aws_credentials_expired:
-            _logger.info("AWS credentials expired, re-authenticating...")
-            # Re-authenticate to get fresh AWS credentials
-            await self.sign_in(self._user_id, self._password)
-            return self._auth_response.tokens if self._auth_response else None
+            async with self._refresh_lock:
+                # Re-check after acquiring the lock: another task may have
+                # re-authenticated while we waited.
+                if not self._auth_response:
+                    return None
+                tokens = self._auth_response.tokens
+                if tokens.are_aws_credentials_expired:
+                    _logger.info(
+                        "AWS credentials expired, re-authenticating..."
+                    )
+                    # Re-authenticate to get fresh AWS credentials
+                    await self.sign_in(self._user_id, self._password)
+                return (
+                    self._auth_response.tokens if self._auth_response else None
+                )
 
-        # Check if JWT token has expired
+        # Check if JWT token has expired. refresh_token() serializes
+        # concurrent refreshes and returns the already-refreshed tokens
+        # to callers that lost the race.
         if tokens.is_expired:
             _logger.info("Token expired, refreshing...")
-            return await self.refresh_token(tokens.refresh_token)
+            return await self.refresh_token()
 
         return tokens
 
@@ -779,8 +866,9 @@ async def refresh_access_token(refresh_token: str) -> AuthTokens:
     # Use ThreadedResolver for reliable DNS in containerized environments
     resolver = aiohttp.ThreadedResolver()
     connector = aiohttp.TCPConnector(resolver=resolver)
+    timeout = aiohttp.ClientTimeout(total=30)
     async with (
-        aiohttp.ClientSession(connector=connector) as session,
+        aiohttp.ClientSession(connector=connector, timeout=timeout) as session,
         session.post(url, json=payload) as response,
     ):
         response_data = await response.json()

nwp500/cli/__init__.py

@@ -1,7 +1,5 @@
 """CLI package for nwp500-python."""
 
-from __future__ import annotations
-
 from .__main__ import run
 from .handlers import (
     handle_device_info_request,

nwp500/cli/__main__.py

@@ -1,7 +1,5 @@
 """Navien Water Heater Control CLI - Main Entry Point."""
 
-from __future__ import annotations
-
 import asyncio
 import functools
 import logging
@@ -88,6 +86,10 @@ def async_command(f: Any) -> Any:
 
             # Load cached tokens if available
             tokens, cached_email = load_tokens()
+            # Cached tokens belong to cached_email; never reuse them for a
+            # different account.
+            if email and cached_email and email != cached_email:
+                tokens = None
             # If email not provided in args, try cached email
             email = email or cached_email
 
@@ -162,7 +164,9 @@ def async_command(f: Any) -> Any:
                 _formatter.print_error(str(e), title="Unexpected Error")
             return 1
 
-        return asyncio.run(runner())
+        # click ignores callback return values in standalone mode, so
+        # propagate failures via ctx.exit to get a non-zero exit code.
+        ctx.exit(asyncio.run(runner()))
 
     return wrapper
 
@@ -288,12 +292,10 @@ async def power(mqtt: NavienMqttClient, device: Any, state: str) -> None:
     "mode_name",
     type=click.Choice(
         [
-            "standby",
             "heat-pump",
             "electric",
             "energy-saver",
             "high-demand",
-            "vacation",
         ],
         case_sensitive=False,
     ),

nwp500/cli/handlers.py

@@ -1,7 +1,5 @@
 """Command handlers for CLI operations."""
 
-from __future__ import annotations
-
 import asyncio
 import json
 import logging
@@ -220,13 +218,13 @@ async def handle_set_mode_request(
     mqtt: NavienMqttClient, device: Device, mode_name: str
 ) -> None:
     """Set device operation mode."""
+    # Vacation mode (5) requires a day count and has its own `vacation`
+    # command; power-off (6) is handled by the `power` command.
     mode_mapping = {
-        "standby": 0,
         "heat-pump": 1,
         "electric": 2,
         "energy-saver": 3,
         "high-demand": 4,
-        "vacation": 5,
     }
     mode_id = mode_mapping.get(mode_name.lower())
     if mode_id is None:

nwp500/cli/monitoring.py

@@ -1,7 +1,5 @@
 """Monitoring and periodic status polling."""
 
-from __future__ import annotations
-
 import asyncio
 import logging
 

nwp500/cli/output_formatters.py

@@ -1,7 +1,5 @@
 """Output formatting utilities for CLI (CSV, JSON)."""
 
-from __future__ import annotations
-
 import csv
 import json
 import logging
@@ -369,13 +367,14 @@ def write_status_to_csv(file_path: str, status: DeviceStatus) -> None:
         # Convert status to dict (enums are already converted to names)
         status_dict = status.model_dump()
 
-        # Add a timestamp to the beginning of the data
-        status_dict["timestamp"] = datetime.now().isoformat()
+        # Add a timestamp to the beginning of the data (timezone-aware,
+        # in the local timezone)
+        status_dict["timestamp"] = datetime.now().astimezone().isoformat()
 
         # Check if file exists to determine if we need to write the header
         file_exists = Path(file_path).exists()
 
-        with open(file_path, "a", newline="") as csvfile:
+        with Path(file_path).open("a", newline="") as csvfile:
             # Get the field names from the dict keys
             fieldnames = list(status_dict.keys())
             writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
@@ -897,13 +896,6 @@ def print_device_status(device_status: Any) -> None:
             )
         )
 
-    # Calculate widths dynamically
-    max_label_len = max((len(label) for _, label, _ in all_items), default=20)
-    max_value_len = max(
-        (len(str(value)) for _, _, value in all_items), default=20
-    )
-    _line_width = max_label_len + max_value_len + 4  # +4 for padding
-
     # Use rich formatter for output
     formatter = get_formatter()
     formatter.print_status_table(all_items)
@@ -1109,13 +1101,6 @@ def print_device_info(device_feature: Any) -> None:
             status = "Yes" if value else "No"
             all_items.append(("SUPPORTED FEATURES", label, status))
 
-    # Calculate widths dynamically
-    max_label_len = max((len(label) for _, label, _ in all_items), default=20)
-    max_value_len = max(
-        (len(str(value)) for _, _, value in all_items), default=20
-    )
-    _line_width = max_label_len + max_value_len + 4  # +4 for padding
-
     # Use rich formatter for output
     formatter = get_formatter()
     formatter.print_status_table(all_items)

nwp500/cli/rich_output.py

@@ -1,7 +1,6 @@
 """Rich-enhanced output formatting with graceful fallback."""
 
-from __future__ import annotations
-
+import itertools
 import json
 import logging
 import os
@@ -142,7 +141,7 @@ def _collapse_ranges(
 
     # Build groups of consecutive items
     groups: list[list[Any]] = [[items[0]]]
-    for prev, curr in zip(items, items[1:], strict=False):
+    for prev, curr in itertools.pairwise(items):
         if isinstance(prev, int):
             consecutive = (curr - prev) == 1 or (
                 prev == cycle_size and curr == 1

nwp500/cli/token_storage.py

@@ -1,9 +1,8 @@
 """Token storage and management for CLI authentication."""
 
-from __future__ import annotations
-
 import json
 import logging
+import os
 from pathlib import Path
 
 from nwp500.auth import AuthTokens
@@ -22,7 +21,11 @@ def save_tokens(tokens: AuthTokens, email: str) -> None:
         email: User email address
     """
     try:
-        with open(TOKEN_FILE, "w") as f:
+        # Tokens grant account access; keep the file owner-readable only.
+        # O_CREAT mode only applies to new files, so chmod existing ones.
+        fd = os.open(TOKEN_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            TOKEN_FILE.chmod(0o600)
             # Use the built-in to_dict() method for serialization
             token_data = tokens.to_dict()
             token_data["email"] = email
@@ -42,7 +45,7 @@ def load_tokens() -> tuple[AuthTokens | None, str | None]:
     if not TOKEN_FILE.exists():
         return None, None
     try:
-        with open(TOKEN_FILE) as f:
+        with TOKEN_FILE.open() as f:
             data = json.load(f)
             email = data.get("email")
             if not email:

nwp500/command_decorators.py

@@ -4,8 +4,6 @@ This module provides decorators that automatically validate device capabilities
 before command execution, preventing unsupported commands from being sent.
 """
 
-from __future__ import annotations
-
 import functools
 import inspect
 import logging
@@ -84,7 +82,7 @@ def requires_capability(feature: str) -> Callable[[F], F]:
                     # Wrap other errors (timeouts, connection issues, etc)
                     raise DeviceCapabilityError(
                         feature,
-                        f"Cannot execute {func.__name__}: {str(e)}",
+                        f"Cannot execute {func.__name__}: {e!s}",
                     ) from e
 
                 if cached_features is None: