diff --git a/homeassistant/helpers/event.py b/homeassistant/helpers/event.py index 648a118f175..7fae0976686 100644 --- a/homeassistant/helpers/event.py +++ b/homeassistant/helpers/event.py @@ -38,6 +38,7 @@ from homeassistant.util import dt as dt_util from homeassistant.util.async_ import run_callback_threadsafe from homeassistant.util.event_type import EventType +from . import frame from .device_registry import ( EVENT_DEVICE_REGISTRY_UPDATED, EventDeviceRegistryUpdatedData, @@ -203,8 +204,16 @@ def async_track_state_change( being None, async_track_state_change_event should be used instead as it is slightly faster. + This function is deprecated and will be removed in Home Assistant 2025.5. + Must be run within the event loop. """ + frame.report( + "calls `async_track_state_change` instead of `async_track_state_change_event`" + " which is deprecated and will be removed in Home Assistant 2025.5", + error_if_core=False, + ) + if from_state is not None: match_from_state = process_state_match(from_state) if to_state is not None: diff --git a/tests/helpers/test_event.py b/tests/helpers/test_event.py index a4235d1ee2c..07228abcc2c 100644 --- a/tests/helpers/test_event.py +++ b/tests/helpers/test_event.py @@ -4804,3 +4804,18 @@ async def test_async_track_device_registry_updated_event_with_a_callback_that_th unsub2() assert event_data[0] == {"action": "create", "device_id": device_id} + + +async def test_track_state_change_deprecated( + hass: HomeAssistant, caplog: pytest.LogCaptureFixture +) -> None: + """Test track_state_change is deprecated.""" + async_track_state_change( + hass, "light.Bowl", lambda entity_id, old_state, new_state: None, "on", "off" + ) + + assert ( + "Detected code that calls `async_track_state_change` instead " + "of `async_track_state_change_event` which is deprecated and " + "will be removed in Home Assistant 2025.5. Please report this issue." + ) in caplog.text