homeassistant 2025.7.3__py3-none-any.whl → 2025.8.0__py3-none-any.whl

homeassistant/components/knx/storage/config_store.py

@@ -13,10 +13,11 @@ from homeassistant.util.ulid import ulid_now
 
 from ..const import DOMAIN
 from .const import CONF_DATA
+from .migration import migrate_1_to_2
 
 _LOGGER = logging.getLogger(__name__)
 
-STORAGE_VERSION: Final = 1
+STORAGE_VERSION: Final = 2
 STORAGE_KEY: Final = f"{DOMAIN}/config_store.json"
 
 type KNXPlatformStoreModel = dict[str, dict[str, Any]]  # unique_id: configuration
@@ -45,6 +46,20 @@ class PlatformControllerBase(ABC):
         """Update an existing entities configuration."""
 
 
+class _KNXConfigStoreStorage(Store[KNXConfigStoreModel]):
+    """Storage handler for KNXConfigStore."""
+
+    async def _async_migrate_func(
+        self, old_major_version: int, old_minor_version: int, old_data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Migrate to the new version."""
+        if old_major_version == 1:
+            # version 2 introduced in 2025.8
+            migrate_1_to_2(old_data)
+
+        return old_data
+
+
 class KNXConfigStore:
     """Manage KNX config store data."""
 
@@ -56,7 +71,7 @@ class KNXConfigStore:
         """Initialize config store."""
         self.hass = hass
         self.config_entry = config_entry
-        self._store = Store[KNXConfigStoreModel](hass, STORAGE_VERSION, STORAGE_KEY)
+        self._store = _KNXConfigStoreStorage(hass, STORAGE_VERSION, STORAGE_KEY)
         self.data = KNXConfigStoreModel(entities={})
         self._platform_controllers: dict[Platform, PlatformControllerBase] = {}
 

homeassistant/components/knx/storage/const.py

@@ -2,6 +2,7 @@
 
 from typing import Final
 
+# Common
 CONF_DATA: Final = "data"
 CONF_ENTITY: Final = "entity"
 CONF_DEVICE_INFO: Final = "device_info"
@@ -12,10 +13,22 @@ CONF_DPT: Final = "dpt"
 
 CONF_GA_SENSOR: Final = "ga_sensor"
 CONF_GA_SWITCH: Final = "ga_switch"
-CONF_GA_COLOR_TEMP: Final = "ga_color_temp"
+
+# Cover
+CONF_GA_UP_DOWN: Final = "ga_up_down"
+CONF_GA_STOP: Final = "ga_stop"
+CONF_GA_STEP: Final = "ga_step"
+CONF_GA_POSITION_SET: Final = "ga_position_set"
+CONF_GA_POSITION_STATE: Final = "ga_position_state"
+CONF_GA_ANGLE: Final = "ga_angle"
+
+# Light
 CONF_COLOR_TEMP_MIN: Final = "color_temp_min"
 CONF_COLOR_TEMP_MAX: Final = "color_temp_max"
 CONF_GA_BRIGHTNESS: Final = "ga_brightness"
+CONF_GA_COLOR_TEMP: Final = "ga_color_temp"
+# Light/color
+CONF_COLOR: Final = "color"
 CONF_GA_COLOR: Final = "ga_color"
 CONF_GA_RED_BRIGHTNESS: Final = "ga_red_brightness"
 CONF_GA_RED_SWITCH: Final = "ga_red_switch"
@@ -27,9 +40,3 @@ CONF_GA_WHITE_BRIGHTNESS: Final = "ga_white_brightness"
 CONF_GA_WHITE_SWITCH: Final = "ga_white_switch"
 CONF_GA_HUE: Final = "ga_hue"
 CONF_GA_SATURATION: Final = "ga_saturation"
-CONF_GA_UP_DOWN: Final = "ga_up_down"
-CONF_GA_STOP: Final = "ga_stop"
-CONF_GA_STEP: Final = "ga_step"
-CONF_GA_POSITION_SET: Final = "ga_position_set"
-CONF_GA_POSITION_STATE: Final = "ga_position_state"
-CONF_GA_ANGLE: Final = "ga_angle"

homeassistant/components/knx/storage/entity_store_schema.py

@@ -29,6 +29,7 @@ from ..const import (
 )
 from ..validation import sync_state_validator
 from .const import (
+    CONF_COLOR,
     CONF_COLOR_TEMP_MAX,
     CONF_COLOR_TEMP_MIN,
     CONF_DATA,
@@ -43,23 +44,20 @@ from .const import (
     CONF_GA_GREEN_BRIGHTNESS,
     CONF_GA_GREEN_SWITCH,
     CONF_GA_HUE,
-    CONF_GA_PASSIVE,
     CONF_GA_POSITION_SET,
     CONF_GA_POSITION_STATE,
     CONF_GA_RED_BRIGHTNESS,
     CONF_GA_RED_SWITCH,
     CONF_GA_SATURATION,
     CONF_GA_SENSOR,
-    CONF_GA_STATE,
     CONF_GA_STEP,
     CONF_GA_STOP,
     CONF_GA_SWITCH,
     CONF_GA_UP_DOWN,
     CONF_GA_WHITE_BRIGHTNESS,
     CONF_GA_WHITE_SWITCH,
-    CONF_GA_WRITE,
 )
-from .knx_selector import GASelector
+from .knx_selector import GASelector, GroupSelect
 
 BASE_ENTITY_SCHEMA = vol.All(
     {
@@ -87,24 +85,6 @@ BASE_ENTITY_SCHEMA = vol.All(
 )
 
 
-def optional_ga_schema(key: str, ga_selector: GASelector) -> VolDictType:
-    """Validate group address schema or remove key if no address is set."""
-    # frontend will return {key: {"write": None, "state": None}} for unused GA sets
-    # -> remove this entirely for optional keys
-    # if one GA is set, validate as usual
-    return {
-        vol.Optional(key): ga_selector,
-        vol.Remove(key): vol.Schema(
-            {
-                vol.Optional(CONF_GA_WRITE): None,
-                vol.Optional(CONF_GA_STATE): None,
-                vol.Optional(CONF_GA_PASSIVE): vol.IsFalse(),  # None or empty list
-            },
-            extra=vol.ALLOW_EXTRA,
-        ),
-    }
-
-
 BINARY_SENSOR_SCHEMA = vol.Schema(
     {
         vol.Required(CONF_ENTITY): BASE_ENTITY_SCHEMA,
@@ -134,16 +114,14 @@ COVER_SCHEMA = vol.Schema(
         vol.Required(DOMAIN): vol.All(
             vol.Schema(
                 {
-                    **optional_ga_schema(CONF_GA_UP_DOWN, GASelector(state=False)),
+                    vol.Optional(CONF_GA_UP_DOWN): GASelector(state=False),
                     vol.Optional(CoverConf.INVERT_UPDOWN): selector.BooleanSelector(),
-                    **optional_ga_schema(CONF_GA_STOP, GASelector(state=False)),
-                    **optional_ga_schema(CONF_GA_STEP, GASelector(state=False)),
-                    **optional_ga_schema(CONF_GA_POSITION_SET, GASelector(state=False)),
-                    **optional_ga_schema(
-                        CONF_GA_POSITION_STATE, GASelector(write=False)
-                    ),
+                    vol.Optional(CONF_GA_STOP): GASelector(state=False),
+                    vol.Optional(CONF_GA_STEP): GASelector(state=False),
+                    vol.Optional(CONF_GA_POSITION_SET): GASelector(state=False),
+                    vol.Optional(CONF_GA_POSITION_STATE): GASelector(write=False),
                     vol.Optional(CoverConf.INVERT_POSITION): selector.BooleanSelector(),
-                    **optional_ga_schema(CONF_GA_ANGLE, GASelector()),
+                    vol.Optional(CONF_GA_ANGLE): GASelector(),
                     vol.Optional(CoverConf.INVERT_ANGLE): selector.BooleanSelector(),
                     vol.Optional(
                         CoverConf.TRAVELLING_TIME_DOWN, default=25
@@ -208,73 +186,112 @@ class LightColorModeSchema(StrEnum):
     HSV = "hsv"
 
 
-_LIGHT_COLOR_MODE_SCHEMA = "_light_color_mode_schema"
+_hs_color_inclusion_msg = (
+    "'Hue', 'Saturation' and 'Brightness' addresses are required for HSV configuration"
+)
 
-_COMMON_LIGHT_SCHEMA = vol.Schema(
-    {
-        vol.Optional(CONF_SYNC_STATE, default=True): sync_state_validator,
-        **optional_ga_schema(
-            CONF_GA_COLOR_TEMP, GASelector(write_required=True, dpt=ColorTempModes)
+
+LIGHT_KNX_SCHEMA = vol.All(
+    vol.Schema(
+        {
+            vol.Optional(CONF_GA_SWITCH): GASelector(write_required=True),
+            vol.Optional(CONF_GA_BRIGHTNESS): GASelector(write_required=True),
+            vol.Optional(CONF_GA_COLOR_TEMP): GASelector(
+                write_required=True, dpt=ColorTempModes
+            ),
+            vol.Optional(CONF_COLOR): GroupSelect(
+                vol.Schema(
+                    {
+                        vol.Optional(CONF_GA_COLOR): GASelector(
+                            write_required=True, dpt=LightColorMode
+                        )
+                    }
+                ),
+                vol.Schema(
+                    {
+                        vol.Required(CONF_GA_RED_BRIGHTNESS): GASelector(
+                            write_required=True
+                        ),
+                        vol.Optional(CONF_GA_RED_SWITCH): GASelector(
+                            write_required=False
+                        ),
+                        vol.Required(CONF_GA_GREEN_BRIGHTNESS): GASelector(
+                            write_required=True
+                        ),
+                        vol.Optional(CONF_GA_GREEN_SWITCH): GASelector(
+                            write_required=False
+                        ),
+                        vol.Required(CONF_GA_BLUE_BRIGHTNESS): GASelector(
+                            write_required=True
+                        ),
+                        vol.Optional(CONF_GA_BLUE_SWITCH): GASelector(
+                            write_required=False
+                        ),
+                        vol.Optional(CONF_GA_WHITE_BRIGHTNESS): GASelector(
+                            write_required=True
+                        ),
+                        vol.Optional(CONF_GA_WHITE_SWITCH): GASelector(
+                            write_required=False
+                        ),
+                    }
+                ),
+                vol.Schema(
+                    {
+                        vol.Required(CONF_GA_HUE): GASelector(write_required=True),
+                        vol.Required(CONF_GA_SATURATION): GASelector(
+                            write_required=True
+                        ),
+                    }
+                ),
+                # msg="error in `color` config",
+            ),
+            vol.Optional(CONF_SYNC_STATE, default=True): sync_state_validator,
+            vol.Optional(CONF_COLOR_TEMP_MIN, default=2700): vol.All(
+                vol.Coerce(int), vol.Range(min=1)
+            ),
+            vol.Optional(CONF_COLOR_TEMP_MAX, default=6000): vol.All(
+                vol.Coerce(int), vol.Range(min=1)
+            ),
+        }
+    ),
+    vol.Any(
+        vol.Schema(
+            {vol.Required(CONF_GA_SWITCH): object},
+            extra=vol.ALLOW_EXTRA,
         ),
-        vol.Optional(CONF_COLOR_TEMP_MIN, default=2700): vol.All(
-            vol.Coerce(int), vol.Range(min=1)
+        vol.Schema(  # brightness addresses are required in INDIVIDUAL_COLOR_SCHEMA
+            {vol.Required(CONF_COLOR): {vol.Required(CONF_GA_RED_BRIGHTNESS): object}},
+            extra=vol.ALLOW_EXTRA,
         ),
-        vol.Optional(CONF_COLOR_TEMP_MAX, default=6000): vol.All(
-            vol.Coerce(int), vol.Range(min=1)
+        msg="either 'address' or 'individual_colors' is required",
+    ),
+    vol.Any(
+        vol.Schema(  # 'brightness' is non-optional for hs-color
+            {
+                vol.Required(CONF_GA_BRIGHTNESS, msg=_hs_color_inclusion_msg): object,
+                vol.Required(CONF_COLOR): {
+                    vol.Required(CONF_GA_HUE, msg=_hs_color_inclusion_msg): object,
+                    vol.Required(
+                        CONF_GA_SATURATION, msg=_hs_color_inclusion_msg
+                    ): object,
+                },
+            },
+            extra=vol.ALLOW_EXTRA,
         ),
-    },
-    extra=vol.REMOVE_EXTRA,
-)
-
-_DEFAULT_LIGHT_SCHEMA = _COMMON_LIGHT_SCHEMA.extend(
-    {
-        vol.Required(_LIGHT_COLOR_MODE_SCHEMA): LightColorModeSchema.DEFAULT.value,
-        vol.Required(CONF_GA_SWITCH): GASelector(write_required=True),
-        **optional_ga_schema(CONF_GA_BRIGHTNESS, GASelector(write_required=True)),
-        **optional_ga_schema(
-            CONF_GA_COLOR,
-            GASelector(write_required=True, dpt=LightColorMode),
+        vol.Schema(  # hs-colors not used
+            {
+                vol.Optional(CONF_COLOR): {
+                    vol.Optional(CONF_GA_HUE): None,
+                    vol.Optional(CONF_GA_SATURATION): None,
+                },
+            },
+            extra=vol.ALLOW_EXTRA,
         ),
-    }
-)
-
-_INDIVIDUAL_LIGHT_SCHEMA = _COMMON_LIGHT_SCHEMA.extend(
-    {
-        vol.Required(_LIGHT_COLOR_MODE_SCHEMA): LightColorModeSchema.INDIVIDUAL.value,
-        **optional_ga_schema(CONF_GA_SWITCH, GASelector(write_required=True)),
-        **optional_ga_schema(CONF_GA_BRIGHTNESS, GASelector(write_required=True)),
-        vol.Required(CONF_GA_RED_BRIGHTNESS): GASelector(write_required=True),
-        **optional_ga_schema(CONF_GA_RED_SWITCH, GASelector(write_required=False)),
-        vol.Required(CONF_GA_GREEN_BRIGHTNESS): GASelector(write_required=True),
-        **optional_ga_schema(CONF_GA_GREEN_SWITCH, GASelector(write_required=False)),
-        vol.Required(CONF_GA_BLUE_BRIGHTNESS): GASelector(write_required=True),
-        **optional_ga_schema(CONF_GA_BLUE_SWITCH, GASelector(write_required=False)),
-        **optional_ga_schema(CONF_GA_WHITE_BRIGHTNESS, GASelector(write_required=True)),
-        **optional_ga_schema(CONF_GA_WHITE_SWITCH, GASelector(write_required=False)),
-    }
-)
-
-_HSV_LIGHT_SCHEMA = _COMMON_LIGHT_SCHEMA.extend(
-    {
-        vol.Required(_LIGHT_COLOR_MODE_SCHEMA): LightColorModeSchema.HSV.value,
-        vol.Required(CONF_GA_SWITCH): GASelector(write_required=True),
-        vol.Required(CONF_GA_BRIGHTNESS): GASelector(write_required=True),
-        vol.Required(CONF_GA_HUE): GASelector(write_required=True),
-        vol.Required(CONF_GA_SATURATION): GASelector(write_required=True),
-    }
+        msg=_hs_color_inclusion_msg,
+    ),
 )
 
 
-LIGHT_KNX_SCHEMA = cv.key_value_schemas(
-    _LIGHT_COLOR_MODE_SCHEMA,
-    default_schema=_DEFAULT_LIGHT_SCHEMA,
-    value_schemas={
-        LightColorModeSchema.DEFAULT: _DEFAULT_LIGHT_SCHEMA,
-        LightColorModeSchema.INDIVIDUAL: _INDIVIDUAL_LIGHT_SCHEMA,
-        LightColorModeSchema.HSV: _HSV_LIGHT_SCHEMA,
-    },
-)
-
 LIGHT_SCHEMA = vol.Schema(
     {
         vol.Required(CONF_ENTITY): BASE_ENTITY_SCHEMA,

homeassistant/components/knx/storage/entity_store_validation.py

@@ -1,4 +1,4 @@
-"""KNX Entity Store Validation."""
+"""KNX entity store validation."""
 
 from typing import Literal, TypedDict
 

homeassistant/components/knx/storage/knx_selector.py

@@ -1,5 +1,6 @@
 """Selectors for KNX."""
 
+from collections.abc import Hashable, Iterable
 from enum import Enum
 from typing import Any
 
@@ -9,6 +10,31 @@ from ..validation import ga_validator, maybe_ga_validator
 from .const import CONF_DPT, CONF_GA_PASSIVE, CONF_GA_STATE, CONF_GA_WRITE
 
 
+class GroupSelect(vol.Any):
+    """Use the first validated value.
+
+    This is a version of vol.Any with custom error handling to
+    show proper invalid markers for sub-schema items in the UI.
+    """
+
+    def _exec(self, funcs: Iterable, v: Any, path: list[Hashable] | None = None) -> Any:
+        """Execute the validation functions."""
+        errors: list[vol.Invalid] = []
+        for func in funcs:
+            try:
+                if path is None:
+                    return func(v)
+                return func(path, v)
+            except vol.Invalid as e:
+                errors.append(e)
+        if errors:
+            raise next(
+                (err for err in errors if "extra keys not allowed" not in err.msg),
+                errors[0],
+            )
+        raise vol.AnyInvalid(self.msg or "no valid value found", path=path)
+
+
 class GASelector:
     """Selector for a KNX group address structure."""
 

homeassistant/components/knx/storage/migration.py

@@ -0,0 +1,42 @@
+"""Migration functions for KNX config store schema."""
+
+from typing import Any
+
+from homeassistant.const import Platform
+
+from . import const as store_const
+
+
+def migrate_1_to_2(data: dict[str, Any]) -> None:
+    """Migrate from schema 1 to schema 2."""
+    if lights := data.get("entities", {}).get(Platform.LIGHT):
+        for light in lights.values():
+            _migrate_light_schema_1_to_2(light["knx"])
+
+
+def _migrate_light_schema_1_to_2(light_knx_data: dict[str, Any]) -> None:
+    """Migrate light color mode schema."""
+    # Remove no more needed helper data from schema
+    light_knx_data.pop("_light_color_mode_schema", None)
+
+    # Move color related group addresses to new "color" key
+    color: dict[str, Any] = {}
+    for color_key in (
+        # optional / required and exclusive keys are the same in old and new schema
+        store_const.CONF_GA_COLOR,
+        store_const.CONF_GA_HUE,
+        store_const.CONF_GA_SATURATION,
+        store_const.CONF_GA_RED_BRIGHTNESS,
+        store_const.CONF_GA_RED_SWITCH,
+        store_const.CONF_GA_GREEN_BRIGHTNESS,
+        store_const.CONF_GA_GREEN_SWITCH,
+        store_const.CONF_GA_BLUE_BRIGHTNESS,
+        store_const.CONF_GA_BLUE_SWITCH,
+        store_const.CONF_GA_WHITE_BRIGHTNESS,
+        store_const.CONF_GA_WHITE_SWITCH,
+    ):
+        if color_key in light_knx_data:
+            color[color_key] = light_knx_data.pop(color_key)
+
+    if color:
+        light_knx_data[store_const.CONF_COLOR] = color

homeassistant/components/knx/storage/util.py

@@ -0,0 +1,51 @@
+"""Utility functions for the KNX integration."""
+
+from functools import partial
+from typing import Any
+
+from homeassistant.helpers.typing import ConfigType
+
+from .const import CONF_DPT, CONF_GA_PASSIVE, CONF_GA_STATE, CONF_GA_WRITE
+
+
+def nested_get(dic: ConfigType, *keys: str, default: Any | None = None) -> Any:
+    """Get the value from a nested dictionary."""
+    for key in keys:
+        if key not in dic:
+            return default
+        dic = dic[key]
+    return dic
+
+
+class ConfigExtractor:
+    """Helper class for extracting values from a knx config store dictionary."""
+
+    __slots__ = ("get",)
+
+    def __init__(self, config: ConfigType) -> None:
+        """Initialize the extractor."""
+        self.get = partial(nested_get, config)
+
+    def get_write(self, *path: str) -> str | None:
+        """Get the write group address."""
+        return self.get(*path, CONF_GA_WRITE)  # type: ignore[no-any-return]
+
+    def get_state(self, *path: str) -> str | None:
+        """Get the state group address."""
+        return self.get(*path, CONF_GA_STATE)  # type: ignore[no-any-return]
+
+    def get_write_and_passive(self, *path: str) -> list[Any | None]:
+        """Get the group addresses of write and passive."""
+        write = self.get(*path, CONF_GA_WRITE)
+        passive = self.get(*path, CONF_GA_PASSIVE)
+        return [write, *passive] if passive else [write]
+
+    def get_state_and_passive(self, *path: str) -> list[Any | None]:
+        """Get the group addresses of state and passive."""
+        state = self.get(*path, CONF_GA_STATE)
+        passive = self.get(*path, CONF_GA_PASSIVE)
+        return [state, *passive] if passive else [state]
+
+    def get_dpt(self, *path: str) -> str | None:
+        """Get the data point type of a group address config key."""
+        return self.get(*path, CONF_DPT)  # type: ignore[no-any-return]