Improve docstring

homeassistant/helpers/entity.py

@@ -25,6 +25,7 @@ from homeassistant.const import (
     ATTR_ASSUMED_STATE,
     ATTR_ATTRIBUTION,
     ATTR_DEVICE_CLASS,
+    ATTR_ENTITY_ID,
     ATTR_ENTITY_PICTURE,
     ATTR_FRIENDLY_NAME,
     ATTR_ICON,
@@ -526,6 +527,9 @@ class Entity(
     __capabilities_updated_at_reported: bool = False
     __remove_future: asyncio.Future[None] | None = None
 
+    # Remember we keep track of included entities
+    __init_track_included_entities: bool = False
+
     # Entity Properties
     _attr_assumed_state: bool = False
     _attr_attribution: str | None = None
@@ -541,6 +545,8 @@ class Entity(
     _attr_extra_state_attributes: dict[str, Any]
     _attr_force_update: bool
     _attr_icon: str | None
+    _attr_included_entities: list[str]
+    _attr_included_unique_ids: list[str]
     _attr_name: str | None
     _attr_should_poll: bool = True
     _attr_state: StateType = STATE_UNKNOWN
@@ -1087,6 +1093,8 @@ class Entity(
         available = self.available  # only call self.available once per update cycle
         state = self._stringify_state(available)
         if available:
+            if hasattr(self, "_attr_included_entities"):
+                attr[ATTR_ENTITY_ID] = self._attr_included_entities.copy()
             if state_attributes := self.state_attributes:
                 attr |= state_attributes
             if extra_state_attributes := self.extra_state_attributes:
@@ -1378,6 +1386,7 @@ class Entity(
         """Finish adding an entity to a platform."""
         await self.async_internal_added_to_hass()
         await self.async_added_to_hass()
+        self.async_set_included_entities()
         self._platform_state = EntityPlatformState.ADDED
         self.async_write_ha_state()
 
@@ -1635,6 +1644,59 @@ class Entity(
             self.hass, integration_domain=platform_name, module=type(self).__module__
         )
 
+    @callback
+    def async_set_included_entities(self) -> None:
+        """Set the list of included entities identified by their unique IDs.
+
+        Integrations need to call this when the list of included unique IDs changes.
+        """
+        if not self.included_unique_ids:
+            return
+        entity_registry = er.async_get(self.hass)
+        assert self.entity_id is not None
+
+        def _update_group_entity_ids() -> None:
+            self._attr_included_entities = []
+            for included_id in self.included_unique_ids:
+                if entity_id := entity_registry.async_get_entity_id(
+                    self.platform.domain, self.platform.platform_name, included_id
+                ):
+                    self._attr_included_entities.append(entity_id)
+
+        async def _handle_entity_registry_updated(event: Event[Any]) -> None:
+            """Handle registry create or update event."""
+            if (
+                event.data["action"] in {"create", "update"}
+                and (entry := entity_registry.async_get(event.data["entity_id"]))
+                and entry.unique_id in self.included_unique_ids
+            ) or (
+                event.data["action"] == "remove"
+                and hasattr(self, "_attr_included_entities")
+                and event.data["entity_id"] in self._attr_included_entities
+            ):
+                _update_group_entity_ids()
+                self.async_write_ha_state()
+
+        if not self.__init_track_included_entities:
+            self.async_on_remove(
+                self.hass.bus.async_listen(
+                    er.EVENT_ENTITY_REGISTRY_UPDATED,
+                    _handle_entity_registry_updated,
+                )
+            )
+            self.__init_track_included_entities = True
+        _update_group_entity_ids()
+
+    @property
+    def included_unique_ids(self) -> list[str]:
+        """Return the list of unique IDs if the entity represents a group.
+
+        The corresponding entities will be shown as members in the UI.
+        """
+        if hasattr(self, "_attr_included_unique_ids"):
+            return self._attr_included_unique_ids
+        return []
+
 
 class ToggleEntityDescription(EntityDescription, frozen_or_thawed=True):
     """A class that describes toggle entities."""

tests/helpers/test_entity.py

@@ -6,7 +6,7 @@ import dataclasses
 from datetime import timedelta
 import logging
 import threading
-from typing import Any
+from typing import Any, final
 from unittest.mock import MagicMock, PropertyMock, patch
 
 from freezegun.api import FrozenDateTimeFactory
@@ -20,6 +20,7 @@ from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import (
     ATTR_ATTRIBUTION,
     ATTR_DEVICE_CLASS,
+    ATTR_ENTITY_ID,
     ATTR_FRIENDLY_NAME,
     STATE_UNAVAILABLE,
     STATE_UNKNOWN,
@@ -1878,6 +1879,7 @@ async def test_change_entity_id(
             self.remove_calls = []
 
         async def async_added_to_hass(self):
+            await super().async_added_to_hass()
             self.added_calls.append(None)
             self.async_on_remove(lambda: result.append(1))
 
@@ -2896,3 +2898,107 @@ async def test_platform_state_write_from_init_unique_id(
     # The early attempt to write is interpreted as a unique ID collision
     assert "Platform test_platform does not generate unique IDs." in caplog.text
     assert "Entity id already exists - ignoring: test.test" not in caplog.text
+
+
+async def test_included_entities(
+    hass: HomeAssistant,
+    entity_registry: er.EntityRegistry,
+) -> None:
+    """Test included entities are exposed via the entity_id attribute."""
+
+    entity_registry.async_get_or_create(
+        domain="hello",
+        platform="test",
+        unique_id="very_unique_oceans",
+        suggested_object_id="oceans",
+    )
+    entity_registry.async_get_or_create(
+        domain="hello",
+        platform="test",
+        unique_id="very_unique_continents",
+        suggested_object_id="continents",
+    )
+    entity_registry.async_get_or_create(
+        domain="hello",
+        platform="test",
+        unique_id="very_unique_moon",
+        suggested_object_id="moon",
+    )
+
+    class MockHelloBaseClass(entity.Entity):
+        """Domain base entity platform domain Hello."""
+
+        @final
+        @property
+        def state_attributes(self) -> dict[str, Any]:
+            """Return the state attributes."""
+            return {"extra": "beer"}
+
+    class MockHelloIncludedEntitiesClass(MockHelloBaseClass, entity.Entity):
+        """Mock hello grouped entity class for a test integration."""
+
+    platform = MockEntityPlatform(hass, domain="hello", platform_name="test")
+    mock_entity = MockHelloIncludedEntitiesClass()
+    mock_entity.hass = hass
+    mock_entity.entity_id = "hello.universe"
+    mock_entity.unique_id = "very_unique_universe"
+    mock_entity._attr_included_unique_ids = [
+        "very_unique_continents",
+        "very_unique_oceans",
+    ]
+
+    await platform.async_add_entities([mock_entity])
+
+    # Initiate mock grouped entity for hello domain
+    mock_entity.async_schedule_update_ha_state(True)
+    await hass.async_block_till_done()
+
+    state = hass.states.get(mock_entity.entity_id)
+    assert state.attributes.get(ATTR_ENTITY_ID) == ["hello.continents", "hello.oceans"]
+
+    # Add an entity to the group of included entities
+    mock_entity._attr_included_unique_ids = [
+        "very_unique_continents",
+        "very_unique_moon",
+        "very_unique_oceans",
+    ]
+    mock_entity.async_set_included_entities()
+
+    mock_entity.async_schedule_update_ha_state(True)
+    await hass.async_block_till_done()
+
+    state = hass.states.get(mock_entity.entity_id)
+    assert state.attributes.get("extra") == "beer"
+    assert state.attributes.get(ATTR_ENTITY_ID) == [
+        "hello.continents",
+        "hello.moon",
+        "hello.oceans",
+    ]
+
+    # Remove an entity from the group of included entities
+    mock_entity._attr_included_unique_ids = ["very_unique_moon", "very_unique_oceans"]
+    mock_entity.async_set_included_entities()
+
+    mock_entity.async_schedule_update_ha_state(True)
+    await hass.async_block_till_done()
+
+    state = hass.states.get(mock_entity.entity_id)
+    assert state.attributes.get(ATTR_ENTITY_ID) == ["hello.moon", "hello.oceans"]
+
+    # Rename an included entity via the registry entity
+    entity_registry.async_update_entity(
+        entity_id="hello.moon", new_entity_id="hello.moon_light"
+    )
+
+    await hass.async_block_till_done()
+
+    state = hass.states.get(mock_entity.entity_id)
+    assert state.attributes.get(ATTR_ENTITY_ID) == ["hello.moon_light", "hello.oceans"]
+
+    # Remove an included entity from the registry entity
+    entity_registry.async_remove(entity_id="hello.oceans")
+
+    await hass.async_block_till_done()
+
+    state = hass.states.get(mock_entity.entity_id)
+    assert state.attributes.get(ATTR_ENTITY_ID) == ["hello.moon_light"]