Individual manual control of brightness and color (#1356)

* refactor: introduce light control parameter enum

* refactor: replace manual control flag with parameter enum

* test: update deprecated color temp attribute

* build: set execution bits on task scripts

* feat: individual manual control of brightness and color

* test: add tests for individual manual control evaluation

* fix: sequential manual changes not always detected

If multiple attributes of a light were changed within an interval, only the last change was detected because the check in the interval only used the latest event. For example, if there was a brightness change and a following color change, only the color attribute was detected as manually controlled. To fix this, the manual control attribute flags are now set directly from the event handler so that all events are processed.

* fix: invalid service description

* docs: fix missing space in config description

* refactor: pluralize multivalued bitmask enum name

custom_components/adaptive_lighting/adaptation_utils.py

@@ -3,7 +3,8 @@
 import logging
 from collections.abc import AsyncGenerator
 from dataclasses import dataclass
-from typing import Any, Literal
+from enum import IntFlag, auto
+from typing import Any
 
 from homeassistant.components.light import (
     ATTR_BRIGHTNESS,
@@ -12,6 +13,8 @@ from homeassistant.components.light import (
     ATTR_BRIGHTNESS_STEP_PCT,
     ATTR_COLOR_NAME,
     ATTR_COLOR_TEMP_KELVIN,
+    ATTR_EFFECT,
+    ATTR_FLASH,
     ATTR_HS_COLOR,
     ATTR_RGB_COLOR,
     ATTR_RGBW_COLOR,
@@ -45,6 +48,41 @@ BRIGHTNESS_ATTRS = {
 ServiceData = dict[str, Any]
 
 
+class LightControlAttributes(IntFlag):
+    """Attributes of lights that the adaptation engine can control."""
+
+    NONE = 0
+    BRIGHTNESS = auto()
+    COLOR = auto()
+
+    ALL = BRIGHTNESS | COLOR
+
+    def __str__(self) -> str:
+        """Return a string representation of the attributes."""
+        if self == LightControlAttributes.NONE:
+            return "NONE"
+
+        return "|".join(
+            member.name
+            for member in type(self)
+            if member is not LightControlAttributes.NONE
+            and member in self
+            and member.name is not None
+        )
+
+    def has_any(self) -> bool:
+        """Determine whether any attribute is selected."""
+        return self != LightControlAttributes.NONE
+
+    def has_none(self) -> bool:
+        """Determine whether no attribute is selected."""
+        return self == LightControlAttributes.NONE
+
+    def has_all(self) -> bool:
+        """Determine whether all attributes are selected."""
+        return (self & LightControlAttributes.ALL) == LightControlAttributes.ALL
+
+
 def _split_service_call_data(service_data: ServiceData) -> list[ServiceData]:
     """Splits the service data by the adapted attributes.
 
@@ -145,7 +183,7 @@ class AdaptationData:
     service_call_datas: AsyncGenerator[ServiceData]
     force: bool
     max_length: int
-    which: Literal["brightness", "color", "both"]
+    attributes: LightControlAttributes
     initial_sleep: bool = False
 
     async def next_service_call_data(self) -> ServiceData | None:
@@ -161,7 +199,7 @@ class AdaptationData:
             f"sleep_time={self.sleep_time}, "
             f"force={self.force}, "
             f"max_length={self.max_length}, "
-            f"which={self.which}, "
+            f"attributes={self.attributes}, "
             f"initial_sleep={self.initial_sleep}"
             ")"
         )
@@ -171,20 +209,25 @@ class NoColorOrBrightnessInServiceDataError(Exception):
     """Exception raised when no color or brightness attributes are found in service data."""
 
 
-def _identify_lighting_type(
+def _identify_light_control_attributes(
     service_data: ServiceData,
-) -> Literal["brightness", "color", "both"]:
+) -> LightControlAttributes:
     """Extract the 'which' attribute from the service data."""
     has_brightness = ATTR_BRIGHTNESS in service_data
     has_color = any(attr in service_data for attr in COLOR_ATTRS)
-    if has_brightness and has_color:
-        return "both"
+
+    parameters = LightControlAttributes.NONE
+
     if has_brightness:
-        return "brightness"
+        parameters |= LightControlAttributes.BRIGHTNESS
     if has_color:
-        return "color"
-    msg = f"Invalid service_data, no brightness or color attributes found: {service_data=}"
-    raise NoColorOrBrightnessInServiceDataError(msg)
+        parameters |= LightControlAttributes.COLOR
+
+    if parameters == LightControlAttributes.NONE:
+        msg = f"Invalid service_data, no brightness or color attributes found: {service_data=}"
+        raise NoColorOrBrightnessInServiceDataError(msg)
+
+    return parameters
 
 
 def prepare_adaptation_data(
@@ -220,7 +263,7 @@ def prepare_adaptation_data(
         filter_by_state,
     )
 
-    lighting_type = _identify_lighting_type(service_data)
+    attributes = _identify_light_control_attributes(service_data)
 
     return AdaptationData(
         entity_id=entity_id,
@@ -229,5 +272,58 @@ def prepare_adaptation_data(
         service_call_datas=service_data_iterator,
         force=force,
         max_length=service_datas_length,
-        which=lighting_type,
+        attributes=attributes,
     )
+
+
+def manual_control_event_attribute_to_flags(
+    manual_control_attribute: bool | str,
+) -> LightControlAttributes:
+    """Convert manual control event data to light control attributes."""
+    if isinstance(manual_control_attribute, bool) and manual_control_attribute:
+        return LightControlAttributes.ALL
+    if manual_control_attribute == "brightness":
+        return LightControlAttributes.BRIGHTNESS
+    if manual_control_attribute == "color":
+        return LightControlAttributes.COLOR
+    return LightControlAttributes.NONE
+
+
+def has_brightness_attribute(
+    service_data: ServiceData,
+) -> bool:
+    """Determine whether the service data contains brightness attributes."""
+    return any(attr in BRIGHTNESS_ATTRS for attr in service_data)
+
+
+def has_color_attribute(
+    service_data: ServiceData,
+) -> bool:
+    """Determine whether the service data contains color attributes."""
+    return any(attr in COLOR_ATTRS for attr in service_data)
+
+
+def has_effect_attribute(
+    service_data: ServiceData,
+) -> bool:
+    """Determine whether the service data contains effect attributes."""
+    return ATTR_FLASH in service_data or ATTR_EFFECT in service_data
+
+
+def get_light_control_attributes(
+    service_data: ServiceData,
+) -> LightControlAttributes:
+    """Get the light control attributes affected by the service call data."""
+    parameters = LightControlAttributes.NONE
+
+    if has_brightness_attribute(service_data):
+        parameters |= LightControlAttributes.BRIGHTNESS
+
+    if has_color_attribute(service_data):
+        parameters |= LightControlAttributes.COLOR
+
+    if has_effect_attribute(service_data):
+        parameters |= LightControlAttributes.BRIGHTNESS
+        parameters |= LightControlAttributes.COLOR
+
+    return parameters