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-12 11:56:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document ConfigEntry objects must not be mutated by integrations (#2076)

Browse Source 
* Document ConfigEntry objects must not be mutated by integrations

* Update config_entries_config_flow_handler.md

* Update docs/config_entries_config_flow_handler.md
This commit is contained in:
Erik Montnemery 2024-02-11 08:31:16 +01:00 committed by GitHub
parent 4603892c50
commit cdcc008469
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 6 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/config_entries_config_flow_handler.md
View File

@ -242,31 +242,9 @@ async def async_migrate_entry(hass, config_entry: ConfigEntry):
# TODO: modify Config Entry data with changes in version 1.3 # TODO: modify Config Entry data with changes in version 1.3
pass pass
config_entry.version = 1 hass.config_entries.async_update_entry(config_entry, data=new, minor_version=3, version=1)
config_entry.minor_version = 3
hass.config_entries.async_update_entry(config_entry, data=new)
_LOGGER.debug("Migration to version %s successful", config_entry.version) _LOGGER.debug("Migration to version %s.%s successful", config_entry.version, config_entry.minor_version)
return True
```
If only the config entry version is changed, but no other properties, `async_update_entry` should not be called:
```python
# Example migration function which does not modify config entry properties, e.g. data or options
async def async_migrate_entry(hass, config_entry: ConfigEntry):
"""Migrate old entry."""
_LOGGER.debug("Migrating from version %s", config_entry.version)
if config_entry.version == 1:
# TODO: Do some changes which is not stored in the config entry itself
# There's no need to call async_update_entry, the config entry will automatically be
# saved when async_migrate_entry returns True
config_entry.version = 2
_LOGGER.debug("Migration to version %s successful", config_entry.version)
return True return True
``` ```

4
docs/config_entries_index.md
View File

@ -150,3 +150,7 @@ If the config entry version is changed, `async_migrate_entry` must be implemente
async def async_migrate_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> bool: async def async_migrate_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> bool:
"""Migrate old entry.""" """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](/config_entries_config_flow_handler.md#config-entry-migration).