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

homeassistant/helpers/helper_integration.py

@@ -14,17 +14,20 @@ from .event import async_track_entity_registry_updated_event
 def async_handle_source_entity_changes(
     hass: HomeAssistant,
     *,
+    add_helper_config_entry_to_device: bool = True,
     helper_config_entry_id: str,
     set_source_entity_id_or_uuid: Callable[[str], None],
     source_device_id: str | None,
     source_entity_id_or_uuid: str,
-    source_entity_removed: Callable[[], Coroutine[Any, Any, None]],
+    source_entity_removed: Callable[[], Coroutine[Any, Any, None]] | None = None,
 ) -> CALLBACK_TYPE:
     """Handle changes to a helper entity's source entity.
 
     The following changes are handled:
-    - Entity removal: If the source entity is removed, the helper config entry
-      is removed, and the helper entity is cleaned up.
+    - Entity removal: If the source entity is removed:
+      - If source_entity_removed is provided, it is called to handle the removal.
+      - If source_entity_removed is not provided, The helper entity is updated to
+      not link to any device.
     - Entity ID changed: If the source entity's entity ID changes and the source
       entity is identified by an entity ID, the set_source_entity_id_or_uuid is
       called. If the source entity is identified by a UUID, the helper config entry
@@ -51,7 +54,18 @@ def async_handle_source_entity_changes(
 
         data = event.data
         if data["action"] == "remove":
-            await source_entity_removed()
+            if source_entity_removed:
+                await source_entity_removed()
+            else:
+                for (
+                    helper_entity_entry
+                ) in entity_registry.entities.get_entries_for_config_entry_id(
+                    helper_config_entry_id
+                ):
+                    # Update the helper entity to link to the new device (or no device)
+                    entity_registry.async_update_entity(
+                        helper_entity_entry.entity_id, device_id=None
+                    )
 
         if data["action"] != "update":
             return
@@ -88,15 +102,17 @@ def async_handle_source_entity_changes(
                 helper_entity.entity_id, device_id=source_entity_entry.device_id
             )
 
-        if source_entity_entry.device_id is not None:
+        if add_helper_config_entry_to_device:
+            if source_entity_entry.device_id is not None:
+                device_registry.async_update_device(
+                    source_entity_entry.device_id,
+                    add_config_entry_id=helper_config_entry_id,
+                )
+
             device_registry.async_update_device(
-                source_entity_entry.device_id,
-                add_config_entry_id=helper_config_entry_id,
+                source_device_id, remove_config_entry_id=helper_config_entry_id
             )
 
-        device_registry.async_update_device(
-            source_device_id, remove_config_entry_id=helper_config_entry_id
-        )
         source_device_id = source_entity_entry.device_id
 
         # Reload the config entry so the helper entity is recreated with
@@ -111,3 +127,46 @@ def async_handle_source_entity_changes(
     return async_track_entity_registry_updated_event(
         hass, source_entity_id, async_registry_updated
     )
+
+
+def async_remove_helper_config_entry_from_source_device(
+    hass: HomeAssistant,
+    *,
+    helper_config_entry_id: str,
+    source_device_id: str,
+) -> None:
+    """Remove helper config entry from source device.
+
+    This is a convenience function to migrate from helpers which added their config
+    entry to the source device.
+    """
+    device_registry = dr.async_get(hass)
+
+    if (
+        not (source_device := device_registry.async_get(source_device_id))
+        or helper_config_entry_id not in source_device.config_entries
+    ):
+        return
+
+    entity_registry = er.async_get(hass)
+    helper_entity_entries = er.async_entries_for_config_entry(
+        entity_registry, helper_config_entry_id
+    )
+
+    # Disconnect helper entities from the device to prevent them from
+    # being removed when the config entry link to the device is removed.
+    modified_helpers: list[er.RegistryEntry] = []
+    for helper in helper_entity_entries:
+        if helper.device_id != source_device_id:
+            continue
+        modified_helpers.append(helper)
+        entity_registry.async_update_entity(helper.entity_id, device_id=None)
+    # Remove the helper config entry from the device
+    device_registry.async_update_device(
+        source_device_id, remove_config_entry_id=helper_config_entry_id
+    )
+    # Connect the helper entity to the device
+    for helper in modified_helpers:
+        entity_registry.async_update_entity(
+            helper.entity_id, device_id=source_device_id
+        )

homeassistant/helpers/http.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-import asyncio
 from collections.abc import Awaitable, Callable
 from contextvars import ContextVar
 from http import HTTPStatus
+import inspect
 import logging
 from typing import Any, Final
 
@@ -45,7 +45,7 @@ def request_handler_factory(
     hass: HomeAssistant, view: HomeAssistantView, handler: Callable
 ) -> Callable[[web.Request], Awaitable[web.StreamResponse]]:
     """Wrap the handler classes."""
-    is_coroutinefunction = asyncio.iscoroutinefunction(handler)
+    is_coroutinefunction = inspect.iscoroutinefunction(handler)
     assert is_coroutinefunction or is_callback(handler), (
         "Handler should be a coroutine or a callback."
     )

homeassistant/helpers/llm.py

@@ -315,10 +315,23 @@ class IntentTool(Tool):
             assistant=llm_context.assistant,
             device_id=llm_context.device_id,
         )
-        response = intent_response.as_dict()
-        del response["language"]
-        del response["card"]
-        return response
+        return IntentResponseDict(intent_response)
+
+
+class IntentResponseDict(dict):
+    """Dictionary to represent an intent response resulting from a tool call."""
+
+    def __init__(self, intent_response: Any) -> None:
+        """Initialize the dictionary."""
+        if not isinstance(intent_response, intent.IntentResponse):
+            super().__init__(intent_response)
+            return
+
+        result = intent_response.as_dict()
+        del result["language"]
+        del result["card"]
+        super().__init__(result)
+        self.original = intent_response
 
 
 class NamespacedTool(Tool):
@@ -331,7 +344,7 @@ class NamespacedTool(Tool):
     def __init__(self, namespace: str, tool: Tool) -> None:
         """Init the class."""
         self.namespace = namespace
-        self.name = f"{namespace}.{tool.name}"
+        self.name = f"{namespace}__{tool.name}"
         self.description = tool.description
         self.parameters = tool.parameters
         self.tool = tool
@@ -458,7 +471,7 @@ class AssistAPI(API):
             api_prompt=self._async_get_api_prompt(llm_context, exposed_entities),
             llm_context=llm_context,
             tools=self._async_get_tools(llm_context, exposed_entities),
-            custom_serializer=_selector_serializer,
+            custom_serializer=selector_serializer,
         )
 
     @callback
@@ -701,7 +714,7 @@ def _get_exposed_entities(
     return data
 
 
-def _selector_serializer(schema: Any) -> Any:  # noqa: C901
+def selector_serializer(schema: Any) -> Any:  # noqa: C901
     """Convert selectors into OpenAPI schema."""
     if not isinstance(schema, selector.Selector):
         return UNSUPPORTED
@@ -777,7 +790,29 @@ def _selector_serializer(schema: Any) -> Any:  # noqa: C901
         return result
 
     if isinstance(schema, selector.ObjectSelector):
-        return {"type": "object", "additionalProperties": True}
+        result = {"type": "object"}
+        if fields := schema.config.get("fields"):
+            properties = {}
+            required = []
+            for field, field_schema in fields.items():
+                properties[field] = convert(
+                    selector.selector(field_schema["selector"]),
+                    custom_serializer=selector_serializer,
+                )
+                if field_schema.get("required"):
+                    required.append(field)
+            result["properties"] = properties
+
+            if required:
+                result["required"] = required
+        else:
+            result["additionalProperties"] = True
+        if schema.config.get("multiple"):
+            result = {
+                "type": "array",
+                "items": result,
+            }
+        return result
 
     if isinstance(schema, selector.SelectSelector):
         options = [
@@ -899,7 +934,7 @@ class ActionTool(Tool):
         """Init the class."""
         self._domain = domain
         self._action = action
-        self.name = f"{domain}.{action}"
+        self.name = f"{domain}__{action}"
         # Note: _get_cached_action_parameters only works for services which
         # add their description directly to the service description cache.
         # This is not the case for most services, but it is for scripts.

homeassistant/helpers/schema_config_entry_flow.py

@@ -95,6 +95,12 @@ class SchemaFlowFormStep(SchemaFlowStep):
     preview: str | None = None
     """Optional preview component."""
 
+    description_placeholders: (
+        Callable[[SchemaCommonFlowHandler], Coroutine[Any, Any, dict[str, str]]]
+        | UndefinedType
+    ) = UNDEFINED
+    """Optional property to populate description placeholders."""
+
 
 @dataclass(slots=True)
 class SchemaFlowMenuStep(SchemaFlowStep):
@@ -257,6 +263,10 @@ class SchemaCommonFlowHandler:
         if (data_schema := await self._get_schema(form_step)) is None:
             return await self._show_next_step_or_create_entry(form_step)
 
+        description_placeholders: dict[str, str] | None = None
+        if form_step.description_placeholders is not UNDEFINED:
+            description_placeholders = await form_step.description_placeholders(self)
+
         suggested_values: dict[str, Any] = {}
         if form_step.suggested_values is UNDEFINED:
             suggested_values = self._options
@@ -285,6 +295,7 @@ class SchemaCommonFlowHandler:
         return self._handler.async_show_form(
             step_id=next_step_id,
             data_schema=data_schema,
+            description_placeholders=description_placeholders,
             errors=errors,
             last_step=last_step,
             preview=form_step.preview,

homeassistant/helpers/selector.py

@@ -117,11 +117,8 @@ def _validate_supported_feature(supported_feature: str) -> int:
         raise vol.Invalid(f"Unknown supported feature '{supported_feature}'") from exc
 
 
-def _validate_supported_features(supported_features: int | list[str]) -> int:
-    """Validate a supported feature and resolve an enum string to its value."""
-
-    if isinstance(supported_features, int):
-        return supported_features
+def _validate_supported_features(supported_features: list[str]) -> int:
+    """Validate supported features and resolve enum strings to their value."""
 
     feature_mask = 0
 
@@ -160,6 +157,22 @@ ENTITY_FILTER_SELECTOR_CONFIG_SCHEMA = vol.Schema(
 )
 
 
+# Legacy entity selector config schema used directly under entity selectors
+# is provided for backwards compatibility and remains feature frozen.
+# New filtering features should be added under the `filter` key instead.
+# https://github.com/home-assistant/frontend/pull/15302
+LEGACY_ENTITY_SELECTOR_CONFIG_SCHEMA = vol.Schema(
+    {
+        # Integration that provided the entity
+        vol.Optional("integration"): str,
+        # Domain the entity belongs to
+        vol.Optional("domain"): vol.All(cv.ensure_list, [str]),
+        # Device class of the entity
+        vol.Optional("device_class"): vol.All(cv.ensure_list, [str]),
+    }
+)
+
+
 class EntityFilterSelectorConfig(TypedDict, total=False):
     """Class to represent a single entity selector config."""
 
@@ -179,10 +192,22 @@ DEVICE_FILTER_SELECTOR_CONFIG_SCHEMA = vol.Schema(
         vol.Optional("model"): str,
         # Model ID of device
         vol.Optional("model_id"): str,
-        # Device has to contain entities matching this selector
-        vol.Optional("entity"): vol.All(
-            cv.ensure_list, [ENTITY_FILTER_SELECTOR_CONFIG_SCHEMA]
-        ),
+    }
+)
+
+
+# Legacy device selector config schema used directly under device selectors
+# is provided for backwards compatibility and remains feature frozen.
+# New filtering features should be added under the `filter` key instead.
+# https://github.com/home-assistant/frontend/pull/15302
+LEGACY_DEVICE_SELECTOR_CONFIG_SCHEMA = vol.Schema(
+    {
+        # Integration linked to it with a config entry
+        vol.Optional("integration"): str,
+        # Manufacturer of device
+        vol.Optional("manufacturer"): str,
+        # Model of device
+        vol.Optional("model"): str,
     }
 )
 
@@ -550,49 +575,6 @@ class ConstantSelector(Selector[ConstantSelectorConfig]):
         return self.config["value"]
 
 
-class QrErrorCorrectionLevel(StrEnum):
-    """Possible error correction levels for QR code selector."""
-
-    LOW = "low"
-    MEDIUM = "medium"
-    QUARTILE = "quartile"
-    HIGH = "high"
-
-
-class QrCodeSelectorConfig(BaseSelectorConfig, total=False):
-    """Class to represent a QR code selector config."""
-
-    data: str
-    scale: int
-    error_correction_level: QrErrorCorrectionLevel
-
-
-@SELECTORS.register("qr_code")
-class QrCodeSelector(Selector[QrCodeSelectorConfig]):
-    """QR code selector."""
-
-    selector_type = "qr_code"
-
-    CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
-        {
-            vol.Required("data"): str,
-            vol.Optional("scale"): int,
-            vol.Optional("error_correction_level"): vol.All(
-                vol.Coerce(QrErrorCorrectionLevel), lambda val: val.value
-            ),
-        }
-    )
-
-    def __init__(self, config: QrCodeSelectorConfig) -> None:
-        """Instantiate a selector."""
-        super().__init__(config)
-
-    def __call__(self, data: Any) -> Any:
-        """Validate the passed selection."""
-        vol.Schema(vol.Any(str, None))(data)
-        return self.config["data"]
-
-
 class ConversationAgentSelectorConfig(BaseSelectorConfig, total=False):
     """Class to represent a conversation agent selector config."""
 
@@ -714,9 +696,13 @@ class DeviceSelector(Selector[DeviceSelectorConfig]):
     selector_type = "device"
 
     CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
-        DEVICE_FILTER_SELECTOR_CONFIG_SCHEMA.schema
+        LEGACY_DEVICE_SELECTOR_CONFIG_SCHEMA.schema
     ).extend(
         {
+            # Device has to contain entities matching this selector
+            vol.Optional("entity"): vol.All(
+                cv.ensure_list, [ENTITY_FILTER_SELECTOR_CONFIG_SCHEMA]
+            ),
             vol.Optional("multiple", default=False): cv.boolean,
             vol.Optional("filter"): vol.All(
                 cv.ensure_list,
@@ -784,6 +770,7 @@ class EntitySelectorConfig(BaseSelectorConfig, EntityFilterSelectorConfig, total
     exclude_entities: list[str]
     include_entities: list[str]
     multiple: bool
+    reorder: bool
     filter: EntityFilterSelectorConfig | list[EntityFilterSelectorConfig]
 
 
@@ -794,12 +781,13 @@ class EntitySelector(Selector[EntitySelectorConfig]):
     selector_type = "entity"
 
     CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
-        ENTITY_FILTER_SELECTOR_CONFIG_SCHEMA.schema
+        LEGACY_ENTITY_SELECTOR_CONFIG_SCHEMA.schema
     ).extend(
         {
             vol.Optional("exclude_entities"): [str],
             vol.Optional("include_entities"): [str],
             vol.Optional("multiple", default=False): cv.boolean,
+            vol.Optional("reorder", default=False): cv.boolean,
             vol.Optional("filter"): vol.All(
                 cv.ensure_list,
                 [ENTITY_FILTER_SELECTOR_CONFIG_SCHEMA],
@@ -841,6 +829,39 @@ class EntitySelector(Selector[EntitySelectorConfig]):
         return cast(list, vol.Schema([validate])(data))  # Output is a list
 
 
+class FileSelectorConfig(BaseSelectorConfig):
+    """Class to represent a file selector config."""
+
+    accept: str  # required
+
+
+@SELECTORS.register("file")
+class FileSelector(Selector[FileSelectorConfig]):
+    """Selector of a file."""
+
+    selector_type = "file"
+
+    CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
+        {
+            # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept
+            vol.Required("accept"): str,
+        }
+    )
+
+    def __init__(self, config: FileSelectorConfig) -> None:
+        """Instantiate a selector."""
+        super().__init__(config)
+
+    def __call__(self, data: Any) -> str:
+        """Validate the passed selection."""
+        if not isinstance(data, str):
+            raise vol.Invalid("Value should be a string")
+
+        UUID(data)
+
+        return data
+
+
 class FloorSelectorConfig(BaseSelectorConfig, total=False):
     """Class to represent an floor selector config."""
 
@@ -1043,9 +1064,19 @@ class MediaSelector(Selector[MediaSelectorConfig]):
         """Instantiate a selector."""
         super().__init__(config)
 
-    def __call__(self, data: Any) -> dict[str, float]:
+    def __call__(self, data: Any) -> dict[str, str]:
         """Validate the passed selection."""
-        media: dict[str, float] = self.DATA_SCHEMA(data)
+        schema = {
+            key: value
+            for key, value in self.DATA_SCHEMA.schema.items()
+            if key != "entity_id"
+        }
+
+        if "accept" not in self.config:
+            # If accept is not set, the entity_id field is required
+            schema[vol.Required("entity_id")] = cv.entity_id_or_uuid
+
+        media: dict[str, str] = vol.Schema(schema)(data)
         return media
 
 
@@ -1057,6 +1088,7 @@ class NumberSelectorConfig(BaseSelectorConfig, total=False):
     step: float | Literal["any"]
     unit_of_measurement: str
     mode: NumberSelectorMode
+    translation_key: str
 
 
 class NumberSelectorMode(StrEnum):
@@ -1068,10 +1100,12 @@ class NumberSelectorMode(StrEnum):
 
 def validate_slider(data: Any) -> Any:
     """Validate configuration."""
-    if data["mode"] == "box":
-        return data
+    has_min_max = "min" in data and "max" in data
+
+    if "mode" not in data:
+        data["mode"] = "slider" if has_min_max else "box"
 
-    if "min" not in data or "max" not in data:
+    if data["mode"] == "slider" and not has_min_max:
         raise vol.Invalid("min and max are required in slider mode")
 
     return data
@@ -1094,9 +1128,10 @@ class NumberSelector(Selector[NumberSelectorConfig]):
                     "any", vol.All(vol.Coerce(float), vol.Range(min=1e-3))
                 ),
                 vol.Optional(CONF_UNIT_OF_MEASUREMENT): str,
-                vol.Optional(CONF_MODE, default=NumberSelectorMode.SLIDER): vol.All(
+                vol.Optional(CONF_MODE): vol.All(
                     vol.Coerce(NumberSelectorMode), lambda val: val.value
                 ),
+                vol.Optional("translation_key"): str,
             }
         ),
         validate_slider,
@@ -1168,6 +1203,49 @@ class ObjectSelector(Selector[ObjectSelectorConfig]):
         return data
 
 
+class QrErrorCorrectionLevel(StrEnum):
+    """Possible error correction levels for QR code selector."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    QUARTILE = "quartile"
+    HIGH = "high"
+
+
+class QrCodeSelectorConfig(BaseSelectorConfig, total=False):
+    """Class to represent a QR code selector config."""
+
+    data: str
+    scale: int
+    error_correction_level: QrErrorCorrectionLevel
+
+
+@SELECTORS.register("qr_code")
+class QrCodeSelector(Selector[QrCodeSelectorConfig]):
+    """QR code selector."""
+
+    selector_type = "qr_code"
+
+    CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
+        {
+            vol.Required("data"): str,
+            vol.Optional("scale"): int,
+            vol.Optional("error_correction_level"): vol.All(
+                vol.Coerce(QrErrorCorrectionLevel), lambda val: val.value
+            ),
+        }
+    )
+
+    def __init__(self, config: QrCodeSelectorConfig) -> None:
+        """Instantiate a selector."""
+        super().__init__(config)
+
+    def __call__(self, data: Any) -> Any:
+        """Validate the passed selection."""
+        vol.Schema(vol.Any(str, None))(data)
+        return self.config["data"]
+
+
 select_option = vol.All(
     dict,
     vol.Schema(
@@ -1250,6 +1328,41 @@ class SelectSelector(Selector[SelectSelectorConfig]):
         return [parent_schema(vol.Schema(str)(val)) for val in data]
 
 
+class StateSelectorConfig(BaseSelectorConfig, total=False):
+    """Class to represent an state selector config."""
+
+    entity_id: str
+    hide_states: list[str]
+
+
+@SELECTORS.register("state")
+class StateSelector(Selector[StateSelectorConfig]):
+    """Selector for an entity state."""
+
+    selector_type = "state"
+
+    CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
+        {
+            vol.Optional("entity_id"): cv.entity_id,
+            vol.Optional("hide_states"): [str],
+            # The attribute to filter on, is currently deliberately not
+            # configurable/exposed. We are considering separating state
+            # selectors into two types: one for state and one for attribute.
+            # Limiting the public use, prevents breaking changes in the future.
+            # vol.Optional("attribute"): str,
+        }
+    )
+
+    def __init__(self, config: StateSelectorConfig) -> None:
+        """Instantiate a selector."""
+        super().__init__(config)
+
+    def __call__(self, data: Any) -> str:
+        """Validate the passed selection."""
+        state: str = vol.Schema(str)(data)
+        return state
+
+
 class StatisticSelectorConfig(BaseSelectorConfig, total=False):
     """Class to represent a statistic selector config."""
 
@@ -1290,39 +1403,6 @@ class TargetSelectorConfig(BaseSelectorConfig, total=False):
     device: DeviceFilterSelectorConfig | list[DeviceFilterSelectorConfig]
 
 
-class StateSelectorConfig(BaseSelectorConfig, total=False):
-    """Class to represent an state selector config."""
-
-    entity_id: Required[str]
-
-
-@SELECTORS.register("state")
-class StateSelector(Selector[StateSelectorConfig]):
-    """Selector for an entity state."""
-
-    selector_type = "state"
-
-    CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
-        {
-            vol.Required("entity_id"): cv.entity_id,
-            # The attribute to filter on, is currently deliberately not
-            # configurable/exposed. We are considering separating state
-            # selectors into two types: one for state and one for attribute.
-            # Limiting the public use, prevents breaking changes in the future.
-            # vol.Optional("attribute"): str,
-        }
-    )
-
-    def __init__(self, config: StateSelectorConfig) -> None:
-        """Instantiate a selector."""
-        super().__init__(config)
-
-    def __call__(self, data: Any) -> str:
-        """Validate the passed selection."""
-        state: str = vol.Schema(str)(data)
-        return state
-
-
 @SELECTORS.register("target")
 class TargetSelector(Selector[TargetSelectorConfig]):
     """Selector of a target value (area ID, device ID, entity ID etc).
@@ -1512,39 +1592,6 @@ class TriggerSelector(Selector[TriggerSelectorConfig]):
         return vol.Schema(cv.TRIGGER_SCHEMA)(data)
 
 
-class FileSelectorConfig(BaseSelectorConfig):
-    """Class to represent a file selector config."""
-
-    accept: str  # required
-
-
-@SELECTORS.register("file")
-class FileSelector(Selector[FileSelectorConfig]):
-    """Selector of a file."""
-
-    selector_type = "file"
-
-    CONFIG_SCHEMA = BASE_SELECTOR_CONFIG_SCHEMA.extend(
-        {
-            # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept
-            vol.Required("accept"): str,
-        }
-    )
-
-    def __init__(self, config: FileSelectorConfig) -> None:
-        """Instantiate a selector."""
-        super().__init__(config)
-
-    def __call__(self, data: Any) -> str:
-        """Validate the passed selection."""
-        if not isinstance(data, str):
-            raise vol.Invalid("Value should be a string")
-
-        UUID(data)
-
-        return data
-
-
 dumper.add_representer(
     Selector,
     lambda dumper, value: dumper.represent_odict(