2.2 KiB
title, related_rules
| title | related_rules | |
|---|---|---|
| Check during integration initialization if we are able to set it up correctly |
|
import RelatedRules from './_includes/related_rules.jsx'
Reasoning
When we initialize an integration, we should check if we are able to set it up correctly. This way we can immediately let the user know that it doesn't work.
Implementing these checks increases the confidence that the integration will work correctly and provides a user-friendly way to show errors. This will improve the user experience.
Example implementation
When the reason for the failure is temporary (like a temporary offline device), we should raise ConfigEntryNotReady and Home Assistant will retry the setup later.
If the reason for the failure is that the password is incorrect or the api key is invalid, we should raise ConfigEntryAuthFailed and Home Assistant will ask the user to reauthenticate (if the reauthentication flow is implemented).
If we don't expect the integration to work in the foreseeable future, we should raise ConfigEntryError.
__init__.py:
async def async_setup_entry(hass: HomeAssistant, entry: MyIntegrationConfigEntry) -> bool:
"""Set up my integration from a config entry."""
client = MyClient(entry.data[CONF_HOST])
try:
await client.async_setup()
except OfflineException as ex:
raise ConfigEntryNotReady("Device is offline") from ex
except InvalidAuthException as ex:
raise ConfigEntryAuthFailed("Invalid authentication") from ex
except AccountClosedException as ex:
raise ConfigEntryError("Account closed") from ex
entry.runtime_data = client
await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
return True
:::info
Please note that this may also be implemented implicitly when using a data update coordinator via await coordinator.async_config_entry_first_refresh().
:::
Additional resources
More information about config entries and their lifecycle can be found in the config entry documentation.
Exceptions
There are no exceptions to this rule.