python-hotspring 1.3.0__tar.gz → 2.0.0__tar.gz

{python_hotspring-1.3.0 → python_hotspring-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hotspring
-Version: 1.3.0
+Version: 2.0.0
 Summary: Asynchronous Python client for Hot Spring Connected Spa Kit 2.
 License: MIT
 License-File: LICENSE

{python_hotspring-1.3.0 → python_hotspring-2.0.0}/pyproject.toml

@@ -22,7 +22,7 @@ packages = [
 ]
 readme = "README.md"
 repository = "https://github.com/Moustachauve/python-hotspring"
-version = "1.3.0"
+version = "2.0.0"
 
 [tool.poetry.dependencies]
 aiohttp = ">=3.0.0"

{python_hotspring-1.3.0 → python_hotspring-2.0.0}/src/hotspring/const.py

@@ -82,8 +82,7 @@ class LightColor(Enum):
     """
 
     UNKNOWN = "unknown"
-    OFF = "WHEEL_OFF"
-    ON = "WHEEL_ON"
+    CUSTOM = "CUSTOM"
     RED = "RED"
     BLUE = "BLUE"
     GREEN = "GREEN"
@@ -96,7 +95,7 @@ class LightColor(Enum):
     def build(cls, value: str | None) -> LightColor:
         """Parse a raw API string into a LightColor.
 
-        Case-insensitive matching (real API returns e.g. "BLUE").
+        Case-insensitive matching (real API returns e.g. "BLUE", "custom").
 
         Args:
         ----

{python_hotspring-1.3.0 → python_hotspring-2.0.0}/src/hotspring/hotspring.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 from dataclasses import dataclass
 from typing import Self
@@ -11,6 +12,12 @@ import aiohttp
 import backoff
 from yarl import URL
 
+from .const import (
+    HeatingMode,
+    JetSpeed,
+    LightColor,
+    LightWheelMode,
+)
 from .exceptions import (
     HotSpringCommandError,
     HotSpringConnectionError,
@@ -23,6 +30,7 @@ from .models import (
     Diagnostics,
     FreshWaterIQ,
     Spa,
+    SpaInfo,
 )
 
 
@@ -47,6 +55,7 @@ class HotSpring:
     session: aiohttp.ClientSession | None = None
     request_timeout: float = 10.0
     _close_session: bool = False
+    _identity_loaded: bool = False
     spa: Spa | None = None
 
     @backoff.on_exception(
@@ -144,55 +153,102 @@ class HotSpring:
 
         return response_data
 
-    async def update(self) -> Spa:
-        """Get all spa information in a single polling cycle.
+    async def _safe_request(self, uri: str) -> dict[str, object] | None:
+        """Fetch an endpoint, returning None on error."""
+        with contextlib.suppress(HotSpringError):
+            return await self.request(uri)
+        return None
 
-        This method fetches the main /status endpoint and combines it with
-        identity information from /startup and /spamodel. Use this for
-        the primary 15-second polling cycle.
+    async def update(self, *, refresh_identity: bool = False) -> Spa:
+        """Get all spa information.
 
-        Returns
+        On the initial call (or when `refresh_identity=True`), this method fetches
+        the main /status endpoint concurrently with /startup, /spaConnectStatus,
+        and /spamodel.
+
+        On subsequent routine polling cycles, it only queries the fast /status
+        endpoint, avoiding redundant radio (LoRA) queries for static identity data.
+
+        Args:
+        ----
+            refresh_identity: Force re-fetching static identity from /startup
+                and /spamodel.
+
+        Returns:
         -------
             The updated Spa data object.
 
-        Raises
+        Raises:
         ------
             HotSpringError: If no data is returned from the spa.
 
         """
-        # Fetch main status
+        if not self._identity_loaded or refresh_identity:
+            status_res, startup_res, connect_res, model_res = await asyncio.gather(
+                self.request("/status"),
+                self._safe_request("/startup"),
+                self._safe_request("/spaConnectStatus"),
+                self._safe_request("/spamodel"),
+            )
+
+            if self.spa is None:
+                self.spa = Spa(status_res)
+            else:
+                self.spa.update_from_dict(status_res)
+
+            if startup_res:
+                self.spa.update_info(startup_res)
+
+            if model_res:
+                self.spa.update_info(model_res)
+
+            if connect_res:
+                self.spa.update_connection_status(connect_res)
+
+            self._identity_loaded = True
+            return self.spa
+
         status_data = await self.request("/status")
 
-        if self.spa is None:
+        if self.spa is None:  # Safety guard; spa is always set after cold sync
             self.spa = Spa(status_data)
         else:
             self.spa.update_from_dict(status_data)
 
-        # Fetch identity/startup info
-        identity_data: dict[str, object] = {}
-        try:
-            startup_data = await self.request("/startup")
-            identity_data.update(startup_data)
-        except HotSpringError:
-            pass
+        return self.spa
 
-        try:
-            model_data = await self.request("/spamodel")
-            identity_data.update(model_data)
-        except HotSpringError:
-            pass
+    async def update_identity(self) -> SpaInfo:
+        """Fetch and update static spa identity info (/startup and /spamodel).
+
+        Returns
+        -------
+            The updated SpaInfo data.
+
+        Raises
+        ------
+            HotSpringError: If the spa has not been initialized with update().
+
+        """
+        if self.spa is None:
+            msg = "Call update() before update_identity()"
+            raise HotSpringError(msg)
+
+        startup_res, model_res = await asyncio.gather(
+            self._safe_request("/startup"),
+            self._safe_request("/spamodel"),
+        )
+
+        identity_data: dict[str, object] = {}
+        if startup_res:
+            identity_data.update(startup_res)
+        if model_res:
+            identity_data.update(model_res)
 
         if identity_data:
             self.spa.update_info(identity_data)
 
-        # Fetch connection status
-        try:
-            connect_data = await self.request("/spaConnectStatus")
-            self.spa.update_connection_status(connect_data)
-        except HotSpringError:
-            pass  # Non-critical
-
-        return self.spa
+        self._identity_loaded = True
+        return self.spa.info
 
     async def update_water_care(self) -> FreshWaterIQ:
         """Update FreshWater IQ water quality data.
@@ -292,7 +348,11 @@ class HotSpring:
             raise HotSpringNotReadyError(msg)
 
         try:
-            await self.request("/spaManager", method="POST", data=payload)
+            response_data = await self.request(
+                "/spaManager", method="POST", data=payload
+            )
+            if self.spa is not None:
+                self.spa.update_from_dict(response_data)
         except HotSpringError as exception:
             msg = f"Command failed: {payload}"
             raise HotSpringCommandError(msg) from exception
@@ -310,57 +370,53 @@ class HotSpring:
             {"heater": {"control": {"temperatureABS": str(temperature)}}}
         )
 
-    async def set_heating_mode(self, mode: str) -> None:
+    async def set_heating_mode(self, mode: str | HeatingMode) -> None:
         """Set the heating mode.
 
         Args:
         ----
-            mode: The heating mode value. Use HeatingMode enum values,
-                e.g. ``HeatingMode.HEAT_WITH_BOOST.value``.
+            mode: The heating mode value. Use HeatingMode enum values or string,
+                e.g. ``HeatingMode.HEAT_WITH_BOOST.value`` or ``"heatWithBoost"``.
 
         """
-        await self._send_command({"heater": {"control": {"heatingMode": mode}}})
+        mode_val = mode.value if isinstance(mode, HeatingMode) else str(mode)
+        await self._send_command({"heater": {"control": {"heatingMode": mode_val}}})
 
-    async def set_jet(self, jet: int, speed: str) -> None:
+    async def set_jet(self, jet: int, speed: str | JetSpeed) -> None:
         """Set the speed of a jet pump.
 
         Args:
         ----
             jet: The jet number (1-based).
-            speed: The speed value. Use JetSpeed enum values,
-                e.g. ``JetSpeed.HIGH_SPEED.value``.
+            speed: The speed value. Use JetSpeed enum values or string,
+                e.g. ``JetSpeed.HIGH_SPEED.value`` or ``"highSpeed"``.
 
         """
-        await self._send_command({"JET": {f"JET{jet}": {"control": speed}}})
+        speed_val = speed.value if isinstance(speed, JetSpeed) else str(speed)
+        await self._send_command({"JET": {f"JET{jet}": {"control": speed_val}}})
 
     async def set_light_color(
         self,
         zone: int,
-        color: str,
-        intensity: int = 5,
-        light_wheel: str = "off",
+        color: str | LightColor,
     ) -> None:
         """Set the color of a light zone.
 
         Args:
         ----
             zone: The light zone number (1-based).
-            color: The color value. Use LightColor enum values,
-                e.g. ``LightColor.BLUE.value``.
-            intensity: The brightness intensity (0-5). Defaults to 5.
-            light_wheel: The light wheel mode. Use LightWheelMode enum values,
-                e.g. ``LightWheelMode.OFF.value``. Defaults to "off".
+            color: The color value. Use LightColor enum values or string,
+                e.g. ``LightColor.BLUE.value`` or ``"BLUE"``.
 
         """
+        color_val = color.value if isinstance(color, LightColor) else str(color)
         await self._send_command(
             {
                 "lights": {
                     "control": {
                         f"Zone{zone}": {
                             "control": {
-                                "color": color.upper(),
-                                "IntensityAbs": intensity,
-                                "lightWheel": light_wheel,
+                                "color": color_val.upper(),
                             }
                         }
                     }
@@ -390,23 +446,60 @@ class HotSpring:
             }
         )
 
-    async def set_light_brightness(self, zone: int, *, full: bool = True) -> None:
-        """Set the brightness of a light zone.
+    async def set_light_brightness(self, zone: int, brightness: int) -> None:
+        """Set the brightness intensity of a light zone (0-5).
 
         Args:
         ----
             zone: The light zone number (1-based).
-            full: True to set to full brightness ("fullon"), False to turn off ("off").
+            brightness: The brightness level (0 = off, 1 = lowest, 5 = maximum).
+
+        Raises:
+        ------
+            ValueError: If brightness is not an integer between 0 and 5.
 
         """
-        intensity = "fullon" if full else "off"
+        if not 0 <= brightness <= 5:
+            msg = f"Brightness must be between 0 and 5, got {brightness}"
+            raise ValueError(msg)
+
         await self._send_command(
             {
                 "lights": {
                     "control": {
                         f"Zone{zone}": {
                             "control": {
-                                "Intensity": intensity,
+                                "IntensityAbs": brightness,
+                            }
+                        }
+                    }
+                }
+            }
+        )
+
+    async def set_light_wheel(
+        self,
+        zone: int,
+        mode: str | LightWheelMode = LightWheelMode.ON,
+    ) -> None:
+        """Set the light wheel (color cycle / rainbow loop) mode for a light zone.
+
+        Args:
+        ----
+            zone: The light zone number (1-based).
+            mode: The light wheel mode. Use LightWheelMode enum values or string,
+                e.g. ``LightWheelMode.ON.value``, ``"loopUp"``,
+                ``"loopDown"``, or ``"off"``. Defaults to LightWheelMode.ON.
+
+        """
+        mode_val = mode.value if isinstance(mode, LightWheelMode) else str(mode)
+        await self._send_command(
+            {
+                "lights": {
+                    "control": {
+                        f"Zone{zone}": {
+                            "control": {
+                                "lightWheel": mode_val,
                             }
                         }
                     }
@@ -430,7 +523,19 @@ class HotSpring:
             green: Green value (0-255).
             blue: Blue value (0-255).
 
+        Raises:
+        ------
+            ValueError: If any RGB component is not between 0 and 255.
+
         """
+        for component in (red, green, blue):
+            if not 0 <= component <= 255:
+                msg = (
+                    f"RGB values must be between 0 and 255, "
+                    f"got ({red}, {green}, {blue})"
+                )
+                raise ValueError(msg)
+
         await self._send_command(
             {
                 "lights": {