From e1b99a12d7603b38d1f8c1d9197b23315e4c5c74 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Sun, 16 Feb 2025 17:53:14 +0100 Subject: [PATCH] Clarify config entry unload quality scale rule (#2566) * Clarify config entry unload quality scale rule * Apply suggestions from code review --------- Co-authored-by: Franck Nijhof --- .../rules/config-entry-unloading.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/core/integration-quality-scale/rules/config-entry-unloading.md b/docs/core/integration-quality-scale/rules/config-entry-unloading.md index 6ddb4c8e..28e53f72 100644 --- a/docs/core/integration-quality-scale/rules/config-entry-unloading.md +++ b/docs/core/integration-quality-scale/rules/config-entry-unloading.md @@ -16,7 +16,6 @@ This improves the user experience, since the user can do more actions without ha In the `async_unload_entry` interface function, the integration should clean up any subscriptions and close any connections opened during the setup of the integration. -The method that has to be added to `__init__.py` looks very similar to the `async_setup_entry` method. In this example we have a listener, stored in the `runtime_data` of the config entry, which we want to clean up to avoid memory leaks. `__init__.py`: @@ -29,8 +28,13 @@ async def async_unload_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool: ``` :::info -You can also use `entry.async_on_unload` to register a callback that will be called when the config entry is unloaded. +Integrations can use `entry.async_on_unload` to register callbacks which will be called when the config entry is unloaded or if it fails to set up. This can be useful to clean up resources without having to keep track of the removal methods yourself. +The registered callbacks will be called if : + - `async_setup_entry` raises either `ConfigEntryError`, `ConfigEntryAuthFailed`, or `ConfigEntryNotReady` + - `async_unload_entry` succeeds, i.e., it returns True and does not raise. + +Note that integrations always need to implement `async_unload_entry` to support config entry unloading, just calling `entry.async_on_unload` is not enough. ::: ## Additional resources