Add standard event type for doorbell event entities (#167630)

Author: abmantis

homeassistant/components/event/__init__.py

@@ -20,7 +20,7 @@
 from homeassistant.util import dt as dt_util
 from homeassistant.util.hass_dict import HassKey
 
-from .const import ATTR_EVENT_TYPE, ATTR_EVENT_TYPES, DOMAIN
+from .const import ATTR_EVENT_TYPE, ATTR_EVENT_TYPES, DOMAIN, DoorbellEventType
 
 _LOGGER = logging.getLogger(__name__)
 DATA_COMPONENT: HassKey[EntityComponent[EventEntity]] = HassKey(DOMAIN)
@@ -44,6 +44,7 @@ class EventDeviceClass(StrEnum):
     "DOMAIN",
     "PLATFORM_SCHEMA",
     "PLATFORM_SCHEMA_BASE",
+    "DoorbellEventType",
     "EventDeviceClass",
     "EventEntity",
     "EventEntityDescription",
@@ -189,6 +190,21 @@ def state_attributes(self) -> dict[str, Any]:
     async def async_internal_added_to_hass(self) -> None:
         """Call when the event entity is added to hass."""
         await super().async_internal_added_to_hass()
+
+        if (
+            self.device_class == EventDeviceClass.DOORBELL
+            and DoorbellEventType.RING not in self.event_types
+        ):
+            report_issue = self._suggest_report_issue()
+            _LOGGER.warning(
+                "Entity %s is a doorbell event entity but does not support "
+                "the '%s' event type. This will stop working in "
+                "Home Assistant 2027.4, please %s",
+                self.entity_id,
+                DoorbellEventType.RING,
+                report_issue,
+            )
+
         if (
             (state := await self.async_get_last_state())
             and state.state is not None

homeassistant/components/event/const.py

@@ -1,5 +1,13 @@
 """Provides the constants needed for the component."""
 
+from enum import StrEnum
+
 DOMAIN = "event"
 ATTR_EVENT_TYPE = "event_type"
 ATTR_EVENT_TYPES = "event_types"
+
+
+class DoorbellEventType(StrEnum):
+    """Standard event types for doorbell device class."""
+
+    RING = "ring"

homeassistant/components/event/strings.json

@@ -15,7 +15,14 @@
       "name": "Button"
     },
     "doorbell": {
-      "name": "Doorbell"
+      "name": "Doorbell",
+      "state_attributes": {
+        "event_type": {
+          "state": {
+            "ring": "Ring"
+          }
+        }
+      }
     },
     "motion": {
       "name": "Motion"

tests/components/event/test_init.py

@@ -10,6 +10,7 @@
     ATTR_EVENT_TYPE,
     ATTR_EVENT_TYPES,
     DOMAIN,
+    DoorbellEventType,
     EventDeviceClass,
     EventEntity,
     EventEntityDescription,
@@ -34,6 +35,7 @@
     mock_platform,
     mock_restore_cache,
     mock_restore_cache_with_extra_data,
+    setup_test_component_platform,
 )
 
 
@@ -344,3 +346,68 @@ async def async_setup_entry_platform(
         "device_class": "doorbell",
         "friendly_name": "Doorbell",
     }
+
+
+@pytest.mark.usefixtures("config_flow_fixture")
+async def test_doorbell_missing_ring_event_type(
+    hass: HomeAssistant,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Test warning when a doorbell entity does not include the standard ring event type."""
+
+    async def async_setup_entry_init(
+        hass: HomeAssistant, config_entry: ConfigEntry
+    ) -> bool:
+        """Set up test config entry."""
+        await hass.config_entries.async_forward_entry_setups(
+            config_entry, [Platform.EVENT]
+        )
+        return True
+
+    mock_platform(hass, f"{TEST_DOMAIN}.config_flow")
+    mock_integration(
+        hass,
+        MockModule(
+            TEST_DOMAIN,
+            async_setup_entry=async_setup_entry_init,
+        ),
+    )
+
+    # Doorbell entity WITHOUT the standard "ring" event type
+    entity_without_ring = EventEntity()
+    entity_without_ring._attr_event_types = ["ding"]
+    entity_without_ring._attr_device_class = EventDeviceClass.DOORBELL
+    entity_without_ring._attr_has_entity_name = True
+    entity_without_ring.entity_id = "event.doorbell_without_ring"
+
+    # Doorbell entity WITH the standard "ring" event type
+    entity_with_ring = EventEntity()
+    entity_with_ring._attr_event_types = [DoorbellEventType.RING, "ding"]
+    entity_with_ring._attr_device_class = EventDeviceClass.DOORBELL
+    entity_with_ring._attr_has_entity_name = True
+    entity_with_ring.entity_id = "event.doorbell_with_ring"
+
+    # Non-doorbell entity should not warn
+    entity_button = EventEntity()
+    entity_button._attr_event_types = ["press"]
+    entity_button._attr_device_class = EventDeviceClass.BUTTON
+    entity_button._attr_has_entity_name = True
+    entity_button.entity_id = "event.button"
+
+    setup_test_component_platform(
+        hass,
+        DOMAIN,
+        [entity_without_ring, entity_with_ring, entity_button],
+        from_config_entry=True,
+    )
+    config_entry = MockConfigEntry(domain=TEST_DOMAIN)
+    config_entry.add_to_hass(hass)
+    assert await hass.config_entries.async_setup(config_entry.entry_id)
+    await hass.async_block_till_done()
+
+    assert (
+        "Entity event.doorbell_without_ring is a doorbell event entity "
+        "but does not support the 'ring' event type"
+    ) in caplog.text
+    assert "event.doorbell_with_ring" not in caplog.text
+    assert "event.button" not in caplog.text