Deprecate tplink alarm button entities

homeassistant/components/tplink/binary_sensor.py

@@ -75,6 +75,7 @@ async def async_setup_entry(
  device = parent_coordinator.device
 
  entities = CoordinatedTPLinkFeatureEntity.entities_for_device_and_its_children(
+ hass=hass,
  device=device,
  coordinator=parent_coordinator,
  feature_type=Feature.Type.BinarySensor,

homeassistant/components/tplink/button.py

@@ -7,11 +7,17 @@
 
 from kasa import Feature
 
-from homeassistant.components.button import ButtonEntity, ButtonEntityDescription
+from homeassistant.components.button import (
+ DOMAIN as BUTTON_DOMAIN,
+ ButtonEntity,
+ ButtonEntityDescription,
+)
+from homeassistant.components.siren import DOMAIN as SIREN_DOMAIN
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
 from . import TPLinkConfigEntry
+from .deprecate import DeprecatedInfo, async_cleanup_deprecated
 from .entity import CoordinatedTPLinkFeatureEntity, TPLinkFeatureEntityDescription
 
 
@@ -25,9 +31,19 @@ class TPLinkButtonEntityDescription(
 BUTTON_DESCRIPTIONS: Final = [
  TPLinkButtonEntityDescription(
  key="test_alarm",
+ deprecated_info=DeprecatedInfo(
+ platform=BUTTON_DOMAIN,
+ new_platform=SIREN_DOMAIN,
+ breaks_in_ha_version="2025.4.0",
+ ),
  ),
  TPLinkButtonEntityDescription(
  key="stop_alarm",
+ deprecated_info=DeprecatedInfo(
+ platform=BUTTON_DOMAIN,
+ new_platform=SIREN_DOMAIN,
+ breaks_in_ha_version="2025.4.0",
+ ),
  ),
 ]
 
@@ -46,13 +62,15 @@ async def async_setup_entry(
  device = parent_coordinator.device
 
  entities = CoordinatedTPLinkFeatureEntity.entities_for_device_and_its_children(
+ hass=hass,
  device=device,
  coordinator=parent_coordinator,
  feature_type=Feature.Type.Action,
  entity_class=TPLinkButtonEntity,
  descriptions=BUTTON_DESCRIPTIONS_MAP,
  child_coordinators=children_coordinators,
  )
+ async_cleanup_deprecated(hass, BUTTON_DOMAIN, config_entry.entry_id, entities)
  async_add_entities(entities)
 
 

homeassistant/components/tplink/deprecate.py

@@ -0,0 +1,111 @@
+"""Helper class for deprecating entities."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from homeassistant.components.automation import automations_with_entity
+from homeassistant.components.script import scripts_with_entity
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers import entity_registry as er
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
+
+from .const import DOMAIN
+
+if TYPE_CHECKING:
+ from .entity import CoordinatedTPLinkFeatureEntity, TPLinkFeatureEntityDescription
+
+
+@dataclass(slots=True)
+class DeprecatedInfo:
+ """Class to define deprecation info for deprecated entities."""
+
+ platform: str
+ new_platform: str
+ breaks_in_ha_version: str
+
+
+def async_check_create_deprecated(
+ hass: HomeAssistant,
+ unique_id: str,
+ entity_description: TPLinkFeatureEntityDescription,
+) -> bool:
+ """Return true if the entity should be created based on the deprecated_info.
+
+ If deprecated_info is not defined will return true.
+ If entity not yet created will return false.
+ If entity disabled will return false.
+ """
+ if not entity_description.deprecated_info:
+ return True
+
+ deprecated_info = entity_description.deprecated_info
+ platform = deprecated_info.platform
+
+ ent_reg = er.async_get(hass)
+ entity_id = ent_reg.async_get_entity_id(
+ platform,
+ DOMAIN,
+ unique_id,
+ )
+ if not entity_id:
+ return False
+
+ entity_entry = ent_reg.async_get(entity_id)
+ assert entity_entry
+ return not entity_entry.disabled
+
+
+def async_cleanup_deprecated(
+ hass: HomeAssistant,
+ platform: str,
+ entry_id: str,
+ entities: Sequence[CoordinatedTPLinkFeatureEntity],
+) -> None:
+ """Remove disabled deprecated entities or create issues if necessary."""
+ ent_reg = er.async_get(hass)
+ for entity in entities:
+ if not (deprecated_info := entity.entity_description.deprecated_info):
+ continue
+
+ assert entity.unique_id
+ entity_id = ent_reg.async_get_entity_id(
+ platform,
+ DOMAIN,
+ entity.unique_id,
+ )
+ assert entity_id
+ # Check for issues that need to be created
+ entity_automations = automations_with_entity(hass, entity_id)
+ entity_scripts = scripts_with_entity(hass, entity_id)
+
+ for item in entity_automations + entity_scripts:
+ async_create_issue(
+ hass,
+ DOMAIN,
+ f"deprecated_entity_{entity_id}_{item}",
+ breaks_in_ha_version=deprecated_info.breaks_in_ha_version,
+ is_fixable=False,
+ is_persistent=False,
+ severity=IssueSeverity.WARNING,
+ translation_key="deprecated_entity",
+ translation_placeholders={
+ "entity": entity_id,
+ "info": item,
+ "platform": platform,
+ "new_platform": deprecated_info.new_platform,
+ },
+ )
+
+ # Remove entities that are no longer provided and have been disabled.
+ unique_ids = {entity.unique_id for entity in entities}
+ for entity_entry in er.async_entries_for_config_entry(ent_reg, entry_id):
+ if (
+ entity_entry.domain == platform
+ and entity_entry.disabled
+ and entity_entry.unique_id not in unique_ids
+ ):
+ ent_reg.async_remove(entity_entry.entity_id)
+ continue

homeassistant/components/tplink/entity.py

@@ -18,7 +18,7 @@
 )
 
 from homeassistant.const import EntityCategory
-from homeassistant.core import callback
+from homeassistant.core import HomeAssistant, callback
 from homeassistant.exceptions import HomeAssistantError
 from homeassistant.helpers import device_registry as dr
 from homeassistant.helpers.device_registry import DeviceInfo
@@ -36,6 +36,7 @@
  PRIMARY_STATE_ID,
 )
 from .coordinator import TPLinkDataUpdateCoordinator
+from .deprecate import DeprecatedInfo, async_check_create_deprecated
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -87,6 +88,8 @@
 class TPLinkFeatureEntityDescription(EntityDescription):
  """Base class for a TPLink feature based entity description."""
 
+ deprecated_info: DeprecatedInfo | None = None
+
 
 def async_refresh_after[_T: CoordinatedTPLinkEntity, **_P](
  func: Callable[Concatenate[_T, _P], Awaitable[None]],
@@ -251,18 +254,25 @@ def __init__(
 
  def _get_unique_id(self) -> str:
  """Return unique ID for the entity."""
- key = self.entity_description.key
+ return self._get_feature_unique_id(self._device, self.entity_description)
+
+ @staticmethod
+ def _get_feature_unique_id(
+ device: Device, entity_description: TPLinkFeatureEntityDescription
+ ) -> str:
+ """Return unique ID for the entity."""
+ key = entity_description.key
  # The unique id for the state feature in the switch platform is the
  # device_id
  if key == PRIMARY_STATE_ID:
- return legacy_device_id(self._device)
+ return legacy_device_id(device)
 
  # Historically the legacy device emeter attributes which are now
  # replaced with features used slightly different keys. This ensures
  # that those entities are not orphaned. Returns the mapped key or the
  # provided key if not mapped.
  key = LEGACY_KEY_MAPPING.get(key, key)
- return f"{legacy_device_id(self._device)}_{key}"
+ return f"{legacy_device_id(device)}_{key}"
 
  @classmethod
  def _category_for_feature(cls, feature: Feature | None) -> EntityCategory | None:
@@ -334,6 +344,7 @@ def _entities_for_device[
  _D: TPLinkFeatureEntityDescription,
  ](
  cls,
+ hass: HomeAssistant,
  device: Device,
  coordinator: TPLinkDataUpdateCoordinator,
  *,
@@ -368,6 +379,11 @@ def _entities_for_device[
  feat, descriptions, device=device, parent=parent
  )
  )
+ and async_check_create_deprecated(
+ hass,
+ cls._get_feature_unique_id(device, desc),
+ desc,
+ )
  ]
  return entities
 
@@ -377,6 +393,7 @@ def entities_for_device_and_its_children[
  _D: TPLinkFeatureEntityDescription,
  ](
  cls,
+ hass: HomeAssistant,
  device: Device,
  coordinator: TPLinkDataUpdateCoordinator,
  *,
@@ -393,6 +410,7 @@ def entities_for_device_and_its_children[
  # Add parent entities before children so via_device id works.
  entities.extend(
  cls._entities_for_device(
+ hass,
  device,
  coordinator=coordinator,
  feature_type=feature_type,
@@ -412,6 +430,7 @@ def entities_for_device_and_its_children[
  child_coordinator = coordinator
  entities.extend(
  cls._entities_for_device(
+ hass,
  child,
  coordinator=child_coordinator,
  feature_type=feature_type,

homeassistant/components/tplink/number.py

@@ -67,6 +67,7 @@ async def async_setup_entry(
  children_coordinators = data.children_coordinators
  device = parent_coordinator.device
  entities = CoordinatedTPLinkFeatureEntity.entities_for_device_and_its_children(
+ hass=hass,
  device=device,
  coordinator=parent_coordinator,
  feature_type=Feature.Type.Number,

homeassistant/components/tplink/select.py

@@ -54,6 +54,7 @@ async def async_setup_entry(
  device = parent_coordinator.device
 
  entities = CoordinatedTPLinkFeatureEntity.entities_for_device_and_its_children(
+ hass=hass,
  device=device,
  coordinator=parent_coordinator,
  feature_type=Feature.Type.Choice,

homeassistant/components/tplink/sensor.py

@@ -8,6 +8,7 @@
 from kasa import Feature
 
 from homeassistant.components.sensor import (
+ DOMAIN as SENSOR_DOMAIN,
  SensorDeviceClass,
  SensorEntity,
  SensorEntityDescription,
@@ -18,6 +19,7 @@
 
 from . import TPLinkConfigEntry
 from .const import UNIT_MAPPING
+from .deprecate import async_cleanup_deprecated
 from .entity import CoordinatedTPLinkFeatureEntity, TPLinkFeatureEntityDescription
 
 
@@ -128,13 +130,15 @@ async def async_setup_entry(
  device = parent_coordinator.device
 
  entities = CoordinatedTPLinkFeatureEntity.entities_for_device_and_its_children(
+ hass=hass,
  device=device,
  coordinator=parent_coordinator,
  feature_type=Feature.Type.Sensor,
  entity_class=TPLinkSensorEntity,
  descriptions=SENSOR_DESCRIPTIONS_MAP,
  child_coordinators=children_coordinators,
  )
+ async_cleanup_deprecated(hass, SENSOR_DOMAIN, config_entry.entry_id, entities)
  async_add_entities(entities)
 
 

homeassistant/components/tplink/strings.json

@@ -311,5 +311,11 @@
  "device_authentication": {
  "message": "Device authentication error {func}: {exc}"
  }
+ },
+ "issues": {
+ "deprecated_entity": {
+ "title": "Detected deprecated `{platform}` entity usage",
+ "description": "We detected that entity `{entity}` is being used in `{info}`\n\nWe have created a new `{new_platform}` entity and you should migrate `{info}` to use this new entity.\n\nWhen you are done migrating `{info}` and are ready to have the deprecated `{entity}` entity removed, disable the entity and restart Home Assistant."
+ }
  }
 }

homeassistant/components/tplink/switch.py

@@ -64,7 +64,8 @@ async def async_setup_entry(
  device = parent_coordinator.device
 
  entities = CoordinatedTPLinkFeatureEntity.entities_for_device_and_its_children(
- device,
+ hass=hass,
+ device=device,
  coordinator=parent_coordinator,
  feature_type=Feature.Switch,
  entity_class=TPLinkSwitch,

tests/components/tplink/__init__.py

@@ -21,6 +21,7 @@
 from kasa.smart.modules.alarm import Alarm
 from syrupy import SnapshotAssertion
 
+from homeassistant.components.automation import DOMAIN as AUTOMATION_DOMAIN
 from homeassistant.components.tplink import (
  CONF_AES_KEYS,
  CONF_ALIAS,
@@ -184,6 +185,21 @@ async def snapshot_platform(
  ), f"state snapshot failed for {entity_entry.entity_id}"
 
 
+async def setup_automation(hass: HomeAssistant, alias: str, entity_id: str) -> None:
+ """Set up an automation for tests."""
+ assert await async_setup_component(
+ hass,
+ AUTOMATION_DOMAIN,
+ {
+ AUTOMATION_DOMAIN: {
+ "alias": alias,
+ "trigger": {"platform": "state", "entity_id": entity_id, "to": "on"},
+ "action": {"action": "notify.notify", "metadata": {}, "data": {}},
+ }
+ },
+ )
+
+
 def _mock_protocol() -> BaseProtocol:
  protocol = MagicMock(spec=BaseProtocol)
  protocol.close = AsyncMock()