Update cli, light modules, and docs to use FeatureAttributes (#1364)

kasa/cli/light.py

@@ -25,7 +25,9 @@ def light(dev) -> None:
 @pass_dev_or_child
 async def brightness(dev: Device, brightness: int, transition: int):
     """Get or set brightness."""
-    if not (light := dev.modules.get(Module.Light)) or not light.is_dimmable:
+    if not (light := dev.modules.get(Module.Light)) or not light.has_feature(
+        "brightness"
+    ):
         error("This device does not support brightness.")
         return
 
@@ -45,13 +47,15 @@ async def brightness(dev: Device, brightness: int, transition: int):
 @pass_dev_or_child
 async def temperature(dev: Device, temperature: int, transition: int):
     """Get or set color temperature."""
-    if not (light := dev.modules.get(Module.Light)) or not light.is_variable_color_temp:
+    if not (light := dev.modules.get(Module.Light)) or not (
+        color_temp_feat := light.get_feature("color_temp")
+    ):
         error("Device does not support color temperature")
         return
 
     if temperature is None:
         echo(f"Color temperature: {light.color_temp}")
-        valid_temperature_range = light.valid_temperature_range
+        valid_temperature_range = color_temp_feat.range
         if valid_temperature_range != (0, 0):
             echo("(min: {}, max: {})".format(*valid_temperature_range))
         else:
@@ -59,7 +63,7 @@ async def temperature(dev: Device, temperature: int, transition: int):
                 "Temperature range unknown, please open a github issue"
                 f" or a pull request for model '{dev.model}'"
             )
-        return light.valid_temperature_range
+        return color_temp_feat.range
     else:
         echo(f"Setting color temperature to {temperature}")
         return await light.set_color_temp(temperature, transition=transition)
@@ -99,7 +103,7 @@ async def effect(dev: Device, ctx, effect):
 @pass_dev_or_child
 async def hsv(dev: Device, ctx, h, s, v, transition):
     """Get or set color in HSV."""
-    if not (light := dev.modules.get(Module.Light)) or not light.is_color:
+    if not (light := dev.modules.get(Module.Light)) or not light.has_feature("hsv"):
         error("Device does not support colors")
         return
 

kasa/interfaces/light.py

@@ -23,13 +23,13 @@ Get the light module to interact:
 
 >>> light = dev.modules[Module.Light]
 
-You can use the ``is_``-prefixed properties to check for supported features:
+You can use the ``has_feature()`` method to check for supported features:
 
->>> light.is_dimmable
+>>> light.has_feature("brightness")
 True
->>> light.is_color
+>>> light.has_feature("hsv")
 True
->>> light.is_variable_color_temp
+>>> light.has_feature("color_temp")
 True
 
 All known bulbs support changing the brightness:
@@ -43,8 +43,9 @@ All known bulbs support changing the brightness:
 
 Bulbs supporting color temperature can be queried for the supported range:
 
->>> light.valid_temperature_range
-ColorTempRange(min=2500, max=6500)
+>>> if color_temp_feature := light.get_feature("color_temp"):
+>>>     print(f"{color_temp_feature.minimum_value}, {color_temp_feature.maximum_value}")
+2500, 6500
 >>> await light.set_color_temp(3000)
 >>> await dev.update()
 >>> light.color_temp

kasa/interfaces/lighteffect.py

@@ -13,8 +13,7 @@ Living Room Bulb
 
 Light effects are accessed via the LightPreset module. To list available presets
 
->>> if dev.modules[Module.Light].has_effects:
->>>     light_effect = dev.modules[Module.LightEffect]
+>>> light_effect = dev.modules[Module.LightEffect]
 >>> light_effect.effect_list
 ['Off', 'Party', 'Relax']
 

kasa/iot/modules/light.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 from dataclasses import asdict
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Annotated, cast
 
 from ...device_type import DeviceType
 from ...exceptions import KasaException
 from ...feature import Feature
 from ...interfaces.light import HSV, ColorTempRange, LightState
 from ...interfaces.light import Light as LightInterface
+from ...module import FeatureAttribute
 from ..iotmodule import IotModule
 
 if TYPE_CHECKING:
@@ -32,7 +33,7 @@ class Light(IotModule, LightInterface):
         super()._initialize_features()
         device = self._device
 
-        if self._device._is_dimmable:
+        if device._is_dimmable:
             self._add_feature(
                 Feature(
                     device,
@@ -46,7 +47,7 @@ class Light(IotModule, LightInterface):
                     category=Feature.Category.Primary,
                 )
             )
-        if self._device._is_variable_color_temp:
+        if device._is_variable_color_temp:
             self._add_feature(
                 Feature(
                     device=device,
@@ -60,7 +61,7 @@ class Light(IotModule, LightInterface):
                     type=Feature.Type.Number,
                 )
             )
-        if self._device._is_color:
+        if device._is_color:
             self._add_feature(
                 Feature(
                     device=device,
@@ -95,13 +96,13 @@ class Light(IotModule, LightInterface):
         return self._device._is_dimmable
 
     @property  # type: ignore
-    def brightness(self) -> int:
+    def brightness(self) -> Annotated[int, FeatureAttribute()]:
         """Return the current brightness in percentage."""
         return self._device._brightness
 
     async def set_brightness(
         self, brightness: int, *, transition: int | None = None
-    ) -> dict:
+    ) -> Annotated[dict, FeatureAttribute()]:
         """Set the brightness in percentage. A value of 0 will turn off the light.
 
         :param int brightness: brightness in percent
@@ -133,7 +134,7 @@ class Light(IotModule, LightInterface):
         return bulb._has_effects
 
     @property
-    def hsv(self) -> HSV:
+    def hsv(self) -> Annotated[HSV, FeatureAttribute()]:
         """Return the current HSV state of the bulb.
 
         :return: hue, saturation and value (degrees, %, %)
@@ -149,7 +150,7 @@ class Light(IotModule, LightInterface):
         value: int | None = None,
         *,
         transition: int | None = None,
-    ) -> dict:
+    ) -> Annotated[dict, FeatureAttribute()]:
         """Set new HSV.
 
         Note, transition is not supported and will be ignored.
@@ -176,7 +177,7 @@ class Light(IotModule, LightInterface):
         return bulb._valid_temperature_range
 
     @property
-    def color_temp(self) -> int:
+    def color_temp(self) -> Annotated[int, FeatureAttribute()]:
         """Whether the bulb supports color temperature changes."""
         if (
             bulb := self._get_bulb_device()
@@ -186,7 +187,7 @@ class Light(IotModule, LightInterface):
 
     async def set_color_temp(
         self, temp: int, *, brightness: int | None = None, transition: int | None = None
-    ) -> dict:
+    ) -> Annotated[dict, FeatureAttribute()]:
         """Set the color temperature of the device in kelvin.
 
         Note, transition is not supported and will be ignored.
@@ -242,17 +243,18 @@ class Light(IotModule, LightInterface):
         return self._light_state
 
     async def _post_update_hook(self) -> None:
-        if self._device.is_on is False:
+        device = self._device
+        if device.is_on is False:
             state = LightState(light_on=False)
         else:
             state = LightState(light_on=True)
-            if self.is_dimmable:
+            if device._is_dimmable:
                 state.brightness = self.brightness
-            if self.is_color:
+            if device._is_color:
                 hsv = self.hsv
                 state.hue = hsv.hue
                 state.saturation = hsv.saturation
-            if self.is_variable_color_temp:
+            if device._is_variable_color_temp:
                 state.color_temp = self.color_temp
         self._light_state = state
 

kasa/iot/modules/lightpreset.py

@@ -85,17 +85,19 @@ class LightPreset(IotModule, LightPresetInterface):
     def preset(self) -> str:
         """Return current preset name."""
         light = self._device.modules[Module.Light]
+        is_color = light.has_feature("hsv")
+        is_variable_color_temp = light.has_feature("color_temp")
+
         brightness = light.brightness
-        color_temp = light.color_temp if light.is_variable_color_temp else None
-        h, s = (light.hsv.hue, light.hsv.saturation) if light.is_color else (None, None)
+        color_temp = light.color_temp if is_variable_color_temp else None
+
+        h, s = (light.hsv.hue, light.hsv.saturation) if is_color else (None, None)
         for preset_name, preset in self._presets.items():
             if (
                 preset.brightness == brightness
-                and (
-                    preset.color_temp == color_temp or not light.is_variable_color_temp
-                )
-                and (preset.hue == h or not light.is_color)
-                and (preset.saturation == s or not light.is_color)
+                and (preset.color_temp == color_temp or not is_variable_color_temp)
+                and (preset.hue == h or not is_color)
+                and (preset.saturation == s or not is_color)
             ):
                 return preset_name
         return self.PRESET_NOT_SET
@@ -107,7 +109,7 @@ class LightPreset(IotModule, LightPresetInterface):
         """Set a light preset for the device."""
         light = self._device.modules[Module.Light]
         if preset_name == self.PRESET_NOT_SET:
-            if light.is_color:
+            if light.has_feature("hsv"):
                 preset = LightState(hue=0, saturation=0, brightness=100)
             else:
                 preset = LightState(brightness=100)

kasa/smart/modules/light.py

@@ -55,7 +55,7 @@ class Light(SmartModule, LightInterface):
 
         :return: White temperature range in Kelvin (minimum, maximum)
         """
-        if not self.is_variable_color_temp:
+        if Module.ColorTemperature not in self._device.modules:
             raise KasaException("Color temperature not supported")
 
         return self._device.modules[Module.ColorTemperature].valid_temperature_range
@@ -66,7 +66,7 @@ class Light(SmartModule, LightInterface):
 
         :return: hue, saturation and value (degrees, %, %)
         """
-        if not self.is_color:
+        if Module.Color not in self._device.modules:
             raise KasaException("Bulb does not support color.")
 
         return self._device.modules[Module.Color].hsv
@@ -74,7 +74,7 @@ class Light(SmartModule, LightInterface):
     @property
     def color_temp(self) -> Annotated[int, FeatureAttribute()]:
         """Whether the bulb supports color temperature changes."""
-        if not self.is_variable_color_temp:
+        if Module.ColorTemperature not in self._device.modules:
             raise KasaException("Bulb does not support colortemp.")
 
         return self._device.modules[Module.ColorTemperature].color_temp
@@ -82,7 +82,7 @@ class Light(SmartModule, LightInterface):
     @property
     def brightness(self) -> Annotated[int, FeatureAttribute()]:
         """Return the current brightness in percentage."""
-        if not self.is_dimmable:  # pragma: no cover
+        if Module.Brightness not in self._device.modules:
             raise KasaException("Bulb is not dimmable.")
 
         return self._device.modules[Module.Brightness].brightness
@@ -104,7 +104,7 @@ class Light(SmartModule, LightInterface):
         :param int value: value between 1 and 100
         :param int transition: transition in milliseconds.
         """
-        if not self.is_color:
+        if Module.Color not in self._device.modules:
             raise KasaException("Bulb does not support color.")
 
         return await self._device.modules[Module.Color].set_hsv(hue, saturation, value)
@@ -119,7 +119,7 @@ class Light(SmartModule, LightInterface):
         :param int temp: The new color temperature, in Kelvin
         :param int transition: transition in milliseconds.
         """
-        if not self.is_variable_color_temp:
+        if Module.ColorTemperature not in self._device.modules:
             raise KasaException("Bulb does not support colortemp.")
         return await self._device.modules[Module.ColorTemperature].set_color_temp(
             temp, brightness=brightness
@@ -135,7 +135,7 @@ class Light(SmartModule, LightInterface):
         :param int brightness: brightness in percent
         :param int transition: transition in milliseconds.
         """
-        if not self.is_dimmable:  # pragma: no cover
+        if Module.Brightness not in self._device.modules:
             raise KasaException("Bulb is not dimmable.")
 
         return await self._device.modules[Module.Brightness].set_brightness(brightness)
@@ -167,16 +167,17 @@ class Light(SmartModule, LightInterface):
         return self._light_state
 
     async def _post_update_hook(self) -> None:
-        if self._device.is_on is False:
+        device = self._device
+        if device.is_on is False:
             state = LightState(light_on=False)
         else:
             state = LightState(light_on=True)
-            if self.is_dimmable:
+            if Module.Brightness in device.modules:
                 state.brightness = self.brightness
-            if self.is_color:
+            if Module.Color in device.modules:
                 hsv = self.hsv
                 state.hue = hsv.hue
                 state.saturation = hsv.saturation
-            if self.is_variable_color_temp:
+            if Module.ColorTemperature in device.modules:
                 state.color_temp = self.color_temp
         self._light_state = state

kasa/smart/modules/lightpreset.py

@@ -96,13 +96,18 @@ class LightPreset(SmartModule, LightPresetInterface):
         """Return current preset name."""
         light = self._device.modules[SmartModule.Light]
         brightness = light.brightness
-        color_temp = light.color_temp if light.is_variable_color_temp else None
-        h, s = (light.hsv.hue, light.hsv.saturation) if light.is_color else (None, None)
+        color_temp = light.color_temp if light.has_feature("color_temp") else None
+        h, s = (
+            (light.hsv.hue, light.hsv.saturation)
+            if light.has_feature("hsv")
+            else (None, None)
+        )
         for preset_name, preset in self._presets.items():
             if (
                 preset.brightness == brightness
                 and (
-                    preset.color_temp == color_temp or not light.is_variable_color_temp
+                    preset.color_temp == color_temp
+                    or not light.has_feature("color_temp")
                 )
                 and preset.hue == h
                 and preset.saturation == s
@@ -117,7 +122,7 @@ class LightPreset(SmartModule, LightPresetInterface):
         """Set a light preset for the device."""
         light = self._device.modules[SmartModule.Light]
         if preset_name == self.PRESET_NOT_SET:
-            if light.is_color:
+            if light.has_feature("hsv"):
                 preset = LightState(hue=0, saturation=0, brightness=100)
             else:
                 preset = LightState(brightness=100)