Deprecate calling async_listen and async_listen_once with run_immediately (#115169)

homeassistant/core.py

@@ -136,6 +136,7 @@ _P = ParamSpec("_P")
 _Ts = TypeVarTuple("_Ts")
 # Internal; not helpers.typing.UNDEFINED due to circular dependency
 _UNDEF: dict[Any, Any] = {}
+_SENTINEL = object()
 _CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
 _DataT = TypeVar("_DataT", bound=Mapping[str, Any], default=Mapping[str, Any])
 CALLBACK_TYPE = Callable[[], None]
@@ -1355,7 +1356,6 @@ def _event_repr(
 _FilterableJobType = tuple[
     HassJob[[Event[_DataT]], Coroutine[Any, Any, None] | None],  # job
     Callable[[_DataT], bool] | None,  # event_filter
-    bool,  # run_immediately
 ]
 
 
@@ -1399,9 +1399,7 @@ class EventBus:
         self._listeners[MATCH_ALL] = self._match_all_listeners
         self._hass = hass
         self._async_logging_changed()
-        self.async_listen(
-            EVENT_LOGGING_CHANGED, self._async_logging_changed, run_immediately=True
-        )
+        self.async_listen(EVENT_LOGGING_CHANGED, self._async_logging_changed)
 
     @callback
     def _async_logging_changed(self, event: Event | None = None) -> None:
@@ -1486,7 +1484,7 @@ class EventBus:
 
         event: Event[_DataT] | None = None
 
-        for job, event_filter, run_immediately in listeners:
+        for job, event_filter in listeners:
             if event_filter is not None:
                 try:
                     if event_data is None or not event_filter(event_data):
@@ -1504,14 +1502,10 @@ class EventBus:
                     context,
                 )
 
-            if run_immediately:
-                try:
-                    self._hass.async_run_hass_job(job, event)
-                except Exception:  # pylint: disable=broad-except
-                    _LOGGER.exception("Error running job: %s", job)
-            else:
-                # pylint: disable-next=protected-access
-                self._hass._async_add_hass_job(job, event)
+            try:
+                self._hass.async_run_hass_job(job, event)
+            except Exception:  # pylint: disable=broad-except
+                _LOGGER.exception("Error running job: %s", job)
 
     def listen(
         self,
@@ -1539,7 +1533,7 @@ class EventBus:
         event_type: EventType[_DataT] | str,
         listener: Callable[[Event[_DataT]], Coroutine[Any, Any, None] | None],
         event_filter: Callable[[_DataT], bool] | None = None,
-        run_immediately: bool = True,
+        run_immediately: bool | object = _SENTINEL,
     ) -> CALLBACK_TYPE:
         """Listen for all events or events of a specific type.
 
@@ -1556,6 +1550,16 @@ class EventBus:
 
         This method must be run in the event loop.
         """
+        if run_immediately in (True, False):
+            # late import to avoid circular imports
+            from .helpers import frame  # pylint: disable=import-outside-toplevel
+
+            frame.report(
+                "calls `async_listen` with run_immediately, which is"
+                " deprecated and will be removed in Assistant 2025.5",
+                error_if_core=False,
+            )
+
         if event_filter is not None and not is_callback_check_partial(event_filter):
             raise HomeAssistantError(f"Event filter {event_filter} is not a callback")
         if event_type == EVENT_STATE_REPORTED:
@@ -1563,16 +1567,11 @@ class EventBus:
                 raise HomeAssistantError(
                     f"Event filter is required for event {event_type}"
                 )
-            if not run_immediately:
-                raise HomeAssistantError(
-                    f"Run immediately must be set to True for event {event_type}"
-                )
         return self._async_listen_filterable_job(
             event_type,
             (
                 HassJob(listener, f"listen {event_type}"),
                 event_filter,
-                run_immediately,
             ),
         )
 
@@ -1614,7 +1613,7 @@ class EventBus:
         self,
         event_type: EventType[_DataT] | str,
         listener: Callable[[Event[_DataT]], Coroutine[Any, Any, None] | None],
-        run_immediately: bool = True,
+        run_immediately: bool | object = _SENTINEL,
     ) -> CALLBACK_TYPE:
         """Listen once for event of a specific type.
 
@@ -1625,6 +1624,16 @@ class EventBus:
 
         This method must be run in the event loop.
         """
+        if run_immediately in (True, False):
+            # late import to avoid circular imports
+            from .helpers import frame  # pylint: disable=import-outside-toplevel
+
+            frame.report(
+                "calls `async_listen_once` with run_immediately, which is "
+                "deprecated and will be removed in Assistant 2025.5",
+                error_if_core=False,
+            )
+
         one_time_listener: _OneTimeListener[_DataT] = _OneTimeListener(
             self._hass, HassJob(listener)
         )
@@ -1637,7 +1646,6 @@ class EventBus:
                     job_type=HassJobType.Callback,
                 ),
                 None,
-                run_immediately,
             ),
         )
         one_time_listener.remove = remove