Rename bulb interface to light and move fan and light interface to interfaces (#910)

Also rename BulbPreset to LightPreset.

kasa/interfaces/__init__.py

@@ -0,0 +1,14 @@
+"""Package for interfaces."""
+
+from .fan import Fan
+from .led import Led
+from .light import Light, LightPreset
+from .lighteffect import LightEffect
+
+__all__ = [
+    "Fan",
+    "Led",
+    "Light",
+    "LightEffect",
+    "LightPreset",
+]

kasa/interfaces/fan.py

@@ -0,0 +1,20 @@
+"""Module for Fan Interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..device import Device
+
+
+class Fan(Device, ABC):
+    """Interface for a Fan."""
+
+    @property
+    @abstractmethod
+    def fan_speed_level(self) -> int:
+        """Return fan speed level."""
+
+    @abstractmethod
+    async def set_fan_speed_level(self, level: int):
+        """Set fan speed level."""

kasa/interfaces/light.py

@@ -0,0 +1,139 @@
+"""Module for Device base class."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import NamedTuple, Optional
+
+from pydantic.v1 import BaseModel
+
+from ..device import Device
+
+
+class ColorTempRange(NamedTuple):
+    """Color temperature range."""
+
+    min: int
+    max: int
+
+
+class HSV(NamedTuple):
+    """Hue-saturation-value."""
+
+    hue: int
+    saturation: int
+    value: int
+
+
+class LightPreset(BaseModel):
+    """Light configuration preset."""
+
+    index: int
+    brightness: int
+
+    # These are not available for effect mode presets on light strips
+    hue: Optional[int]  # noqa: UP007
+    saturation: Optional[int]  # noqa: UP007
+    color_temp: Optional[int]  # noqa: UP007
+
+    # Variables for effect mode presets
+    custom: Optional[int]  # noqa: UP007
+    id: Optional[str]  # noqa: UP007
+    mode: Optional[int]  # noqa: UP007
+
+
+class Light(Device, ABC):
+    """Base class for TP-Link Light."""
+
+    def _raise_for_invalid_brightness(self, value):
+        if not isinstance(value, int) or not (0 <= value <= 100):
+            raise ValueError(f"Invalid brightness value: {value} (valid range: 0-100%)")
+
+    @property
+    @abstractmethod
+    def is_color(self) -> bool:
+        """Whether the bulb supports color changes."""
+
+    @property
+    @abstractmethod
+    def is_variable_color_temp(self) -> bool:
+        """Whether the bulb supports color temperature changes."""
+
+    @property
+    @abstractmethod
+    def valid_temperature_range(self) -> ColorTempRange:
+        """Return the device-specific white temperature range (in Kelvin).
+
+        :return: White temperature range in Kelvin (minimum, maximum)
+        """
+
+    @property
+    @abstractmethod
+    def has_effects(self) -> bool:
+        """Return True if the device supports effects."""
+
+    @property
+    @abstractmethod
+    def hsv(self) -> HSV:
+        """Return the current HSV state of the bulb.
+
+        :return: hue, saturation and value (degrees, %, %)
+        """
+
+    @property
+    @abstractmethod
+    def color_temp(self) -> int:
+        """Whether the bulb supports color temperature changes."""
+
+    @property
+    @abstractmethod
+    def brightness(self) -> int:
+        """Return the current brightness in percentage."""
+
+    @abstractmethod
+    async def set_hsv(
+        self,
+        hue: int,
+        saturation: int,
+        value: int | None = None,
+        *,
+        transition: int | None = None,
+    ) -> dict:
+        """Set new HSV.
+
+        Note, transition is not supported and will be ignored.
+
+        :param int hue: hue in degrees
+        :param int saturation: saturation in percentage [0,100]
+        :param int value: value in percentage [0, 100]
+        :param int transition: transition in milliseconds.
+        """
+
+    @abstractmethod
+    async def set_color_temp(
+        self, temp: int, *, brightness=None, transition: int | None = None
+    ) -> dict:
+        """Set the color temperature of the device in kelvin.
+
+        Note, transition is not supported and will be ignored.
+
+        :param int temp: The new color temperature, in Kelvin
+        :param int transition: transition in milliseconds.
+        """
+
+    @abstractmethod
+    async def set_brightness(
+        self, brightness: int, *, transition: int | None = None
+    ) -> dict:
+        """Set the brightness in percentage.
+
+        Note, transition is not supported and will be ignored.
+
+        :param int brightness: brightness in percent
+        :param int transition: transition in milliseconds.
+        """
+
+    @property
+    @abstractmethod
+    def presets(self) -> list[LightPreset]:
+        """Return a list of available bulb setting presets."""