jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-08 09:56:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add blog post about using async_forward_entry_setups instead of async_forward_entry_setup (#2203)

Browse Source 
* Add blog post about ensuring config entries are not unloaded while their platforms are setting up

* adjust existing docs

* Update blog/2024-06-04-ensure_config_entry_platforms_hold_lock.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* newline

* adjust block post for removal of async_late_forward_entry_setup

* adjust block post for removal of async_late_forward_entry_setup

* Update blog/2024-06-04-ensure_config_entry_platforms_hold_lock.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* rename

* Update blog date

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Paulus Schoutsen <balloob@gmail.com>
This commit is contained in:
J. Nick Koston 2024-06-12 20:13:39 -05:00 committed by GitHub
parent e49e2b7fbf
commit b8417d4b07
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 15 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
blog/2022-07-08-config_entry_forwards.md
View File

@ -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. 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. `hass.config_entries.async_setup_platforms` is scheduled to be removed in 2022.12.

9
blog/2024-06-12-async_forward_entry_setups.md Normal file
View File

@ -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).

15
docs/config_entries_index.md
View File

@ -112,23 +112,18 @@ digraph G {
During startup, Home Assistant first calls the [normal component setup](/creating_component_index.md), 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 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 ### For platforms
If a component includes platforms, it will need to forward the Config Entry to the platform. This can 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 ```python
# Use `hass.async_create_task` to avoid a circular dependency between the platform and the component await hass.config_entries.async_forward_entry_setups(config_entry, ["light", "sensor", "switch"])
hass.async_create_task(
hass.config_entries.async_forward_entry_setup(
config_entry, "light"
)
)
``` ```
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 ```python
async def async_setup_entry(hass, config_entry, async_add_entities): 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 ## 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. For each platform that you forwarded the config entry to, you will need to forward the unloading too.