Allow passing alarm parameter overrides (#1340)

Allows specifying alarm parameters duration, volume and sound.
Adds new feature: `alarm_duration`.
Breaking change to `alarm_volume' on the `smart.Alarm` module is changed from `str` to `int`
Co-authored-by: Steven B <51370195+sdb9696@users.noreply.github.com>

kasa/smart/modules/alarm.py

@@ -2,11 +2,27 @@
 
 from __future__ import annotations
 
-from typing import Literal
+from typing import TYPE_CHECKING, Annotated, Literal, TypeAlias
 
 from ...feature import Feature
+from ...module import FeatureAttribute
 from ..smartmodule import SmartModule
 
+DURATION_MAX = 10 * 60
+
+VOLUME_INT_TO_STR = {
+    0: "mute",
+    1: "low",
+    2: "normal",
+    3: "high",
+}
+
+VOLUME_STR_LIST = [v for v in VOLUME_INT_TO_STR.values()]
+VOLUME_INT_RANGE = (min(VOLUME_INT_TO_STR.keys()), max(VOLUME_INT_TO_STR.keys()))
+VOLUME_STR_TO_INT = {v: k for k, v in VOLUME_INT_TO_STR.items()}
+
+AlarmVolume: TypeAlias = Literal["mute", "low", "normal", "high"]
+
 
 class Alarm(SmartModule):
     """Implementation of alarm module."""
@@ -21,10 +37,7 @@ class Alarm(SmartModule):
         }
 
     def _initialize_features(self) -> None:
-        """Initialize features.
-
-        This is implemented as some features depend on device responses.
-        """
+        """Initialize features."""
         device = self._device
         self._add_feature(
             Feature(
@@ -67,11 +80,37 @@ class Alarm(SmartModule):
                 id="alarm_volume",
                 name="Alarm volume",
                 container=self,
-                attribute_getter="alarm_volume",
+                attribute_getter="_alarm_volume_str",
                 attribute_setter="set_alarm_volume",
                 category=Feature.Category.Config,
                 type=Feature.Type.Choice,
-                choices_getter=lambda: ["low", "normal", "high"],
+                choices_getter=lambda: VOLUME_STR_LIST,
+            )
+        )
+        self._add_feature(
+            Feature(
+                device,
+                id="alarm_volume_level",
+                name="Alarm volume",
+                container=self,
+                attribute_getter="alarm_volume",
+                attribute_setter="set_alarm_volume",
+                category=Feature.Category.Config,
+                type=Feature.Type.Number,
+                range_getter=lambda: VOLUME_INT_RANGE,
+            )
+        )
+        self._add_feature(
+            Feature(
+                device,
+                id="alarm_duration",
+                name="Alarm duration",
+                container=self,
+                attribute_getter="alarm_duration",
+                attribute_setter="set_alarm_duration",
+                category=Feature.Category.Config,
+                type=Feature.Type.Number,
+                range_getter=lambda: (1, DURATION_MAX),
             )
         )
         self._add_feature(
@@ -96,15 +135,16 @@ class Alarm(SmartModule):
         )
 
     @property
-    def alarm_sound(self) -> str:
+    def alarm_sound(self) -> Annotated[str, FeatureAttribute()]:
         """Return current alarm sound."""
         return self.data["get_alarm_configure"]["type"]
 
-    async def set_alarm_sound(self, sound: str) -> dict:
+    async def set_alarm_sound(self, sound: str) -> Annotated[dict, FeatureAttribute()]:
         """Set alarm sound.
 
         See *alarm_sounds* for list of available sounds.
         """
+        self._check_sound(sound)
         payload = self.data["get_alarm_configure"].copy()
         payload["type"] = sound
         return await self.call("set_alarm_configure", payload)
@@ -115,16 +155,40 @@ class Alarm(SmartModule):
         return self.data["get_support_alarm_type_list"]["alarm_type_list"]
 
     @property
-    def alarm_volume(self) -> Literal["low", "normal", "high"]:
+    def alarm_volume(self) -> Annotated[int, FeatureAttribute("alarm_volume_level")]:
+        """Return alarm volume."""
+        return VOLUME_STR_TO_INT[self._alarm_volume_str]
+
+    @property
+    def _alarm_volume_str(
+        self,
+    ) -> Annotated[AlarmVolume, FeatureAttribute("alarm_volume")]:
         """Return alarm volume."""
         return self.data["get_alarm_configure"]["volume"]
 
-    async def set_alarm_volume(self, volume: Literal["low", "normal", "high"]) -> dict:
+    async def set_alarm_volume(
+        self, volume: AlarmVolume | int
+    ) -> Annotated[dict, FeatureAttribute()]:
         """Set alarm volume."""
+        self._check_and_convert_volume(volume)
         payload = self.data["get_alarm_configure"].copy()
         payload["volume"] = volume
         return await self.call("set_alarm_configure", payload)
 
+    @property
+    def alarm_duration(self) -> Annotated[int, FeatureAttribute()]:
+        """Return alarm duration."""
+        return self.data["get_alarm_configure"]["duration"]
+
+    async def set_alarm_duration(
+        self, duration: int
+    ) -> Annotated[dict, FeatureAttribute()]:
+        """Set alarm duration."""
+        self._check_duration(duration)
+        payload = self.data["get_alarm_configure"].copy()
+        payload["duration"] = duration
+        return await self.call("set_alarm_configure", payload)
+
     @property
     def active(self) -> bool:
         """Return true if alarm is active."""
@@ -136,10 +200,62 @@ class Alarm(SmartModule):
         src = self._device.sys_info["in_alarm_source"]
         return src if src else None
 
-    async def play(self) -> dict:
-        """Play alarm."""
-        return await self.call("play_alarm")
+    async def play(
+        self,
+        *,
+        duration: int | None = None,
+        volume: int | AlarmVolume | None = None,
+        sound: str | None = None,
+    ) -> dict:
+        """Play alarm.
+
+        The optional *duration*, *volume*, and *sound* to override the device settings.
+        *volume* can be set to 'mute', 'low', 'normal', or 'high'.
+        *duration* is in seconds.
+        See *alarm_sounds* for the list of sounds available for the device.
+        """
+        params: dict[str, str | int] = {}
+
+        if duration is not None:
+            self._check_duration(duration)
+            params["alarm_duration"] = duration
+
+        if volume is not None:
+            target_volume = self._check_and_convert_volume(volume)
+            params["alarm_volume"] = target_volume
+
+        if sound is not None:
+            self._check_sound(sound)
+            params["alarm_type"] = sound
+
+        return await self.call("play_alarm", params)
 
     async def stop(self) -> dict:
         """Stop alarm."""
         return await self.call("stop_alarm")
+
+    def _check_and_convert_volume(self, volume: str | int) -> str:
+        """Raise an exception on invalid volume."""
+        if isinstance(volume, int):
+            volume = VOLUME_INT_TO_STR.get(volume, "invalid")
+
+        if TYPE_CHECKING:
+            assert isinstance(volume, str)
+
+        if volume not in VOLUME_INT_TO_STR.values():
+            raise ValueError(
+                f"Invalid volume {volume} "
+                f"available: {VOLUME_INT_TO_STR.keys()}, {VOLUME_INT_TO_STR.values()}"
+            )
+
+        return volume
+
+    def _check_duration(self, duration: int) -> None:
+        """Raise an exception on invalid duration."""
+        if duration < 1 or duration > DURATION_MAX:
+            raise ValueError(f"Invalid duration {duration} available: 1-600")
+
+    def _check_sound(self, sound: str) -> None:
+        """Raise an exception on invalid sound."""
+        if sound not in self.alarm_sounds:
+            raise ValueError(f"Invalid sound {sound} available: {self.alarm_sounds}")