From d727f8ff5081851f613ce65abbaf80a9601e6c84 Mon Sep 17 00:00:00 2001 From: G Johansson Date: Mon, 28 Oct 2024 23:05:06 +0100 Subject: [PATCH] Clarify event tracking in docstrings for track_state_change/report (#129338) * Clarify event tracking in docstrings for track_state_change/report * Fixes * Update homeassistant/helpers/event.py * Update homeassistant/helpers/event.py Co-authored-by: J. Nick Koston --------- Co-authored-by: Erik Montnemery Co-authored-by: J. Nick Koston --- homeassistant/helpers/event.py | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/homeassistant/helpers/event.py b/homeassistant/helpers/event.py index 97a85fdde89..02ea8103192 100644 --- a/homeassistant/helpers/event.py +++ b/homeassistant/helpers/event.py @@ -322,6 +322,10 @@ def async_track_state_change_event( for each one, we keep a dict of entity ids that care about the state change events so we can do a fast dict lookup to route events. + The passed in entity_ids will be automatically lower cased. + + EVENT_STATE_CHANGED is fired on each occasion the state is updated + and changed, opposite of EVENT_STATE_REPORTED. """ if not (entity_ids := _async_string_to_lower_list(entity_ids)): return _remove_empty_listener @@ -383,7 +387,10 @@ def _async_track_state_change_event( action: Callable[[Event[EventStateChangedData]], Any], job_type: HassJobType | None, ) -> CALLBACK_TYPE: - """async_track_state_change_event without lowercasing.""" + """Faster version of async_track_state_change_event. + + The passed in entity_ids will not be automatically lower cased. + """ return _async_track_event( _KEYED_TRACK_STATE_CHANGE, hass, entity_ids, action, job_type ) @@ -403,7 +410,11 @@ def async_track_state_report_event( action: Callable[[Event[EventStateReportedData]], Any], job_type: HassJobType | None = None, ) -> CALLBACK_TYPE: - """Track EVENT_STATE_REPORTED by entity_id without lowercasing.""" + """Track EVENT_STATE_REPORTED by entity_ids. + + EVENT_STATE_REPORTED is fired on each occasion the state is updated + but not changed, opposite of EVENT_STATE_CHANGED. + """ return _async_track_event( _KEYED_TRACK_STATE_REPORT, hass, entity_ids, action, job_type )