remove docs from config entries file [skip ci] (#24488)
This commit is contained in:
Paulus Schoutsen
GitHub
parent
06ca04c1c8
commit
24e1a568a2
1 changed files with 1 additions and 121 deletions
|
|
@ -1,124 +1,4 @@
|
|||
"""The Config Manager is responsible for managing configuration for components.
|
||||
|
||||
The Config Manager allows for creating config entries to be consumed by
|
||||
components. Each entry is created via a Config Flow Handler, as defined by each
|
||||
component.
|
||||
|
||||
During startup, Home Assistant will setup the entries during the normal setup
|
||||
of a component. It will first call the normal setup and then call the method
|
||||
`async_setup_entry(hass, entry)` for each entry. The same method is called when
|
||||
Home Assistant is running while a config entry is created. If the version of
|
||||
the config entry does not match that of the flow handler, setup will
|
||||
call the method `async_migrate_entry(hass, entry)` with the expectation that
|
||||
the entry be brought to the current version. Return `True` to indicate
|
||||
migration was successful, otherwise `False`.
|
||||
|
||||
## Config Flows
|
||||
|
||||
A component needs to define a Config Handler to allow the user to create config
|
||||
entries for that component. A config flow will manage the creation of entries
|
||||
from user input, discovery or other sources (like hassio).
|
||||
|
||||
When a config flow is started for a domain, the handler will be instantiated
|
||||
and receives a unique id. The instance of this handler will be reused for every
|
||||
interaction of the user with this flow. This makes it possible to store
|
||||
instance variables on the handler.
|
||||
|
||||
Before instantiating the handler, Home Assistant will make sure to load all
|
||||
dependencies and install the requirements of the component.
|
||||
|
||||
At a minimum, each config flow will have to define a version number and the
|
||||
'user' step.
|
||||
|
||||
@config_entries.HANDLERS.register(DOMAIN)
|
||||
class ExampleConfigFlow(config_entries.ConfigFlow):
|
||||
|
||||
VERSION = 1
|
||||
CONNECTION_CLASS = config_entries.CONN_CLASS_LOCAL_PUSH
|
||||
|
||||
async def async_step_user(self, user_input=None):
|
||||
…
|
||||
|
||||
The 'user' step is the first step of a flow and is called when a user
|
||||
starts a new flow. Each step has three different possible results: "Show Form",
|
||||
"Abort" and "Create Entry".
|
||||
|
||||
> Note: prior 0.76, the default step is 'init' step, some config flows still
|
||||
keep 'init' step to avoid break localization. All new config flow should use
|
||||
'user' step.
|
||||
|
||||
### Show Form
|
||||
|
||||
This will show a form to the user to fill in. You define the current step,
|
||||
a title, a description and the schema of the data that needs to be returned.
|
||||
|
||||
async def async_step_init(self, user_input=None):
|
||||
# Use OrderedDict to guarantee order of the form shown to the user
|
||||
data_schema = OrderedDict()
|
||||
data_schema[vol.Required('username')] = str
|
||||
data_schema[vol.Required('password')] = str
|
||||
|
||||
return self.async_show_form(
|
||||
step_id='user',
|
||||
title='Account Info',
|
||||
data_schema=vol.Schema(data_schema)
|
||||
)
|
||||
|
||||
After the user has filled in the form, the step method will be called again and
|
||||
the user input is passed in. If the validation of the user input fails , you
|
||||
can return a dictionary with errors. Each key in the dictionary refers to a
|
||||
field name that contains the error. Use the key 'base' if you want to show a
|
||||
generic error.
|
||||
|
||||
async def async_step_init(self, user_input=None):
|
||||
errors = None
|
||||
if user_input is not None:
|
||||
# Validate user input
|
||||
if valid:
|
||||
return self.create_entry(…)
|
||||
|
||||
errors['base'] = 'Unable to reach authentication server.'
|
||||
|
||||
return self.async_show_form(…)
|
||||
|
||||
If the user input passes validation, you can again return one of the three
|
||||
return values. If you want to navigate the user to the next step, return the
|
||||
return value of that step:
|
||||
|
||||
return await self.async_step_account()
|
||||
|
||||
### Abort
|
||||
|
||||
When the result is "Abort", a message will be shown to the user and the
|
||||
configuration flow is finished.
|
||||
|
||||
return self.async_abort(
|
||||
reason='This device is not supported by Home Assistant.'
|
||||
)
|
||||
|
||||
### Create Entry
|
||||
|
||||
When the result is "Create Entry", an entry will be created and stored in Home
|
||||
Assistant, a success message is shown to the user and the flow is finished.
|
||||
|
||||
## Initializing a config flow from an external source
|
||||
|
||||
You might want to initialize a config flow programmatically. For example, if
|
||||
we discover a device on the network that requires user interaction to finish
|
||||
setup. To do so, pass a source parameter and optional user input to the init
|
||||
method:
|
||||
|
||||
await hass.config_entries.flow.async_init(
|
||||
'hue', context={'source': 'discovery'}, data=discovery_info)
|
||||
|
||||
The config flow handler will need to add a step to support the source. The step
|
||||
should follow the same return values as a normal step.
|
||||
|
||||
async def async_step_discovery(info):
|
||||
|
||||
If the result of the step is to show a form, the user will be able to continue
|
||||
the flow from the config panel.
|
||||
"""
|
||||
"""Manage config entries in Home Assistant."""
|
||||
import asyncio
|
||||
import logging
|
||||
import functools
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue