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-09 18:36:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

suggestions for config entries (#2)

Browse Source 
* [WIP] suggestions for config entries

* add working links
This commit is contained in:
Marc Khouri 2018-04-30 11:47:41 -04:00 committed by Paulus Schoutsen
parent b60fc2b8cc
commit 135684a91e
1 changed files with 15 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/config_entries_index.md
View File

@ -3,24 +3,25 @@ title: Config Entries
sidebar_label: Introduction sidebar_label: Introduction
--- ---
Config entries are pieces of configuration that can be consumed by components. Each configuration entry is created via a Config Flow Handler, as defined by each component. Config Entries are configuration data that are persistently stored by Home Assistant.
## Setting up an entry ## Setting up an entry
During startup, Home Assistant will setup the entries during the normal setup During startup, Home Assistant first call the [normal component setup](https://developers.home-assistant.io/docs/en/creating_component_index.html),
of a component. It will first call the normal component setup and then call the method and then call the method `async_setup_entry(hass, entry)` for each entry. If a new Config Entry is
`async_setup_entry(hass, entry)` for each entry. The same method is called when created at runtime, Home Assistant will also call `async_setup_entry(hass, entry)` ([example](https://github.com/home-assistant/home-assistant/blob/0.68.0/homeassistant/components/hue/__init__.py#L119)).
Home Assistant is running while a config entry is created.
If a component includes platforms, it will need to forward the entry to the component. This can be done by calling the forward function on the config entry manager: #### 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/home-assistant/blob/0.68.0/homeassistant/components/hue/bridge.py#L81)):
```python ```python
# Use `hass.async_add_job` to avoid a circular dependency between the platform and the component
hass.async_add_job(hass.config_entries.async_forward_entry_setup(config_entry, 'light')) hass.async_add_job(hass.config_entries.async_forward_entry_setup(config_entry, 'light'))
``` ```
Make sure you use `hass.async_add_job` to avoid a circular dependency between the platform and the component. For a platform to support config entries, it will need to add a setup entry method ([example](https://github.com/home-assistant/home-assistant/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:
```python ```python
async def async_setup_entry(hass, config_entry, async_add_devices): async def async_setup_entry(hass, config_entry, async_add_devices):
@ -28,6 +29,9 @@ async def async_setup_entry(hass, config_entry, async_add_devices):
## Unloading entries ## Unloading entries
Components can support unloading a config entry. This is optional. When unloading an entry, it 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. 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/home-assistant/blob/0.68.0/homeassistant/components/hue/__init__.py#L136)).
Platforms will not need to add any logic for unloading a config entry. The entity component will take care of this. If you need to clean up resources used for an entity, implement the `async_will_remove_from_hass` method on the Entity. Platforms will not need to add any logic for unloading a config entry. The entity component will take care of this.
If you need to clean up resources used for an entity, implement the `async_will_remove_from_hass` method on the Entity ([example](https://github.com/home-assistant/home-assistant/blob/0.68.0/homeassistant/components/media_player/cast.py#L313)).