From 9c52c1f5fda203bd17a5dc9ad504253d9ffe9eff Mon Sep 17 00:00:00 2001 From: Joakim Plate Date: Tue, 3 Jan 2023 16:18:25 +0100 Subject: [PATCH] Adjust development documentation with context (#1355) Co-authored-by: Franck Nijhof --- blog/2022-06-02-update_coordinator-context.md | 11 +++++++++++ docs/integration_fetching_data.md | 8 ++++++-- 2 files changed, 17 insertions(+), 2 deletions(-) create mode 100644 blog/2022-06-02-update_coordinator-context.md diff --git a/blog/2022-06-02-update_coordinator-context.md b/blog/2022-06-02-update_coordinator-context.md new file mode 100644 index 00000000..4f6b1135 --- /dev/null +++ b/blog/2022-06-02-update_coordinator-context.md @@ -0,0 +1,11 @@ +--- +author: Joakim Plate +authorURL: https://github.com/elupus +title: "Support context in update coordinator" +--- + +Starting with Home Assistant 2022.7, the update coordinator supports keeping track of context for each listening entity. This can be used to limit the requests against APIs based on enabled entities. + +This could be a breaking change for custom components that rely on update coordinators and inspect the internal variable `self._listeners` and/or overload the method async_remove_listener() to detect when there is no listeners anymore. Switch to using `async_update_listeners()` to trigger updates on all listeners, and overload `_unschedule_refresh()` to detect when there is no listeners. + +See the updated [integration fetching documentation](/docs/integration_fetching_data/#polling-api-endpoints) for more information on current use. diff --git a/docs/integration_fetching_data.md b/docs/integration_fetching_data.md index 5f379c5a..95057e8a 100644 --- a/docs/integration_fetching_data.md +++ b/docs/integration_fetching_data.md @@ -95,7 +95,11 @@ class MyCoordinator(DataUpdateCoordinator): # Note: asyncio.TimeoutError and aiohttp.ClientError are already # handled by the data update coordinator. async with async_timeout.timeout(10): - return await self.my_api.fetch_data() + # Grab active context variables to limit data required to be fetched from API + # Note: using context is not required if there is no need or ability to limit + # data retrieved from API. + listening_idx = set(self.async_contexts()) + return await self.my_api.fetch_data(listening_idx) except ApiAuthError as err: # Raising ConfigEntryAuthFailed will cancel future updates # and start a config flow with SOURCE_REAUTH (async_step_reauth) @@ -117,7 +121,7 @@ class MyEntity(CoordinatorEntity, LightEntity): def __init__(self, coordinator, idx): """Pass coordinator to CoordinatorEntity.""" - super().__init__(coordinator) + super().__init__(coordinator, context=idx) self.idx = idx @callback