8.8 KiB
| title |
|---|
| Config entries |
Config Entries are configuration data that are persistently stored by Home Assistant. A config entry is created by a user via the UI. The UI flow is powered by a config flow handler as defined by the component. Config entries can also have an extra options flow handler, also defined by the component.
Lifecycle
| State | Description |
|---|---|
| not loaded | The config entry has not been loaded. This is the initial state when a config entry is created or when Home Assistant is restarted. |
| loaded | The config entry has been loaded. |
| setup error | An error occurred when trying to set up the config entry. |
| setup retry | A dependency of the config entry was not ready yet. Home Assistant will automatically retry loading this config entry in the future. Time between attempts will automatically increase. |
| migration error | The config entry had to be migrated to a newer version, but the migration failed. |
| failed unload | The config entry was attempted to be unloaded, but this was either not supported or it raised an exception. |
More information about surfacing errors and requesting a retry are in Handling Setup Failures.
Setting up an entry
During startup, Home Assistant first calls the normal component setup,
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).
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):
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):
async def async_setup_entry(hass, config_entry, async_add_entities):
"""Set up entry."""
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).
For each platform that you forwarded the config entry to, you will need to forward the unloading too.
await self.hass.config_entries.async_forward_entry_unload(self.config_entry, "light")
If you need to clean up resources used by an entity in a platform, have the entity implement the async_will_remove_from_hass method.
Removal of entries
If a component needs to clean up code when an entry is removed, it can define a removal method:
async def async_remove_entry(hass, entry) -> None:
"""Handle removal of an entry."""
Migrating config entries to a new version
If the config entry version is changed, async_migrate_entry must be implemented to support the migration of old entries. This is documented in detail in the config flow documentation
async def async_migrate_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> bool:
"""Migrate old entry."""
Modifying a config entry
A ConfigEntry object, including the data and options, must never be mutated directly by integrations, instead integrations must call async_update_entry, the use of which is illustrated in the config flow documentation.