diff --git a/blog/2022-07-08-config_entry_forwards.md b/blog/2022-07-08-config_entry_forwards.md index f28aedba..4716161f 100644 --- a/blog/2022-07-08-config_entry_forwards.md +++ b/blog/2022-07-08-config_entry_forwards.md @@ -6,6 +6,6 @@ title: "Waiting for config entry platforms" Before 2022.8, it was impossible to `await` config entry platforms forwards without a deadlock if one of the platforms loaded by the config entry was not already loaded. -Integrations need to be refactored to replace calls to `hass.config_entries.async_setup_platforms` with `hass.config_entries.async_forward_entry_setups` and/or await all `hass.config_entries.async_forward_entry_setup` to ensure that Home Assistant does not inadvertently reload the integration while entities and platforms are still being set up. +Integrations need to be refactored to replace calls to `hass.config_entries.async_setup_platforms` with awaiting `hass.config_entries.async_forward_entry_setups` to ensure that Home Assistant does not inadvertently reload the integration while entities and platforms are still being set up. `hass.config_entries.async_setup_platforms` is scheduled to be removed in 2022.12. \ No newline at end of file diff --git a/blog/2024-06-12-async_forward_entry_setups.md b/blog/2024-06-12-async_forward_entry_setups.md new file mode 100644 index 00000000..18cc1cc1 --- /dev/null +++ b/blog/2024-06-12-async_forward_entry_setups.md @@ -0,0 +1,9 @@ +--- +author: J. Nick Koston +authorURL: https://github.com/bdraco +title: Forwarding setup to config entry platforms +--- + +Calling `hass.config_entries.async_forward_entry_setup` is deprecated and will be removed in Home Assistant 2025.6. Instead, await `hass.config_entries.async_forward_entry_setups` as it can load multiple platforms at once and is more efficient since it does not require a separate import executor job for each platform. + +`hass.config_entries.async_forward_entry_setups` must always be awaited if it's called while the config entry is being set up to ensure that it finishes before the config entry setup is complete. For more details, review [this blog post](https://developers.home-assistant.io/blog/2022/07/08/config_entry_forwards). diff --git a/docs/config_entries_index.md b/docs/config_entries_index.md index 555c1675..eb953689 100644 --- a/docs/config_entries_index.md +++ b/docs/config_entries_index.md @@ -112,23 +112,18 @@ digraph G { During startup, Home Assistant first calls the [normal component setup](/creating_component_index.md), and then call the method `async_setup_entry(hass, entry)` for each entry. If a new Config Entry is -created at runtime, Home Assistant will also call `async_setup_entry(hass, entry)` ([example](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/hue/__init__.py#L119)). +created at runtime, Home Assistant will also call `async_setup_entry(hass, entry)` ([example](https://github.com/home-assistant/core/blob/f18ddb628c3574bc82e21563d9ba901bd75bc8b5/homeassistant/components/hassio/__init__.py#L522)). ### For platforms If a component includes platforms, it will need to forward the Config Entry to the platform. This can -be done by calling the forward function on the config entry manager ([example](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/hue/bridge.py#L81)): +be done by calling the forward function on the config entry manager ([example](https://github.com/home-assistant/core/blob/f18ddb628c3574bc82e21563d9ba901bd75bc8b5/homeassistant/components/hassio/__init__.py#L529)): ```python -# Use `hass.async_create_task` to avoid a circular dependency between the platform and the component -hass.async_create_task( - hass.config_entries.async_forward_entry_setup( - config_entry, "light" - ) -) +await hass.config_entries.async_forward_entry_setups(config_entry, ["light", "sensor", "switch"]) ``` -For a platform to support config entries, it will need to add a setup entry method ([example](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/light/hue.py#L60)): +For a platform to support config entries, it will need to add a setup entry method ([example](https://github.com/home-assistant/core/blob/f18ddb628c3574bc82e21563d9ba901bd75bc8b5/homeassistant/components/hassio/__init__.py#L522)): ```python async def async_setup_entry(hass, config_entry, async_add_entities): @@ -137,7 +132,7 @@ async def async_setup_entry(hass, config_entry, async_add_entities): ## Unloading entries -Components can optionally support unloading a config entry. When unloading an entry, the component needs to clean up all entities, unsubscribe any event listener and close all connections. To implement this, add `async_unload_entry(hass, entry)` to your component ([example](https://github.com/home-assistant/core/blob/0.68.0/homeassistant/components/hue/__init__.py#L136)). +Components can optionally support unloading a config entry. When unloading an entry, the component needs to clean up all entities, unsubscribe any event listener and close all connections. To implement this, add `async_unload_entry(hass, entry)` to your component ([example](https://github.com/home-assistant/core/blob/f18ddb628c3574bc82e21563d9ba901bd75bc8b5/homeassistant/components/hassio/__init__.py#L534)). For each platform that you forwarded the config entry to, you will need to forward the unloading too.