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

homeassistant/helpers/target.py

@@ -0,0 +1,359 @@
+"""Helpers for dealing with entity targets."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import dataclasses
+import logging
+from logging import Logger
+from typing import Any, TypeGuard
+
+from homeassistant.const import (
+    ATTR_AREA_ID,
+    ATTR_DEVICE_ID,
+    ATTR_ENTITY_ID,
+    ATTR_FLOOR_ID,
+    ATTR_LABEL_ID,
+    ENTITY_MATCH_NONE,
+)
+from homeassistant.core import (
+    CALLBACK_TYPE,
+    Event,
+    EventStateChangedData,
+    HomeAssistant,
+    callback,
+)
+from homeassistant.exceptions import HomeAssistantError
+
+from . import (
+    area_registry as ar,
+    config_validation as cv,
+    device_registry as dr,
+    entity_registry as er,
+    floor_registry as fr,
+    group,
+    label_registry as lr,
+)
+from .event import async_track_state_change_event
+from .typing import ConfigType
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class TargetStateChangedData:
+    """Data for state change events related to targets."""
+
+    state_change_event: Event[EventStateChangedData]
+    targeted_entity_ids: set[str]
+
+
+def _has_match(ids: str | list[str] | None) -> TypeGuard[str | list[str]]:
+    """Check if ids can match anything."""
+    return ids not in (None, ENTITY_MATCH_NONE)
+
+
+class TargetSelectorData:
+    """Class to hold data of target selector."""
+
+    __slots__ = ("area_ids", "device_ids", "entity_ids", "floor_ids", "label_ids")
+
+    def __init__(self, config: ConfigType) -> None:
+        """Extract ids from the config."""
+        entity_ids: str | list | None = config.get(ATTR_ENTITY_ID)
+        device_ids: str | list | None = config.get(ATTR_DEVICE_ID)
+        area_ids: str | list | None = config.get(ATTR_AREA_ID)
+        floor_ids: str | list | None = config.get(ATTR_FLOOR_ID)
+        label_ids: str | list | None = config.get(ATTR_LABEL_ID)
+
+        self.entity_ids = (
+            set(cv.ensure_list(entity_ids)) if _has_match(entity_ids) else set()
+        )
+        self.device_ids = (
+            set(cv.ensure_list(device_ids)) if _has_match(device_ids) else set()
+        )
+        self.area_ids = set(cv.ensure_list(area_ids)) if _has_match(area_ids) else set()
+        self.floor_ids = (
+            set(cv.ensure_list(floor_ids)) if _has_match(floor_ids) else set()
+        )
+        self.label_ids = (
+            set(cv.ensure_list(label_ids)) if _has_match(label_ids) else set()
+        )
+
+    @property
+    def has_any_selector(self) -> bool:
+        """Determine if any selectors are present."""
+        return bool(
+            self.entity_ids
+            or self.device_ids
+            or self.area_ids
+            or self.floor_ids
+            or self.label_ids
+        )
+
+
+@dataclasses.dataclass(slots=True)
+class SelectedEntities:
+    """Class to hold the selected entities."""
+
+    # Entities that were explicitly mentioned.
+    referenced: set[str] = dataclasses.field(default_factory=set)
+
+    # Entities that were referenced via device/area/floor/label ID.
+    # Should not trigger a warning when they don't exist.
+    indirectly_referenced: set[str] = dataclasses.field(default_factory=set)
+
+    # Referenced items that could not be found.
+    missing_devices: set[str] = dataclasses.field(default_factory=set)
+    missing_areas: set[str] = dataclasses.field(default_factory=set)
+    missing_floors: set[str] = dataclasses.field(default_factory=set)
+    missing_labels: set[str] = dataclasses.field(default_factory=set)
+
+    referenced_devices: set[str] = dataclasses.field(default_factory=set)
+    referenced_areas: set[str] = dataclasses.field(default_factory=set)
+
+    def log_missing(self, missing_entities: set[str], logger: Logger) -> None:
+        """Log about missing items."""
+        parts = []
+        for label, items in (
+            ("floors", self.missing_floors),
+            ("areas", self.missing_areas),
+            ("devices", self.missing_devices),
+            ("entities", missing_entities),
+            ("labels", self.missing_labels),
+        ):
+            if items:
+                parts.append(f"{label} {', '.join(sorted(items))}")
+
+        if not parts:
+            return
+
+        logger.warning(
+            "Referenced %s are missing or not currently available",
+            ", ".join(parts),
+        )
+
+
+def async_extract_referenced_entity_ids(
+    hass: HomeAssistant, selector_data: TargetSelectorData, expand_group: bool = True
+) -> SelectedEntities:
+    """Extract referenced entity IDs from a target selector."""
+    selected = SelectedEntities()
+
+    if not selector_data.has_any_selector:
+        return selected
+
+    entity_ids: set[str] | list[str] = selector_data.entity_ids
+    if expand_group:
+        entity_ids = group.expand_entity_ids(hass, entity_ids)
+
+    selected.referenced.update(entity_ids)
+
+    if (
+        not selector_data.device_ids
+        and not selector_data.area_ids
+        and not selector_data.floor_ids
+        and not selector_data.label_ids
+    ):
+        return selected
+
+    entities = er.async_get(hass).entities
+    dev_reg = dr.async_get(hass)
+    area_reg = ar.async_get(hass)
+
+    if selector_data.floor_ids:
+        floor_reg = fr.async_get(hass)
+        for floor_id in selector_data.floor_ids:
+            if floor_id not in floor_reg.floors:
+                selected.missing_floors.add(floor_id)
+
+    for area_id in selector_data.area_ids:
+        if area_id not in area_reg.areas:
+            selected.missing_areas.add(area_id)
+
+    for device_id in selector_data.device_ids:
+        if device_id not in dev_reg.devices:
+            selected.missing_devices.add(device_id)
+
+    if selector_data.label_ids:
+        label_reg = lr.async_get(hass)
+        for label_id in selector_data.label_ids:
+            if label_id not in label_reg.labels:
+                selected.missing_labels.add(label_id)
+
+            for entity_entry in entities.get_entries_for_label(label_id):
+                if (
+                    entity_entry.entity_category is None
+                    and entity_entry.hidden_by is None
+                ):
+                    selected.indirectly_referenced.add(entity_entry.entity_id)
+
+            for device_entry in dev_reg.devices.get_devices_for_label(label_id):
+                selected.referenced_devices.add(device_entry.id)
+
+            for area_entry in area_reg.areas.get_areas_for_label(label_id):
+                selected.referenced_areas.add(area_entry.id)
+
+    # Find areas for targeted floors
+    if selector_data.floor_ids:
+        selected.referenced_areas.update(
+            area_entry.id
+            for floor_id in selector_data.floor_ids
+            for area_entry in area_reg.areas.get_areas_for_floor(floor_id)
+        )
+
+    selected.referenced_areas.update(selector_data.area_ids)
+    selected.referenced_devices.update(selector_data.device_ids)
+
+    if not selected.referenced_areas and not selected.referenced_devices:
+        return selected
+
+    # Add indirectly referenced by device
+    selected.indirectly_referenced.update(
+        entry.entity_id
+        for device_id in selected.referenced_devices
+        for entry in entities.get_entries_for_device_id(device_id)
+        # Do not add entities which are hidden or which are config
+        # or diagnostic entities.
+        if (entry.entity_category is None and entry.hidden_by is None)
+    )
+
+    # Find devices for targeted areas
+    referenced_devices_by_area: set[str] = set()
+    if selected.referenced_areas:
+        for area_id in selected.referenced_areas:
+            referenced_devices_by_area.update(
+                device_entry.id
+                for device_entry in dev_reg.devices.get_devices_for_area_id(area_id)
+            )
+    selected.referenced_devices.update(referenced_devices_by_area)
+
+    # Add indirectly referenced by area
+    selected.indirectly_referenced.update(
+        entry.entity_id
+        for area_id in selected.referenced_areas
+        # The entity's area matches a targeted area
+        for entry in entities.get_entries_for_area_id(area_id)
+        # Do not add entities which are hidden or which are config
+        # or diagnostic entities.
+        if entry.entity_category is None and entry.hidden_by is None
+    )
+    # Add indirectly referenced by area through device
+    selected.indirectly_referenced.update(
+        entry.entity_id
+        for device_id in referenced_devices_by_area
+        for entry in entities.get_entries_for_device_id(device_id)
+        # Do not add entities which are hidden or which are config
+        # or diagnostic entities.
+        if (
+            entry.entity_category is None
+            and entry.hidden_by is None
+            and (
+                # The entity's device matches a device referenced
+                # by an area and the entity
+                # has no explicitly set area
+                not entry.area_id
+            )
+        )
+    )
+
+    return selected
+
+
+class TargetStateChangeTracker:
+    """Helper class to manage state change tracking for targets."""
+
+    def __init__(
+        self,
+        hass: HomeAssistant,
+        selector_data: TargetSelectorData,
+        action: Callable[[TargetStateChangedData], Any],
+    ) -> None:
+        """Initialize the state change tracker."""
+        self._hass = hass
+        self._selector_data = selector_data
+        self._action = action
+
+        self._state_change_unsub: CALLBACK_TYPE | None = None
+        self._registry_unsubs: list[CALLBACK_TYPE] = []
+
+    def async_setup(self) -> Callable[[], None]:
+        """Set up the state change tracking."""
+        self._setup_registry_listeners()
+        self._track_entities_state_change()
+        return self._unsubscribe
+
+    def _track_entities_state_change(self) -> None:
+        """Set up state change tracking for currently selected entities."""
+        selected = async_extract_referenced_entity_ids(
+            self._hass, self._selector_data, expand_group=False
+        )
+
+        tracked_entities = selected.referenced.union(selected.indirectly_referenced)
+
+        @callback
+        def state_change_listener(event: Event[EventStateChangedData]) -> None:
+            """Handle state change events."""
+            if (
+                event.data["entity_id"] in selected.referenced
+                or event.data["entity_id"] in selected.indirectly_referenced
+            ):
+                self._action(TargetStateChangedData(event, tracked_entities))
+
+        _LOGGER.debug("Tracking state changes for entities: %s", tracked_entities)
+        self._state_change_unsub = async_track_state_change_event(
+            self._hass, tracked_entities, state_change_listener
+        )
+
+    def _setup_registry_listeners(self) -> None:
+        """Set up listeners for registry changes that require resubscription."""
+
+        @callback
+        def resubscribe_state_change_event(event: Event[Any] | None = None) -> None:
+            """Resubscribe to state change events when registry changes."""
+            if self._state_change_unsub:
+                self._state_change_unsub()
+            self._track_entities_state_change()
+
+        # Subscribe to registry updates that can change the entities to track:
+        # - Entity registry: entity added/removed; entity labels changed; entity area changed.
+        # - Device registry: device labels changed; device area changed.
+        # - Area registry: area floor changed.
+        #
+        # We don't track other registries (like floor or label registries) because their
+        # changes don't affect which entities are tracked.
+        self._registry_unsubs = [
+            self._hass.bus.async_listen(
+                er.EVENT_ENTITY_REGISTRY_UPDATED, resubscribe_state_change_event
+            ),
+            self._hass.bus.async_listen(
+                dr.EVENT_DEVICE_REGISTRY_UPDATED, resubscribe_state_change_event
+            ),
+            self._hass.bus.async_listen(
+                ar.EVENT_AREA_REGISTRY_UPDATED, resubscribe_state_change_event
+            ),
+        ]
+
+    def _unsubscribe(self) -> None:
+        """Unsubscribe from all events."""
+        for registry_unsub in self._registry_unsubs:
+            registry_unsub()
+        self._registry_unsubs.clear()
+        if self._state_change_unsub:
+            self._state_change_unsub()
+            self._state_change_unsub = None
+
+
+def async_track_target_selector_state_change_event(
+    hass: HomeAssistant,
+    target_selector_config: ConfigType,
+    action: Callable[[TargetStateChangedData], Any],
+) -> CALLBACK_TYPE:
+    """Track state changes for entities referenced directly or indirectly in a target selector."""
+    selector_data = TargetSelectorData(target_selector_config)
+    if not selector_data.has_any_selector:
+        raise HomeAssistantError(
+            f"Target selector {target_selector_config} does not have any selectors defined"
+        )
+    tracker = TargetStateChangeTracker(hass, selector_data, action)
+    return tracker.async_setup()

homeassistant/helpers/template.py

@@ -2030,7 +2030,7 @@ def apply(value, fn, *args, **kwargs):
 def as_function(macro: jinja2.runtime.Macro) -> Callable[..., Any]:
     """Turn a macro with a 'returns' keyword argument into a function that returns what that argument is called with."""
 
-    def wrapper(value, *args, **kwargs):
+    def wrapper(*args, **kwargs):
         return_value = None
 
         def returns(value):
@@ -2039,7 +2039,7 @@ def as_function(macro: jinja2.runtime.Macro) -> Callable[..., Any]:
             return value
 
         # Call the callable with the value and other args
-        macro(value, *args, **kwargs, returns=returns)
+        macro(*args, **kwargs, returns=returns)
         return return_value
 
     # Remove "macro_" from the macro's name to avoid confusion in the wrapper's name

homeassistant/helpers/trigger.py

@@ -8,6 +8,7 @@ from collections import defaultdict
 from collections.abc import Callable, Coroutine, Iterable
 from dataclasses import dataclass, field
 import functools
+import inspect
 import logging
 from typing import TYPE_CHECKING, Any, Protocol, TypedDict, cast
 
@@ -18,6 +19,7 @@ from homeassistant.const import (
     CONF_ENABLED,
     CONF_ID,
     CONF_PLATFORM,
+    CONF_SELECTOR,
     CONF_VARIABLES,
 )
 from homeassistant.core import (
@@ -40,8 +42,9 @@ from homeassistant.util.hass_dict import HassKey
 from homeassistant.util.yaml import load_yaml_dict
 from homeassistant.util.yaml.loader import JSON_TYPE
 
-from . import config_validation as cv
+from . import config_validation as cv, selector
 from .integration_platform import async_process_integration_platforms
+from .selector import TargetSelector
 from .template import Template
 from .typing import ConfigType, TemplateVarsType
 
@@ -72,12 +75,15 @@ TRIGGERS: HassKey[dict[str, str]] = HassKey("triggers")
 # Basic schemas to sanity check the trigger descriptions,
 # full validation is done by hassfest.triggers
 _FIELD_SCHEMA = vol.Schema(
-    {},
+    {
+        vol.Optional(CONF_SELECTOR): selector.validate_selector,
+    },
     extra=vol.ALLOW_EXTRA,
 )
 
 _TRIGGER_SCHEMA = vol.Schema(
     {
+        vol.Optional("target"): vol.Any(TargetSelector.CONFIG_SCHEMA, None),
         vol.Optional("fields"): vol.Schema({str: _FIELD_SCHEMA}),
     },
     extra=vol.ALLOW_EXTRA,
@@ -147,11 +153,15 @@ async def _register_trigger_platform(
         )
         return
 
-    tasks: list[asyncio.Task[None]] = [
-        create_eager_task(listener(new_triggers))
-        for listener in hass.data[TRIGGER_PLATFORM_SUBSCRIPTIONS]
-    ]
-    await asyncio.gather(*tasks)
+    # We don't use gather here because gather adds additional overhead
+    # when wrapping each coroutine in a task, and we expect our listeners
+    # to call trigger.async_get_all_descriptions which will only yield
+    # the first time it's called, after that it returns cached data.
+    for listener in hass.data[TRIGGER_PLATFORM_SUBSCRIPTIONS]:
+        try:
+            await listener(new_triggers)
+        except Exception:
+            _LOGGER.exception("Error while notifying trigger platform listener")
 
 
 class Trigger(abc.ABC):
@@ -403,7 +413,7 @@ def _trigger_action_wrapper(
         check_func = check_func.func
 
     wrapper_func: Callable[..., Any] | Callable[..., Coroutine[Any, Any, Any]]
-    if asyncio.iscoroutinefunction(check_func):
+    if inspect.iscoroutinefunction(check_func):
         async_action = cast(Callable[..., Coroutine[Any, Any, Any]], action)
 
         @functools.wraps(async_action)

homeassistant/helpers/trigger_template_entity.py

@@ -13,8 +13,10 @@ from homeassistant.components.sensor import (
     CONF_STATE_CLASS,
     DEVICE_CLASSES_SCHEMA,
     STATE_CLASSES_SCHEMA,
+    SensorDeviceClass,
     SensorEntity,
 )
+from homeassistant.components.sensor.helpers import async_parse_date_datetime
 from homeassistant.const import (
     ATTR_ENTITY_PICTURE,
     ATTR_FRIENDLY_NAME,
@@ -389,3 +391,20 @@ class ManualTriggerSensorEntity(ManualTriggerEntity, SensorEntity):
         ManualTriggerEntity.__init__(self, hass, config)
         self._attr_native_unit_of_measurement = config.get(CONF_UNIT_OF_MEASUREMENT)
         self._attr_state_class = config.get(CONF_STATE_CLASS)
+
+    @callback
+    def _set_native_value_with_possible_timestamp(self, value: Any) -> None:
+        """Set native value with possible timestamp.
+
+        If self.device_class is `date` or `timestamp`,
+        it will try to parse the value to a date/datetime object.
+        """
+        if self.device_class not in (
+            SensorDeviceClass.DATE,
+            SensorDeviceClass.TIMESTAMP,
+        ):
+            self._attr_native_value = value
+        elif value is not None:
+            self._attr_native_value = async_parse_date_datetime(
+                value, self.entity_id, self.device_class
+            )

homeassistant/helpers/update_coordinator.py

@@ -84,9 +84,19 @@ class DataUpdateCoordinator(BaseDataUpdateCoordinatorProtocol, Generic[_DataT]):
         self.update_interval = update_interval
         self._shutdown_requested = False
         if config_entry is UNDEFINED:
+            # late import to avoid circular imports
+            from . import frame  # noqa: PLC0415
+
+            # It is not planned to enforce this for custom integrations.
+            # see https://github.com/home-assistant/core/pull/138161#discussion_r1958184241
+            frame.report_usage(
+                "relies on ContextVar, but should pass the config entry explicitly.",
+                core_behavior=frame.ReportBehavior.ERROR,
+                custom_integration_behavior=frame.ReportBehavior.IGNORE,
+                breaks_in_ha_version="2026.8",
+            )
+
             self.config_entry = config_entries.current_entry.get()
-            # This should be deprecated once all core integrations are updated
-            # to pass in the config entry explicitly.
         else:
             self.config_entry = config_entry
         self.always_update = always_update

homeassistant/loader.py

@@ -10,7 +10,6 @@ import asyncio
 from collections.abc import Callable, Iterable
 from contextlib import suppress
 from dataclasses import dataclass
-import functools as ft
 import importlib
 import logging
 import os
@@ -67,6 +66,7 @@ _LOGGER = logging.getLogger(__name__)
 #
 BASE_PRELOAD_PLATFORMS = [
     "backup",
+    "condition",
     "config",
     "config_flow",
     "diagnostics",
@@ -857,6 +857,11 @@ class Integration:
         # True.
         return self.manifest.get("import_executor", True)
 
+    @cached_property
+    def has_conditions(self) -> bool:
+        """Return if the integration has conditions."""
+        return "conditions.yaml" in self._top_level_files
+
     @cached_property
     def has_services(self) -> bool:
         """Return if the integration has services."""
@@ -1644,77 +1649,6 @@ class CircularDependency(LoaderError):
         self.args[1].insert(0, domain)
 
 
-def _load_file(
-    hass: HomeAssistant, comp_or_platform: str, base_paths: list[str]
-) -> ComponentProtocol | None:
-    """Try to load specified file.
-
-    Looks in config dir first, then built-in components.
-    Only returns it if also found to be valid.
-    Async friendly.
-    """
-    cache = hass.data[DATA_COMPONENTS]
-    if module := cache.get(comp_or_platform):
-        return cast(ComponentProtocol, module)
-
-    for path in (f"{base}.{comp_or_platform}" for base in base_paths):
-        try:
-            module = importlib.import_module(path)
-
-            # In Python 3 you can import files from directories that do not
-            # contain the file __init__.py. A directory is a valid module if
-            # it contains a file with the .py extension. In this case Python
-            # will succeed in importing the directory as a module and call it
-            # a namespace. We do not care about namespaces.
-            # This prevents that when only
-            # custom_components/switch/some_platform.py exists,
-            # the import custom_components.switch would succeed.
-            # __file__ was unset for namespaces before Python 3.7
-            if getattr(module, "__file__", None) is None:
-                continue
-
-            cache[comp_or_platform] = module
-
-            return cast(ComponentProtocol, module)
-
-        except ImportError as err:
-            # This error happens if for example custom_components/switch
-            # exists and we try to load switch.demo.
-            # Ignore errors for custom_components, custom_components.switch
-            # and custom_components.switch.demo.
-            white_listed_errors = []
-            parts = []
-            for part in path.split("."):
-                parts.append(part)
-                white_listed_errors.append(f"No module named '{'.'.join(parts)}'")
-
-            if str(err) not in white_listed_errors:
-                _LOGGER.exception(
-                    "Error loading %s. Make sure all dependencies are installed", path
-                )
-
-    return None
-
-
-class ModuleWrapper:
-    """Class to wrap a Python module and auto fill in hass argument."""
-
-    def __init__(self, hass: HomeAssistant, module: ComponentProtocol) -> None:
-        """Initialize the module wrapper."""
-        self._hass = hass
-        self._module = module
-
-    def __getattr__(self, attr: str) -> Any:
-        """Fetch an attribute."""
-        value = getattr(self._module, attr)
-
-        if hasattr(value, "__bind_hass"):
-            value = ft.partial(value, self._hass)
-
-        setattr(self, attr, value)
-        return value
-
-
 def bind_hass[_CallableT: Callable[..., Any]](func: _CallableT) -> _CallableT:
     """Decorate function to indicate that first argument is hass.
 
@@ -1738,13 +1672,6 @@ def _async_mount_config_dir(hass: HomeAssistant) -> None:
     sys.path_importer_cache.pop(hass.config.config_dir, None)
 
 
-def _lookup_path(hass: HomeAssistant) -> list[str]:
-    """Return the lookup paths for legacy lookups."""
-    if hass.config.recovery_mode or hass.config.safe_mode:
-        return [PACKAGE_BUILTIN]
-    return [PACKAGE_CUSTOM_COMPONENTS, PACKAGE_BUILTIN]
-
-
 def is_component_module_loaded(hass: HomeAssistant, module: str) -> bool:
     """Test if a component module is loaded."""
     return module in hass.data[DATA_COMPONENTS]
@@ -1789,6 +1716,13 @@ def async_get_issue_tracker(
         # If we know nothing about the integration, suggest opening an issue on HA core
         return issue_tracker
 
+    if module and not integration_domain:
+        # If we only have a module, we can try to get the integration domain from it
+        if module.startswith("custom_components."):
+            integration_domain = module.split(".")[1]
+        elif module.startswith("homeassistant.components."):
+            integration_domain = module.split(".")[2]
+
     if not integration:
         integration = async_get_issue_integration(hass, integration_domain)