python-hotspring 2.0.1__py3-none-any.whl → 3.0.0__py3-none-any.whl

hotspring/__init__.py

@@ -2,8 +2,11 @@
 
 from .const import (
     BrightnessLevel,
+    DeviceType,
+    EnergySavingMode,
     HeatingMode,
     JetSpeed,
+    JetSpeedType,
     LightColor,
     LightWheelMode,
     SpaBrand,
@@ -15,7 +18,9 @@ from .exceptions import (
     HotSpringConnectionError,
     HotSpringConnectionTimeoutError,
     HotSpringError,
+    HotSpringInvalidDeviceError,
     HotSpringNotReadyError,
+    HotSpringSNADetectedError,
 )
 from .hotspring import HotSpring
 from .models import (
@@ -32,6 +37,7 @@ from .models import (
     Spa,
     SpaInfo,
     SpaLock,
+    SpaTestData,
     Versions,
     WaterCare,
 )
@@ -41,8 +47,10 @@ __all__ = [
     "BrightnessLevel",
     "CleanCycle",
     "ConnectionStatus",
+    "DeviceType",
     "Diagnostics",
     "EnergySaving",
+    "EnergySavingMode",
     "FreshWaterIQ",
     "Heater",
     "HeatingMode",
@@ -51,9 +59,12 @@ __all__ = [
     "HotSpringConnectionError",
     "HotSpringConnectionTimeoutError",
     "HotSpringError",
+    "HotSpringInvalidDeviceError",
     "HotSpringNotReadyError",
+    "HotSpringSNADetectedError",
     "Jet",
     "JetSpeed",
+    "JetSpeedType",
     "LightColor",
     "LightWheelMode",
     "LightZone",
@@ -63,6 +74,7 @@ __all__ = [
     "SpaFailureState",
     "SpaInfo",
     "SpaLock",
+    "SpaTestData",
     "TemperatureUnit",
     "Versions",
     "WaterCare",

hotspring/const.py

@@ -75,6 +75,35 @@ class JetSpeed(Enum):
 _JET_SPEED_MAP: dict[str, JetSpeed] = {s.value: s for s in JetSpeed}
 
 
+class JetSpeedType(Enum):
+    """Configured speed capability of a jet pump."""
+
+    UNKNOWN = "unknown"
+    SINGLE_SPEED = "singleSpeed"
+    DUAL_SPEED = "dualSpeed"
+
+    @classmethod
+    def build(cls, value: str | None) -> JetSpeedType:
+        """Parse a raw API string into a JetSpeedType.
+
+        Args:
+        ----
+            value: The raw speed configuration string from the API, or None.
+
+        Returns:
+        -------
+            The matching JetSpeedType, or JetSpeedType.UNKNOWN for
+            unrecognized values.
+
+        """
+        if value is None:
+            return cls.UNKNOWN
+        return _JET_SPEED_TYPE_MAP.get(value, cls.UNKNOWN)
+
+
+_JET_SPEED_TYPE_MAP: dict[str, JetSpeedType] = {t.value: t for t in JetSpeedType}
+
+
 class LightColor(Enum):
     """Color setting for a spa light zone.
 
@@ -153,12 +182,13 @@ class BrightnessLevel(Enum):
     """
 
     UNKNOWN = "unknown"
+    AUTO = "auto"
     LEVEL_1 = "brightness_level_1"
     LEVEL_2 = "brightness_level_2"
     LEVEL_3 = "brightness_level_3"
 
     @classmethod
-    def build(cls, value: str | None) -> BrightnessLevel:
+    def build(cls, value: str | int | None) -> BrightnessLevel:
         """Parse a raw API string into a BrightnessLevel.
 
         Args:
@@ -173,10 +203,49 @@ class BrightnessLevel(Enum):
         """
         if value is None:
             return cls.UNKNOWN
-        return _BRIGHTNESS_MAP.get(value, cls.UNKNOWN)
+        val_str = str(value).strip().lower()
+        return _BRIGHTNESS_MAP.get(val_str, cls.UNKNOWN)
 
 
 _BRIGHTNESS_MAP: dict[str, BrightnessLevel] = {b.value: b for b in BrightnessLevel}
+_BRIGHTNESS_MAP.update(
+    {
+        "1": BrightnessLevel.LEVEL_1,
+        "2": BrightnessLevel.LEVEL_2,
+        "3": BrightnessLevel.LEVEL_3,
+        "auto": BrightnessLevel.AUTO,
+    }
+)
+
+_BRIGHTNESS_TO_WIRE: dict[BrightnessLevel, str] = {
+    BrightnessLevel.LEVEL_1: "1",
+    BrightnessLevel.LEVEL_2: "2",
+    BrightnessLevel.LEVEL_3: "3",
+    BrightnessLevel.AUTO: "auto",
+}
+
+MAX_ENERGY_SAVING_SCHEDULES = 2
+VALID_ENERGY_SAVING_SCHEDULE_IDS = (1, 2)
+
+
+class EnergySavingMode(Enum):
+    """Energy saving schedule mode."""
+
+    UNKNOWN = "unknown"
+    OFF = "off"
+    ON = "on"
+
+    @classmethod
+    def build(cls, value: object) -> EnergySavingMode:
+        """Parse raw mode from API into EnergySavingMode."""
+        if value is None:
+            return cls.UNKNOWN
+        val_str = str(value).strip().lower()
+        if val_str in ("1", "on", "enable", "true"):
+            return cls.ON
+        if val_str in ("0", "off", "disable", "false"):
+            return cls.OFF
+        return cls.UNKNOWN
 
 
 class TemperatureUnit(Enum):
@@ -408,3 +477,36 @@ def resolve_spa_model(
     model_name = SPA_MODEL_MAP.get((brand_id, collection_id, model_id), "Unknown")
 
     return (brand, collection, model_name)
+
+
+class DeviceType(Enum):
+    """Connected Spa kit adapter device type.
+
+    The Connected Spa Kit 2 consists of two modules:
+    - HNA (Home Network Adapter): Connected to home network, acts as API bridge.
+    - SNA (Spa Network Adapter): Located in the tub, physically wired to controller.
+    """
+
+    UNKNOWN = "unknown"
+    HNA = "hna"
+    SNA = "sna"
+
+    @classmethod
+    def build(cls, value: str | None) -> DeviceType:
+        """Parse a raw string into a DeviceType.
+
+        Args:
+        ----
+            value: The raw device type string, or None.
+
+        Returns:
+        -------
+            The matching DeviceType, or DeviceType.UNKNOWN for unrecognized values.
+
+        """
+        if value is None:
+            return cls.UNKNOWN
+        return _DEVICE_TYPE_MAP.get(value.lower(), cls.UNKNOWN)
+
+
+_DEVICE_TYPE_MAP: dict[str, DeviceType] = {d.value: d for d in DeviceType}

hotspring/exceptions.py

@@ -26,3 +26,18 @@ class HotSpringCommandError(HotSpringError):
 
     Raised when a command sent to the spa is rejected or fails.
     """
+
+
+class HotSpringInvalidDeviceError(HotSpringError):
+    """Hot Spring invalid device exception.
+
+    Raised when attempting to connect to or command an unsupported device.
+    """
+
+
+class HotSpringSNADetectedError(HotSpringInvalidDeviceError):
+    """Hot Spring SNA detected exception.
+
+    Raised when connecting to a Spa Network Adapter (SNA) instead of
+    the Home Network Adapter (HNA). The HNA must be used as the API bridge.
+    """