Add notify entity component (#110950)

* Add notify entity component

* Device classes, restore state, icons

* Add icons file

* Add tests for kitchen_sink

* Remove notify from no_entity_platforms in hassfest icons, translation link

* ruff

* Remove `data` feature

* Only message support

* Complete initial device classes

* mypy pylint

* Remove device_class implementation

* format

* Follow up comments

* Remove _attr_supported_features

* Use setup_test_component_platform

* User helper at other places

* last comment

* Add entry unload test and non async test

* Avoid default mutable object in constructor

Author: jbouwh

homeassistant/components/kitchen_sink/__init__.py

@@ -32,6 +32,7 @@
     Platform.IMAGE,
     Platform.LAWN_MOWER,
     Platform.LOCK,
+    Platform.NOTIFY,
     Platform.SENSOR,
     Platform.SWITCH,
     Platform.WEATHER,
@@ -70,7 +71,7 @@ async def async_setup_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> b
     return True
 
 
-def _create_issues(hass):
+def _create_issues(hass: HomeAssistant) -> None:
     """Create some issue registry issues."""
     async_create_issue(
         hass,

homeassistant/components/kitchen_sink/notify.py

@@ -0,0 +1,54 @@
+"""Demo platform that offers a fake notify entity."""
+
+from __future__ import annotations
+
+from homeassistant.components import persistent_notification
+from homeassistant.components.notify import NotifyEntity
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.device_registry import DeviceInfo
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+
+from . import DOMAIN
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    config_entry: ConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up the demo notify entity platform."""
+    async_add_entities(
+        [
+            DemoNotify(
+                unique_id="just_notify_me",
+                device_name="MyBox",
+                entity_name="Personal notifier",
+            ),
+        ]
+    )
+
+
+class DemoNotify(NotifyEntity):
+    """Representation of a demo notify entity."""
+
+    _attr_has_entity_name = True
+    _attr_should_poll = False
+
+    def __init__(
+        self,
+        unique_id: str,
+        device_name: str,
+        entity_name: str | None,
+    ) -> None:
+        """Initialize the Demo button entity."""
+        self._attr_unique_id = unique_id
+        self._attr_device_info = DeviceInfo(
+            identifiers={(DOMAIN, unique_id)},
+            name=device_name,
+        )
+        self._attr_name = entity_name
+
+    async def async_send_message(self, message: str) -> None:
+        """Send out a persistent notification."""
+        persistent_notification.async_create(self.hass, message, "Demo notification")

homeassistant/components/notify/__init__.py

@@ -2,24 +2,36 @@
 
 from __future__ import annotations
 
+from datetime import timedelta
+from functools import cached_property, partial
+import logging
+from typing import Any, final, override
+
 import voluptuous as vol
 
 import homeassistant.components.persistent_notification as pn
-from homeassistant.const import CONF_NAME, CONF_PLATFORM
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import CONF_NAME, CONF_PLATFORM, STATE_UNAVAILABLE
 from homeassistant.core import HomeAssistant, ServiceCall
 import homeassistant.helpers.config_validation as cv
+from homeassistant.helpers.entity import EntityDescription
+from homeassistant.helpers.entity_component import EntityComponent
+from homeassistant.helpers.restore_state import RestoreEntity
 from homeassistant.helpers.template import Template
 from homeassistant.helpers.typing import ConfigType
+from homeassistant.util import dt as dt_util
 
 from .const import (  # noqa: F401
     ATTR_DATA,
     ATTR_MESSAGE,
+    ATTR_RECIPIENTS,
     ATTR_TARGET,
     ATTR_TITLE,
     DOMAIN,
     NOTIFY_SERVICE_SCHEMA,
     SERVICE_NOTIFY,
     SERVICE_PERSISTENT_NOTIFICATION,
+    SERVICE_SEND_MESSAGE,
 )
 from .legacy import (  # noqa: F401
     BaseNotificationService,
@@ -29,9 +41,17 @@
     check_templates_warn,
 )
 
+# mypy: disallow-any-generics
+
 # Platform specific data
 ATTR_TITLE_DEFAULT = "Home Assistant"
 
+ENTITY_ID_FORMAT = DOMAIN + ".{}"
+
+MIN_TIME_BETWEEN_SCANS = timedelta(seconds=10)
+
+_LOGGER = logging.getLogger(__name__)
+
 PLATFORM_SCHEMA = vol.Schema(
     {vol.Required(CONF_PLATFORM): cv.string, vol.Optional(CONF_NAME): cv.string},
     extra=vol.ALLOW_EXTRA,
@@ -50,6 +70,13 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
         # legacy platforms to finish setting up.
         hass.async_create_task(setup, eager_start=True)
 
+    component = hass.data[DOMAIN] = EntityComponent[NotifyEntity](_LOGGER, DOMAIN, hass)
+    component.async_register_entity_service(
+        SERVICE_SEND_MESSAGE,
+        {vol.Required(ATTR_MESSAGE): cv.string},
+        "_async_send_message",
+    )
+
     async def persistent_notification(service: ServiceCall) -> None:
         """Send notification via the built-in persistent_notify integration."""
         message: Template = service.data[ATTR_MESSAGE]
@@ -79,3 +106,66 @@ async def persistent_notification(service: ServiceCall) -> None:
     )
 
     return True
+
+
+class NotifyEntityDescription(EntityDescription, frozen_or_thawed=True):
+    """A class that describes button entities."""
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Set up a config entry."""
+    component: EntityComponent[NotifyEntity] = hass.data[DOMAIN]
+    return await component.async_setup_entry(entry)
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Unload a config entry."""
+    component: EntityComponent[NotifyEntity] = hass.data[DOMAIN]
+    return await component.async_unload_entry(entry)
+
+
+class NotifyEntity(RestoreEntity):
+    """Representation of a notify entity."""
+
+    entity_description: NotifyEntityDescription
+    _attr_should_poll = False
+    _attr_device_class: None
+    _attr_state: None = None
+    __last_notified_isoformat: str | None = None
+
+    @cached_property
+    @final
+    @override
+    def state(self) -> str | None:
+        """Return the entity state."""
+        return self.__last_notified_isoformat
+
+    def __set_state(self, state: str | None) -> None:
+        """Invalidate the cache of the cached property."""
+        self.__dict__.pop("state", None)
+        self.__last_notified_isoformat = state
+
+    async def async_internal_added_to_hass(self) -> None:
+        """Call when the notify entity is added to hass."""
+        await super().async_internal_added_to_hass()
+        state = await self.async_get_last_state()
+        if state is not None and state.state not in (STATE_UNAVAILABLE, None):
+            self.__set_state(state.state)
+
+    @final
+    async def _async_send_message(self, **kwargs: Any) -> None:
+        """Send a notification message (from e.g., service call).
+
+        Should not be overridden, handle setting last notification timestamp.
+        """
+        self.__set_state(dt_util.utcnow().isoformat())
+        self.async_write_ha_state()
+        await self.async_send_message(**kwargs)
+
+    def send_message(self, message: str) -> None:
+        """Send a message."""
+        raise NotImplementedError
+
+    async def async_send_message(self, message: str) -> None:
+        """Send a message."""
+        await self.hass.async_add_executor_job(partial(self.send_message, message))

homeassistant/components/notify/const.py

@@ -11,9 +11,12 @@
 # Text to notify user of
 ATTR_MESSAGE = "message"
 
-# Target of the notification (user, device, etc)
+# Target of the (legacy) notification (user, device, etc)
 ATTR_TARGET = "target"
 
+# Recipients for a notification
+ATTR_RECIPIENTS = "recipients"
+
 # Title of notification
 ATTR_TITLE = "title"
 
@@ -22,6 +25,7 @@
 LOGGER = logging.getLogger(__package__)
 
 SERVICE_NOTIFY = "notify"
+SERVICE_SEND_MESSAGE = "send_message"
 SERVICE_PERSISTENT_NOTIFICATION = "persistent_notification"
 
 NOTIFY_SERVICE_SCHEMA = vol.Schema(

homeassistant/components/notify/icons.json

@@ -1,6 +1,12 @@
 {
+  "entity_component": {
+    "_": {
+      "default": "mdi:message"
+    }
+  },
   "services": {
     "notify": "mdi:bell-ring",
-    "persistent_notification": "mdi:bell-badge"
+    "persistent_notification": "mdi:bell-badge",
+    "send_message": "mdi:message-arrow-right"
   }
 }

homeassistant/components/notify/services.yaml

@@ -20,6 +20,16 @@ notify:
       selector:
         object:
 
+send_message:
+  target:
+    entity:
+      domain: notify
+  fields:
+    message:
+      required: true
+      selector:
+        text:
+
 persistent_notification:
   fields:
     message:

homeassistant/components/notify/strings.json

@@ -1,5 +1,10 @@
 {
   "title": "Notifications",
+  "entity_component": {
+    "_": {
+      "name": "[%key:component::notify::title%]"
+    }
+  },
   "services": {
     "notify": {
       "name": "Send a notification",
@@ -23,6 +28,16 @@
         }
       }
     },
+    "send_message": {
+      "name": "Send a notification message",
+      "description": "Sends a notification message.",
+      "fields": {
+        "message": {
+          "name": "Message",
+          "description": "Your notification message."
+        }
+      }
+    },
     "persistent_notification": {
       "name": "Send a persistent notification",
       "description": "Sends a notification that is visible in the **Notifications** panel.",

homeassistant/helpers/service.py

@@ -93,6 +93,7 @@ def _base_components() -> dict[str, ModuleType]:
         light,
         lock,
         media_player,
+        notify,
         remote,
         siren,
         todo,
@@ -112,6 +113,7 @@ def _base_components() -> dict[str, ModuleType]:
         "light": light,
         "lock": lock,
         "media_player": media_player,
+        "notify": notify,
         "remote": remote,
         "siren": siren,
         "todo": todo,

tests/components/kitchen_sink/test_notify.py

@@ -0,0 +1,66 @@
+"""The tests for the demo button component."""
+
+from collections.abc import AsyncGenerator
+from unittest.mock import patch
+
+from freezegun.api import FrozenDateTimeFactory
+import pytest
+
+from homeassistant.components.kitchen_sink import DOMAIN
+from homeassistant.components.notify import (
+    DOMAIN as NOTIFY_DOMAIN,
+    SERVICE_SEND_MESSAGE,
+)
+from homeassistant.components.notify.const import ATTR_MESSAGE
+from homeassistant.const import ATTR_ENTITY_ID, STATE_UNKNOWN, Platform
+from homeassistant.core import HomeAssistant
+from homeassistant.setup import async_setup_component
+from homeassistant.util import dt as dt_util
+
+ENTITY_DIRECT_MESSAGE = "notify.mybox_personal_notifier"
+
+
+@pytest.fixture
+async def notify_only() -> AsyncGenerator[None, None]:
+    """Enable only the button platform."""
+    with patch(
+        "homeassistant.components.kitchen_sink.COMPONENTS_WITH_DEMO_PLATFORM",
+        [Platform.NOTIFY],
+    ):
+        yield
+
+
+@pytest.fixture(autouse=True)
+async def setup_comp(hass: HomeAssistant, notify_only: None):
+    """Set up demo component."""
+    assert await async_setup_component(hass, DOMAIN, {DOMAIN: {}})
+    await hass.async_block_till_done()
+
+
+def test_setup_params(hass: HomeAssistant) -> None:
+    """Test the initial parameters."""
+    state = hass.states.get(ENTITY_DIRECT_MESSAGE)
+    assert state
+    assert state.state == STATE_UNKNOWN
+
+
+async def test_send_message(
+    hass: HomeAssistant, freezer: FrozenDateTimeFactory
+) -> None:
+    """Test pressing the button."""
+    state = hass.states.get(ENTITY_DIRECT_MESSAGE)
+    assert state
+    assert state.state == STATE_UNKNOWN
+
+    now = dt_util.parse_datetime("2021-01-09 12:00:00+00:00")
+    freezer.move_to(now)
+    await hass.services.async_call(
+        NOTIFY_DOMAIN,
+        SERVICE_SEND_MESSAGE,
+        {ATTR_ENTITY_ID: ENTITY_DIRECT_MESSAGE, ATTR_MESSAGE: "You have an update!"},
+        blocking=True,
+    )
+
+    state = hass.states.get(ENTITY_DIRECT_MESSAGE)
+    assert state
+    assert state.state == now.isoformat()

tests/components/notify/conftest.py

@@ -0,0 +1,23 @@
+"""Fixtures for Notify platform tests."""
+
+from collections.abc import Generator
+
+import pytest
+
+from homeassistant.config_entries import ConfigFlow
+from homeassistant.core import HomeAssistant
+
+from tests.common import mock_config_flow, mock_platform
+
+
+class MockFlow(ConfigFlow):
+    """Test flow."""
+
+
+@pytest.fixture
+def config_flow_fixture(hass: HomeAssistant) -> Generator[None, None, None]:
+    """Mock config flow."""
+    mock_platform(hass, "test.config_flow")
+
+    with mock_config_flow("test", MockFlow):
+        yield