entity_platform.py

Go to the documentation of this file.

"""Class to manage the entities for a single platform."""
 
from __future__ import annotations
 
import asyncio
from collections.abc import Awaitable, Callable, Coroutine, Iterable
from contextvars import ContextVar
from datetime import timedelta
from logging import Logger, getLogger
from typing import TYPE_CHECKING, Any, Protocol
 
from homeassistant import config_entries
from homeassistant.const import (
    ATTR_RESTORED,
    DEVICE_DEFAULT_NAME,
    EVENT_HOMEASSISTANT_STARTED,
)
from homeassistant.core import (
    CALLBACK_TYPE,
    DOMAIN as HOMEASSISTANT_DOMAIN,
    CoreState,
    HomeAssistant,
    ServiceCall,
    SupportsResponse,
    callback,
    split_entity_id,
    valid_entity_id,
)
from homeassistant.exceptions import (
    ConfigEntryAuthFailed,
    ConfigEntryError,
    ConfigEntryNotReady,
    HomeAssistantError,
    PlatformNotReady,
)
from homeassistant.generated import languages
from homeassistant.setup import SetupPhases, async_start_setup
from homeassistant.util.async_ import create_eager_task
from homeassistant.util.hass_dict import HassKey
 
from . import (
    device_registry as dev_reg,
    entity_registry as ent_reg,
    service,
    translation,
)
from .entity_registry import EntityRegistry, RegistryEntryDisabler, RegistryEntryHider
from .event import async_call_later
from .issue_registry import IssueSeverity, async_create_issue
from .typing import UNDEFINED, ConfigType, DiscoveryInfoType, VolDictType, VolSchemaType
 
if TYPE_CHECKING:
    from .entity import Entity
 
 
SLOW_SETUP_WARNING = 10
SLOW_SETUP_MAX_WAIT = 60
SLOW_ADD_ENTITY_MAX_WAIT = 15  # Per Entity
SLOW_ADD_MIN_TIMEOUT = 500
 
PLATFORM_NOT_READY_RETRIES = 10
DATA_ENTITY_PLATFORM: HassKey[dict[str, list[EntityPlatform]]] = HassKey(
    "entity_platform"
)
DATA_DOMAIN_ENTITIES: HassKey[dict[str, dict[str, Entity]]] = HassKey("domain_entities")
DATA_DOMAIN_PLATFORM_ENTITIES: HassKey[dict[tuple[str, str], dict[str, Entity]]] = (
    HassKey("domain_platform_entities")
)
PLATFORM_NOT_READY_BASE_WAIT_TIME = 30  # seconds
 
_LOGGER = getLogger(__name__)
 
 
class AddEntitiesCallback(Protocol):
    """Protocol type for EntityPlatform.add_entities callback."""
 
    def __call__(
        self, new_entities: Iterable[Entity], update_before_add: bool = False
    ) -> None:
        """Define add_entities type."""
 
 
class EntityPlatformModule(Protocol):
    """Protocol type for entity platform modules."""
 
    async def async_setup_platform(
        self,
        hass: HomeAssistant,
        config: ConfigType,
        async_add_entities: AddEntitiesCallback,
        discovery_info: DiscoveryInfoType | None = None,
    ) -> None:
        """Set up an integration platform async."""
 
    def setup_platform(
        self,
        hass: HomeAssistant,
        config: ConfigType,
        add_entities: AddEntitiesCallback,
        discovery_info: DiscoveryInfoType | None = None,
    ) -> None:
        """Set up an integration platform."""
 
    async def async_setup_entry(
        self,
        hass: HomeAssistant,
        entry: config_entries.ConfigEntry,
        async_add_entities: AddEntitiesCallback,
    ) -> None:
        """Set up an integration platform from a config entry."""
 
 
class EntityPlatform:
    """Manage the entities for a single platform.
 
    An example of an entity platform is 'hue.light', which is managed by
    the entity component 'light'.
    """
 
    def __init__(
        self,
        *,
        hass: HomeAssistant,
        logger: Logger,
        domain: str,
        platform_name: str,
        platform: EntityPlatformModule | None,
        scan_interval: timedelta,
        entity_namespace: str | None,
    ) -> None:
        """Initialize the entity platform."""
        self.hasshass = hass
        self.loggerlogger = logger
        self.domaindomain = domain
        self.platform_nameplatform_name = platform_name
        self.platformplatform = platform
        self.scan_intervalscan_interval = scan_interval
        self.scan_interval_secondsscan_interval_seconds = scan_interval.total_seconds()
        self.entity_namespaceentity_namespace = entity_namespace
        self.config_entryconfig_entry: config_entries.ConfigEntry | None = None
        # Storage for entities for this specific platform only
        # which are indexed by entity_id
        self.entities: dict[str, Entity] = {}
        self.component_translationscomponent_translations: dict[str, str] = {}
        self.platform_translationsplatform_translations: dict[str, str] = {}
        self.object_id_component_translationsobject_id_component_translations: dict[str, str] = {}
        self.object_id_platform_translationsobject_id_platform_translations: dict[str, str] = {}
        self.default_language_platform_translationsdefault_language_platform_translations: dict[str, str] = {}
        self._tasks: list[asyncio.Task[None]] = []
        # Stop tracking tasks after setup is completed
        self._setup_complete_setup_complete = False
        # Method to cancel the state change listener
        self._async_polling_timer_async_polling_timer: asyncio.TimerHandle | None = None
        # Method to cancel the retry of setup
        self._async_cancel_retry_setup_async_cancel_retry_setup: CALLBACK_TYPE | None = None
        self._process_updates_process_updates: asyncio.Lock | None = None
 
        self.parallel_updatesparallel_updates: asyncio.Semaphore | None = None
        self._update_in_sequence_update_in_sequence: bool = False
 
        # Platform is None for the EntityComponent "catch-all" EntityPlatform
        # which powers entity_component.add_entities
        self.parallel_updates_createdparallel_updates_created = platform is None
 
        # Storage for entities indexed by domain
        # with the child dict indexed by entity_id
        #
        # This is usually media_player, light, switch, etc.
        self.domain_entitiesdomain_entities = hass.data.setdefault(
            DATA_DOMAIN_ENTITIES, {}
        ).setdefault(domain, {})
 
        # Storage for entities indexed by domain and platform
        # with the child dict indexed by entity_id
        #
        # This is usually media_player.yamaha, light.hue, switch.tplink, etc.
        key = (domain, platform_name)
        self.domain_platform_entitiesdomain_platform_entities = hass.data.setdefault(
            DATA_DOMAIN_PLATFORM_ENTITIES, {}
        ).setdefault(key, {})
 
    def __repr__(self) -> str:
        """Represent an EntityPlatform."""
        return (
            "<EntityPlatform "
            f"domain={self.domain} "
            f"platform_name={self.platform_name} "
            f"config_entry={self.config_entry}>"
        )
 
    @callback
    def _get_parallel_updates_semaphore(
        self, entity_has_sync_update: bool
    ) -> asyncio.Semaphore | None:
        """Get or create a semaphore for parallel updates.
 
        Semaphore will be created on demand because we base it off if update
        method is async or not.
 
        - If parallel updates is set to 0, we skip the semaphore.
        - If parallel updates is set to a number, we initialize the semaphore
          to that number.
 
        The default value for parallel requests is decided based on the first
        entity of the platform which is added to Home Assistant. It's 1 if the
        entity implements the update method, else it's 0.
        """
        if self.parallel_updates_createdparallel_updates_created:
            return self.parallel_updatesparallel_updates
 
        self.parallel_updates_createdparallel_updates_created = True
 
        parallel_updates = getattr(self.platformplatform, "PARALLEL_UPDATES", None)
 
        if parallel_updates is None and entity_has_sync_update:
            parallel_updates = 1
 
        if parallel_updates == 0:
            parallel_updates = None
 
        if parallel_updates is not None:
            self.parallel_updatesparallel_updates = asyncio.Semaphore(parallel_updates)
            self._update_in_sequence_update_in_sequence = parallel_updates == 1
 
        return self.parallel_updatesparallel_updates
 
    async def async_setup(
        self,
        platform_config: ConfigType,
        discovery_info: DiscoveryInfoType | None = None,
    ) -> None:
        """Set up the platform from a config file."""
        platform = self.platformplatform
        hass = self.hasshass
 
        if not hasattr(platform, "async_setup_platform") and not hasattr(
            platform, "setup_platform"
        ):
            self.loggerlogger.error(
                (
                    "The %s platform for the %s integration does not support platform"
                    " setup. Please remove it from your config."
                ),
                self.platform_nameplatform_name,
                self.domaindomain,
            )
            learn_more_url = None
            if self.platformplatform and "custom_components" not in self.platformplatform.__file__:  # type: ignore[attr-defined]
                learn_more_url = (
                    f"https://www.home-assistant.io/integrations/{self.platform_name}/"
                )
            platform_key = f"platform: {self.platform_name}"
            yaml_example = f"```yaml\n{self.domain}:\n  - {platform_key}\n```"
            async_create_issue(
                self.hasshass,
                HOMEASSISTANT_DOMAIN,
                f"platform_integration_no_support_{self.domain}_{self.platform_name}",
                is_fixable=False,
                issue_domain=self.platform_nameplatform_name,
                learn_more_url=learn_more_url,
                severity=IssueSeverity.ERROR,
                translation_key="no_platform_setup",
                translation_placeholders={
                    "domain": self.domaindomain,
                    "platform": self.platform_nameplatform_name,
                    "platform_key": platform_key,
                    "yaml_example": yaml_example,
                },
            )
 
            return
 
        @callback
        def async_create_setup_awaitable() -> (
            Coroutine[Any, Any, None] | asyncio.Future[None]
        ):
            """Get task to set up platform."""
            if getattr(platform, "async_setup_platform", None):
                return platform.async_setup_platform(  # type: ignore[union-attr]
                    hass,
                    platform_config,
                    self._async_schedule_add_entities_async_schedule_add_entities,
                    discovery_info,
                )
 
            # This should not be replaced with hass.async_add_job because
            # we don't want to track this task in case it blocks startup.
            return hass.loop.run_in_executor(
                None,
                platform.setup_platform,  # type: ignore[union-attr]
                hass,
                platform_config,
                self._schedule_add_entities_schedule_add_entities,
                discovery_info,
            )
 
        with async_start_setup(
            hass,
            integration=self.platform_nameplatform_name,
            group=str(id(platform_config)),
            phase=SetupPhases.PLATFORM_SETUP,
        ):
            await self._async_setup_platform_async_setup_platform(async_create_setup_awaitable)
 
    @callback
    def async_shutdown(self) -> None:
        """Call when Home Assistant is stopping."""
        self.async_cancel_retry_setupasync_cancel_retry_setup()
        self.async_unsub_pollingasync_unsub_polling()
 
    @callback
    def async_cancel_retry_setup(self) -> None:
        """Cancel retry setup."""
        if self._async_cancel_retry_setup_async_cancel_retry_setup is not None:
            self._async_cancel_retry_setup_async_cancel_retry_setup()
            self._async_cancel_retry_setup_async_cancel_retry_setup = None
 
    async def async_setup_entry(self, config_entry: config_entries.ConfigEntry) -> bool:
        """Set up the platform from a config entry."""
        # Store it so that we can save config entry ID in entity registry
        self.config_entryconfig_entry = config_entry
        platform = self.platformplatform
 
        @callback
        def async_create_setup_awaitable() -> Coroutine[Any, Any, None]:
            """Get task to set up platform."""
            config_entries.current_entry.set(config_entry)
 
            return platform.async_setup_entry(  # type: ignore[union-attr]
                self.hasshass, config_entry, self._async_schedule_add_entities_for_entry_async_schedule_add_entities_for_entry
            )
 
        return await self._async_setup_platform_async_setup_platform(async_create_setup_awaitable)
 
    async def _async_setup_platform(
        self,
        async_create_setup_awaitable: Callable[[], Awaitable[None]],
        tries: int = 0,
    ) -> bool:
        """Set up a platform via config file or config entry.
 
        async_create_setup_awaitable creates an awaitable that sets up platform.
        """
        current_platform.set(self)
        logger = self.loggerlogger
        hass = self.hasshass
        full_name = f"{self.platform_name}.{self.domain}"
 
        await self.async_load_translationsasync_load_translations()
 
        logger.info("Setting up %s", full_name)
        warn_task = hass.loop.call_at(
            hass.loop.time() + SLOW_SETUP_WARNING,
            logger.warning,
            "Setup of %s platform %s is taking over %s seconds.",
            self.domaindomain,
            self.platform_nameplatform_name,
            SLOW_SETUP_WARNING,
        )
        try:
            awaitable = async_create_setup_awaitable()
            if asyncio.iscoroutine(awaitable):
                awaitable = create_eager_task(awaitable, loop=hass.loop)
 
            async with hass.timeout.async_timeout(SLOW_SETUP_MAX_WAIT, self.domaindomain):
                await asyncio.shield(awaitable)
 
            # Block till all entities are done
            while self._tasks:
                # Await all tasks even if they are done
                # to ensure exceptions are propagated
                pending = self._tasks.copy()
                self._tasks.clear()
                await asyncio.gather(*pending)
        except PlatformNotReady as ex:
            tries += 1
            wait_time = min(tries, 6) * PLATFORM_NOT_READY_BASE_WAIT_TIME
            message = str(ex)
            ready_message = f"ready yet: {message}" if message else "ready yet"
            if tries == 1:
                logger.warning(
                    "Platform %s not %s; Retrying in background in %d seconds",
                    self.platform_nameplatform_name,
                    ready_message,
                    wait_time,
                )
            else:
                logger.debug(
                    "Platform %s not %s; Retrying in %d seconds",
                    self.platform_nameplatform_name,
                    ready_message,
                    wait_time,
                )
 
            async def setup_again(*_args: Any) -> None:
                """Run setup again."""
                self._async_cancel_retry_setup_async_cancel_retry_setup = None
                await self._async_setup_platform_async_setup_platform(async_create_setup_awaitable, tries)
 
            if hass.state is CoreState.running:
                self._async_cancel_retry_setup_async_cancel_retry_setup = async_call_later(
                    hass, wait_time, setup_again
                )
            else:
                self._async_cancel_retry_setup_async_cancel_retry_setup = hass.bus.async_listen_once(
                    EVENT_HOMEASSISTANT_STARTED, setup_again
                )
            return False
        except TimeoutError:
            logger.error(
                (
                    "Setup of platform %s is taking longer than %s seconds."
                    " Startup will proceed without waiting any longer."
                ),
                self.platform_nameplatform_name,
                SLOW_SETUP_MAX_WAIT,
            )
            return False
        except (ConfigEntryNotReady, ConfigEntryAuthFailed, ConfigEntryError) as exc:
            _LOGGER.error(
                "%s raises exception %s in forwarded platform "
                "%s; Instead raise %s before calling async_forward_entry_setups",
                self.platform_nameplatform_name,
                type(exc).__name__,
                self.domaindomain,
                type(exc).__name__,
            )
            return False
        except Exception:
            logger.exception(
                "Error while setting up %s platform for %s",
                self.platform_nameplatform_name,
                self.domaindomain,
            )
            return False
        else:
            hass.config.components.add(full_name)
            self._setup_complete_setup_complete = True
            return True
        finally:
            warn_task.cancel()
 
    async def _async_get_translations(
        self, language: str, category: str, integration: str
    ) -> dict[str, str]:
        """Get translations for a language, category, and integration."""
        try:
            return await translation.async_get_translations(
                self.hasshass, language, category, {integration}
            )
        except Exception as err:  # noqa: BLE001
            _LOGGER.debug(
                "Could not load translations for %s",
                integration,
                exc_info=err,
            )
        return {}
 
    async def async_load_translations(self) -> None:
        """Load translations."""
        hass = self.hasshass
        object_id_language = (
            hass.config.language
            if hass.config.language in languages.NATIVE_ENTITY_IDS
            else languages.DEFAULT_LANGUAGE
        )
        config_language = hass.config.language
        self.component_translationscomponent_translations = await self._async_get_translations_async_get_translations(
            config_language, "entity_component", self.domaindomain
        )
        self.platform_translationsplatform_translations = await self._async_get_translations_async_get_translations(
            config_language, "entity", self.platform_nameplatform_name
        )
        if object_id_language == config_language:
            self.object_id_component_translationsobject_id_component_translations = self.component_translationscomponent_translations
            self.object_id_platform_translationsobject_id_platform_translations = self.platform_translationsplatform_translations
        else:
            self.object_id_component_translationsobject_id_component_translations = await self._async_get_translations_async_get_translations(
                object_id_language, "entity_component", self.domaindomain
            )
            self.object_id_platform_translationsobject_id_platform_translations = await self._async_get_translations_async_get_translations(
                object_id_language, "entity", self.platform_nameplatform_name
            )
        if config_language == languages.DEFAULT_LANGUAGE:
            self.default_language_platform_translationsdefault_language_platform_translations = self.platform_translationsplatform_translations
        else:
            self.default_language_platform_translationsdefault_language_platform_translations = (
                await self._async_get_translations_async_get_translations(
                    languages.DEFAULT_LANGUAGE, "entity", self.platform_nameplatform_name
                )
            )
 
    def _schedule_add_entities(
        self, new_entities: Iterable[Entity], update_before_add: bool = False
    ) -> None:
        """Schedule adding entities for a single platform, synchronously."""
        self.hasshass.loop.call_soon_threadsafe(
            self._async_schedule_add_entities_async_schedule_add_entities,
            list(new_entities),
            update_before_add,
        )
 
    @callback
    def _async_schedule_add_entities(
        self, new_entities: Iterable[Entity], update_before_add: bool = False
    ) -> None:
        """Schedule adding entities for a single platform async."""
        task = self.hasshass.async_create_task_internal(
            self.async_add_entitiesasync_add_entities(new_entities, update_before_add=update_before_add),
            f"EntityPlatform async_add_entities {self.domain}.{self.platform_name}",
            eager_start=True,
        )
 
        if not self._setup_complete_setup_complete:
            self._tasks.append(task)
 
    @callback
    def _async_schedule_add_entities_for_entry(
        self, new_entities: Iterable[Entity], update_before_add: bool = False
    ) -> None:
        """Schedule adding entities for a single platform async and track the task."""
        assert self.config_entryconfig_entry
        task = self.config_entryconfig_entry.async_create_task(
            self.hasshass,
            self.async_add_entitiesasync_add_entities(new_entities, update_before_add=update_before_add),
            f"EntityPlatform async_add_entities_for_entry {self.domain}.{self.platform_name}",
            eager_start=True,
        )
 
        if not self._setup_complete_setup_complete:
            self._tasks.append(task)
 
    def add_entities(
        self, new_entities: Iterable[Entity], update_before_add: bool = False
    ) -> None:
        """Add entities for a single platform."""
        # That avoid deadlocks
        if update_before_add:
            self.loggerlogger.warning(
                "Call 'add_entities' with update_before_add=True "
                "only inside tests or you can run into a deadlock!"
            )
 
        asyncio.run_coroutine_threadsafe(
            self.async_add_entitiesasync_add_entities(list(new_entities), update_before_add),
            self.hasshass.loop,
        ).result()
 
    async def _async_add_and_update_entities(
        self,
        coros: list[Coroutine[Any, Any, None]],
        entities: list[Entity],
        timeout: float,
    ) -> None:
        """Add entities for a single platform and update them.
 
        Since we are updating the entities before adding them, we need to
        schedule the coroutines as tasks so we can await them in the event
        loop. This is because the update is likely to yield control to the
        event loop and will finish faster if we run them concurrently.
        """
        results: list[BaseException | None] | None = None
        tasks = [create_eager_task(coro, loop=self.hasshass.loop) for coro in coros]
        try:
            async with self.hasshass.timeout.async_timeout(timeout, self.domaindomain):
                results = await asyncio.gather(*tasks, return_exceptions=True)
        except TimeoutError:
            self.loggerlogger.warning(
                "Timed out adding entities for domain %s with platform %s after %ds",
                self.domaindomain,
                self.platform_nameplatform_name,
                timeout,
            )
 
        if not results:
            return
 
        for idx, result in enumerate(results):
            if isinstance(result, Exception):
                entity = entities[idx]
                self.loggerlogger.exception(
                    "Error adding entity %s for domain %s with platform %s",
                    entity.entity_id,
                    self.domaindomain,
                    self.platform_nameplatform_name,
                    exc_info=result,
                )
            elif isinstance(result, BaseException):
                raise result
 
    async def _async_add_entities(
        self,
        coros: list[Coroutine[Any, Any, None]],
        entities: list[Entity],
        timeout: float,
    ) -> None:
        """Add entities for a single platform without updating.
 
        In this case we are not updating the entities before adding them
        which means it is likely that we will not have to yield control
        to the event loop so we can await the coros directly without
        scheduling them as tasks.
        """
        try:
            async with self.hasshass.timeout.async_timeout(timeout, self.domaindomain):
                for idx, coro in enumerate(coros):
                    try:
                        await coro
                    except Exception as ex:
                        entity = entities[idx]
                        self.loggerlogger.exception(
                            "Error adding entity %s for domain %s with platform %s",
                            entity.entity_id,
                            self.domaindomain,
                            self.platform_nameplatform_name,
                            exc_info=ex,
                        )
        except TimeoutError:
            self.loggerlogger.warning(
                "Timed out adding entities for domain %s with platform %s after %ds",
                self.domaindomain,
                self.platform_nameplatform_name,
                timeout,
            )
 
    async def async_add_entities(
        self, new_entities: Iterable[Entity], update_before_add: bool = False
    ) -> None:
        """Add entities for a single platform async.
 
        This method must be run in the event loop.
        """
        # handle empty list from component/platform
        if not new_entities:  # type: ignore[truthy-iterable]
            return
 
        hass = self.hasshass
        entity_registry = ent_reg.async_get(hass)
        coros: list[Coroutine[Any, Any, None]] = []
        entities: list[Entity] = []
        for entity in new_entities:
            coros.append(
                self._async_add_entity_async_add_entity(entity, update_before_add, entity_registry)
            )
            entities.append(entity)
 
        # No entities for processing
        if not coros:
            return
 
        timeout = max(SLOW_ADD_ENTITY_MAX_WAIT * len(coros), SLOW_ADD_MIN_TIMEOUT)
        if update_before_add:
            add_func = self._async_add_and_update_entities_async_add_and_update_entities
        else:
            add_func = self._async_add_entities_async_add_entities
 
        await add_func(coros, entities, timeout)
 
        if (
            (self.config_entryconfig_entry and self.config_entryconfig_entry.pref_disable_polling)
            or self._async_polling_timer_async_polling_timer is not None
            or not any(
                # Entity may have failed to add or called `add_to_platform_abort`
                # so we check if the entity is in self.entities before
                # checking `entity.should_poll` since `should_poll` may need to
                # check `self.hass` which will be `None` if the entity did not add
                entity.entity_id
                and entity.entity_id in self.entities
                and entity.should_poll
                for entity in entities
            )
        ):
            return
 
        self._async_polling_timer_async_polling_timer = self.hasshass.loop.call_later(
            self.scan_interval_secondsscan_interval_seconds,
            self._async_handle_interval_callback_async_handle_interval_callback,
        )
 
    @callback
    def _async_handle_interval_callback(self) -> None:
        """Update all the entity states in a single platform."""
        self._async_polling_timer_async_polling_timer = self.hasshass.loop.call_later(
            self.scan_interval_secondsscan_interval_seconds,
            self._async_handle_interval_callback_async_handle_interval_callback,
        )
        if self.config_entryconfig_entry:
            self.config_entryconfig_entry.async_create_background_task(
                self.hasshass,
                self._async_update_entity_states_async_update_entity_states(),
                name=f"EntityPlatform poll {self.domain}.{self.platform_name}",
                eager_start=True,
            )
        else:
            self.hasshass.async_create_background_task(
                self._async_update_entity_states_async_update_entity_states(),
                name=f"EntityPlatform poll {self.domain}.{self.platform_name}",
                eager_start=True,
            )
 
    def _entity_id_already_exists(self, entity_id: str) -> tuple[bool, bool]:
        """Check if an entity_id already exists.
 
        Returns a tuple [already_exists, restored]
        """
        already_exists = entity_id in self.entities
        restored = False
 
        if not already_exists and not self.hasshass.states.async_available(entity_id):
            existing = self.hasshass.states.get(entity_id)
            if existing is not None and ATTR_RESTORED in existing.attributes:
                restored = True
            else:
                already_exists = True
        return (already_exists, restored)
 
    async def _async_add_entity(  # noqa: C901
        self,
        entity: Entity,
        update_before_add: bool,
        entity_registry: EntityRegistry,
    ) -> None:
        """Add an entity to the platform."""
        if entity is None:
            raise ValueError("Entity cannot be None")
 
        entity.add_to_platform_start(
            self.hasshass,
            self,
            self._get_parallel_updates_semaphore_get_parallel_updates_semaphore(hasattr(entity, "update")),
        )
 
        # Update properties before we generate the entity_id. This will happen
        # also for disabled entities.
        if update_before_add:
            try:
                await entity.async_device_update(warning=False)
            except Exception:
                self.loggerlogger.exception("%s: Error on device update!", self.platform_nameplatform_name)
                entity.add_to_platform_abort()
                return
 
        suggested_object_id: str | None = None
 
        entity_name = entity.name
        if entity_name is UNDEFINED:
            entity_name = None
 
        # Get entity_id from unique ID registration
        if entity.unique_id is not None:
            registered_entity_id = entity_registry.async_get_entity_id(
                self.domaindomain, self.platform_nameplatform_name, entity.unique_id
            )
            if registered_entity_id:
                already_exists, _ = self._entity_id_already_exists_entity_id_already_exists(registered_entity_id)
 
                if already_exists:
                    # If there's a collision, the entry belongs to another entity
                    entity.registry_entry = None
                    msg = (
                        f"Platform {self.platform_name} does not generate unique IDs. "
                    )
                    if entity.entity_id:
                        msg += (
                            f"ID {entity.unique_id} is already used by"
                            f" {registered_entity_id} - ignoring {entity.entity_id}"
                        )
                    else:
                        msg += (
                            f"ID {entity.unique_id} already exists - ignoring"
                            f" {registered_entity_id}"
                        )
                    self.loggerlogger.error(msg)
                    entity.add_to_platform_abort()
                    return
 
            if self.config_entryconfig_entry and (device_info := entity.device_info):
                try:
                    device = dev_reg.async_get(self.hasshass).async_get_or_create(
                        config_entry_id=self.config_entryconfig_entry.entry_id,
                        **device_info,
                    )
                except dev_reg.DeviceInfoError as exc:
                    self.loggerlogger.error(
                        "%s: Not adding entity with invalid device info: %s",
                        self.platform_nameplatform_name,
                        str(exc),
                    )
                    entity.add_to_platform_abort()
                    return
            else:
                device = None
 
            # An entity may suggest the entity_id by setting entity_id itself
            suggested_entity_id: str | None = entity.entity_id
            if suggested_entity_id is not None:
                suggested_object_id = split_entity_id(entity.entity_id)[1]
            else:
                if device and entity.has_entity_name:
                    device_name = device.name_by_user or device.name
                    if entity.use_device_name:
                        suggested_object_id = device_name
                    else:
                        suggested_object_id = (
                            f"{device_name} {entity.suggested_object_id}"
                        )
                if not suggested_object_id:
                    suggested_object_id = entity.suggested_object_id
 
            if self.entity_namespaceentity_namespace is not None:
                suggested_object_id = f"{self.entity_namespace} {suggested_object_id}"
 
            disabled_by: RegistryEntryDisabler | None = None
            if not entity.entity_registry_enabled_default:
                disabled_by = RegistryEntryDisabler.INTEGRATION
 
            hidden_by: RegistryEntryHider | None = None
            if not entity.entity_registry_visible_default:
                hidden_by = RegistryEntryHider.INTEGRATION
 
            entry = entity_registry.async_get_or_create(
                self.domaindomain,
                self.platform_nameplatform_name,
                entity.unique_id,
                capabilities=entity.capability_attributes,
                config_entry=self.config_entryconfig_entry,
                device_id=device.id if device else None,
                disabled_by=disabled_by,
                entity_category=entity.entity_category,
                get_initial_options=entity.get_initial_entity_options,
                has_entity_name=entity.has_entity_name,
                hidden_by=hidden_by,
                known_object_ids=self.entities,
                original_device_class=entity.device_class,
                original_icon=entity.icon,
                original_name=entity_name,
                suggested_object_id=suggested_object_id,
                supported_features=entity.supported_features,
                translation_key=entity.translation_key,
                unit_of_measurement=entity.unit_of_measurement,
            )
 
            if device and device.disabled and not entry.disabled:
                entry = entity_registry.async_update_entity(
                    entry.entity_id, disabled_by=RegistryEntryDisabler.DEVICE
                )
 
            entity.registry_entry = entry
            if device:
                entity.device_entry = device
            entity.entity_id = entry.entity_id
 
        else:  # entity.unique_id is None
            generate_new_entity_id = False
            # We won't generate an entity ID if the platform has already set one
            # We will however make sure that platform cannot pick a registered ID
            if entity.entity_id is not None and entity_registry.async_is_registered(
                entity.entity_id
            ):
                # If entity already registered, convert entity id to suggestion
                suggested_object_id = split_entity_id(entity.entity_id)[1]
                generate_new_entity_id = True
 
            # Generate entity ID
            if entity.entity_id is None or generate_new_entity_id:
                suggested_object_id = (
                    suggested_object_id
                    or entity.suggested_object_id
                    or DEVICE_DEFAULT_NAME
                )
 
                if self.entity_namespaceentity_namespace is not None:
                    suggested_object_id = (
                        f"{self.entity_namespace} {suggested_object_id}"
                    )
                entity.entity_id = entity_registry.async_generate_entity_id(
                    self.domaindomain, suggested_object_id, self.entities
                )
 
            # Make sure it is valid in case an entity set the value themselves
            # Avoid calling valid_entity_id if we already know it is valid
            # since it already made it in the registry
            if not valid_entity_id(entity.entity_id):
                entity.add_to_platform_abort()
                raise HomeAssistantError(f"Invalid entity ID: {entity.entity_id}")
 
        already_exists, restored = self._entity_id_already_exists_entity_id_already_exists(entity.entity_id)
 
        if already_exists:
            self.loggerlogger.error(
                "Entity id already exists - ignoring: %s", entity.entity_id
            )
            entity.add_to_platform_abort()
            return
 
        if entity.registry_entry and entity.registry_entry.disabled:
            self.loggerlogger.debug(
                "Not adding entity %s because it's disabled",
                entry.name
                or entity_name
                or f'"{self.platform_name} {entity.unique_id}"',
            )
            entity.add_to_platform_abort()
            return
 
        entity_id = entity.entity_id
        self.entities[entity_id] = entity
        self.domain_entitiesdomain_entities[entity_id] = entity
        self.domain_platform_entitiesdomain_platform_entities[entity_id] = entity
 
        if not restored:
            # Reserve the state in the state machine
            # because as soon as we return control to the event
            # loop below, another entity could be added
            # with the same id before `entity.add_to_platform_finish()`
            # has a chance to finish.
            self.hasshass.states.async_reserve(entity.entity_id)
 
        def remove_entity_cb() -> None:
            """Remove entity from entities dict."""
            del self.entities[entity_id]
            del self.domain_entitiesdomain_entities[entity_id]
            del self.domain_platform_entitiesdomain_platform_entities[entity_id]
 
        entity.async_on_remove(remove_entity_cb)
 
        await entity.add_to_platform_finish()
 
    async def async_reset(self) -> None:
        """Remove all entities and reset data.
 
        This method must be run in the event loop.
        """
        self.async_cancel_retry_setupasync_cancel_retry_setup()
 
        if not self.entities:
            return
 
        # Removals are awaited in series since in most
        # cases calling async_remove will not yield control
        # to the event loop and we want to avoid scheduling
        # one task per entity.
        for entity in list(self.entities.values()):
            try:
                await entity.async_remove()
            except Exception:
                self.loggerlogger.exception(
                    "Error while removing entity %s", entity.entity_id
                )
 
        self.async_unsub_pollingasync_unsub_polling()
        self._setup_complete_setup_complete = False
 
    @callback
    def async_unsub_polling(self) -> None:
        """Stop polling."""
        if self._async_polling_timer_async_polling_timer is not None:
            self._async_polling_timer_async_polling_timer.cancel()
            self._async_polling_timer_async_polling_timer = None
 
    @callback
    def async_prepare(self) -> None:
        """Register the entity platform in DATA_ENTITY_PLATFORM."""
        self.hasshass.data.setdefault(DATA_ENTITY_PLATFORM, {}).setdefault(
            self.platform_nameplatform_name, []
        ).append(self)
 
    async def async_destroy(self) -> None:
        """Destroy an entity platform.
 
        Call before discarding the object.
        """
        await self.async_resetasync_reset()
        self.hasshass.data[DATA_ENTITY_PLATFORM][self.platform_nameplatform_name].remove(self)
 
    async def async_remove_entity(self, entity_id: str) -> None:
        """Remove entity id from platform."""
        await self.entities[entity_id].async_remove()
 
        # Clean up polling job if no longer needed
        if self._async_polling_timer_async_polling_timer is not None and not any(
            entity.should_poll for entity in self.entities.values()
        ):
            self.async_unsub_pollingasync_unsub_polling()
 
    async def async_extract_from_service(
        self, service_call: ServiceCall, expand_group: bool = True
    ) -> list[Entity]:
        """Extract all known and available entities from a service call.
 
        Will return an empty list if entities specified but unknown.
 
        This method must be run in the event loop.
        """
        return await service.async_extract_entities(
            self.hasshass, self.entities.values(), service_call, expand_group
        )
 
    @callback
    def async_register_entity_service(
        self,
        name: str,
        schema: VolDictType | VolSchemaType | None,
        func: str | Callable[..., Any],
        required_features: Iterable[int] | None = None,
        supports_response: SupportsResponse = SupportsResponse.NONE,
    ) -> None:
        """Register an entity service.
 
        Services will automatically be shared by all platforms of the same domain.
        """
        if self.hasshass.services.has_service(self.platform_nameplatform_name, name):
            return
 
        service.async_register_entity_service(
            self.hasshass,
            self.platform_nameplatform_name,
            name,
            entities=self.domain_platform_entitiesdomain_platform_entities,
            func=func,
            job_type=None,
            required_features=required_features,
            schema=schema,
            supports_response=supports_response,
        )
 
    async def _async_update_entity_states(self) -> None:
        """Update the states of all the polling entities.
 
        To protect from flooding the executor, we will update async entities
        in parallel and other entities sequential.
 
        This method must be run in the event loop.
        """
        if self._process_updates_process_updates is None:
            self._process_updates_process_updates = asyncio.Lock()
        if self._process_updates_process_updates.locked():
            self.loggerlogger.warning(
                "Updating %s %s took longer than the scheduled update interval %s",
                self.platform_nameplatform_name,
                self.domaindomain,
                self.scan_intervalscan_interval,
            )
            return
 
        async with self._process_updates_process_updates:
            if self._update_in_sequence_update_in_sequence or len(self.entities) <= 1:
                # If we know we will update sequentially, we want to avoid scheduling
                # the coroutines as tasks that will wait on the semaphore lock.
                for entity in list(self.entities.values()):
                    # If the entity is removed from hass during the previous
                    # entity being updated, we need to skip updating the
                    # entity.
                    if entity.should_poll and entity.hass:
                        await entity.async_update_ha_state(True)
                return
 
            if tasks := [
                create_eager_task(
                    entity.async_update_ha_state(True), loop=self.hasshass.loop
                )
                for entity in self.entities.values()
                if entity.should_poll
            ]:
                await asyncio.gather(*tasks)
 
 
current_platform: ContextVar[EntityPlatform | None] = ContextVar(
    "current_platform", default=None
)
 
 
@callback
def async_get_current_platform() -> EntityPlatform:
    """Get the current platform from context."""
    if (platform := current_platform.get()) is None:
        raise RuntimeError("Cannot get non-set current platform")
    return platform
 
 
@callback
def async_get_platforms(
    hass: HomeAssistant, integration_name: str
) -> list[EntityPlatform]:
    """Find existing platforms."""
    if (
        DATA_ENTITY_PLATFORM not in hass.data
        or integration_name not in hass.data[DATA_ENTITY_PLATFORM]
    ):
        return []
 
    return hass.data[DATA_ENTITY_PLATFORM][integration_name]