0
# Configuration Management
1

2
Configuration loading, validation, and management system supporting both YAML files and UI-driven configuration flows. Handles integration discovery, dependency resolution, and configuration entry lifecycle management.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Core configuration file loading and processing functionality for YAML-based Home Assistant configuration.
9

10
```python { .api }
11
def load_yaml_config_file(config_path: str) -> dict:
12
    """Load YAML configuration file.
13
    
14
    Args:
15
        config_path: Path to YAML configuration file
16
        
17
    Returns:
18
        Configuration dictionary
19
        
20
    Raises:
21
        HomeAssistantError: If configuration cannot be loaded
22
    """
23

24
async def async_process_ha_config_upgrade(hass: HomeAssistant) -> None:
25
    """Process Home Assistant configuration upgrade.
26
    
27
    Args:
28
        hass: Home Assistant instance
29
    """
30

31
async def async_check_ha_config_file(hass: HomeAssistant) -> str:
32
    """Check Home Assistant configuration file for errors.
33
    
34
    Args:
35
        hass: Home Assistant instance
36
        
37
    Returns:
38
        Configuration check result
39
    """
40

41
def find_config_file(config_dir: str) -> str:
42
    """Find configuration file in config directory.
43
    
44
    Args:
45
        config_dir: Configuration directory path
46
        
47
    Returns:
48
        Path to configuration file
49
        
50
    Raises:
51
        HomeAssistantError: If configuration file not found
52
    """
53

54
async def async_from_config_dict(config: dict, hass: HomeAssistant, 
55
                                config_dir: str = None, enable_log: bool = True,
56
                                verbose: bool = False, skip_pip: bool = False,
57
                                log_rotate_days: int = None) -> HomeAssistant:
58
    """Create Home Assistant instance from configuration dictionary.
59
    
60
    Args:
61
        config: Configuration dictionary
62
        hass: Home Assistant instance
63
        config_dir: Configuration directory
64
        enable_log: Enable logging
65
        verbose: Verbose logging
66
        skip_pip: Skip pip installs
67
        log_rotate_days: Log rotation days
68
        
69
    Returns:
70
        Configured Home Assistant instance
71
    """
72
```
73

74
### Config Entries
75

76
UI-driven configuration system that allows integrations to be configured through the web interface with setup flows.
77

78
```python { .api }
79
class ConfigEntry:
80
    """Configuration entry for an integration."""
81
    
82
    def __init__(self, version: int, domain: str, title: str, data: dict,
83
                 options: dict = None, source: str = None, 
84
                 connection_class: str = None, unique_id: str = None,
85
                 entry_id: str = None, state: str = None):
86
        """Initialize config entry.
87
        
88
        Args:
89
            version: Entry version
90
            domain: Integration domain
91
            title: Entry title
92
            data: Entry data
93
            options: Entry options
94
            source: Entry source
95
            connection_class: Connection class
96
            unique_id: Unique ID
97
            entry_id: Entry ID
98
            state: Entry state
99
        """
100
    
101
    @property
102
    def entry_id(self) -> str:
103
        """Return entry ID."""
104
        
105
    @property
106
    def version(self) -> int:
107
        """Return entry version."""
108
        
109
    @property
110
    def domain(self) -> str:
111
        """Return integration domain."""
112
        
113
    @property
114
    def title(self) -> str:
115
        """Return entry title."""
116
        
117
    @property
118
    def data(self) -> dict:
119
        """Return entry data."""
120
        
121
    @property
122
    def options(self) -> dict:
123
        """Return entry options."""
124
        
125
    @property
126
    def source(self) -> str:
127
        """Return entry source."""
128
        
129
    @property
130
    def connection_class(self) -> str:
131
        """Return connection class."""
132
        
133
    @property
134
    def unique_id(self) -> str:
135
        """Return unique ID."""
136
        
137
    @property
138
    def state(self) -> str:
139
        """Return entry state."""
140
        
141
    @property
142
    def supports_options(self) -> bool:
143
        """Return True if entry supports options."""
144
        
145
    @property
146
    def supports_unload(self) -> bool:
147
        """Return True if entry supports unloading."""
148
        
149
    @property
150
    def supports_remove_device(self) -> bool:
151
        """Return True if entry supports device removal."""
152
        
153
    async def async_setup(self, hass: HomeAssistant, *, integration: Integration = None) -> bool:
154
        """Set up config entry.
155
        
156
        Args:
157
            hass: Home Assistant instance
158
            integration: Integration instance
159
            
160
        Returns:
161
            True if setup successful
162
        """
163
        
164
    async def async_unload(self, hass: HomeAssistant) -> bool:
165
        """Unload config entry.
166
        
167
        Args:
168
            hass: Home Assistant instance
169
            
170
        Returns:
171
            True if unload successful
172
        """
173
        
174
    def add_update_listener(self, listener: Callable) -> Callable:
175
        """Add update listener.
176
        
177
        Args:
178
            listener: Update listener function
179
            
180
        Returns:
181
            Function to remove listener
182
        """
183
```
184

185
### Config Flow
186

187
Base class for configuration flows that guide users through integration setup via the web interface.
188

189
```python { .api }
190
class ConfigFlow:
191
    """Base class for config flows."""
192
    
193
    VERSION = 1
194
    CONNECTION_CLASS = None
195
    
196
    def __init__(self):
197
        """Initialize config flow."""
198
    
199
    @property
200
    def source(self) -> str:
201
        """Return flow source."""
202
        
203
    @property
204
    def unique_id(self) -> str:
205
        """Return unique ID."""
206
        
207
    async def async_step_user(self, user_input: dict = None) -> dict:
208
        """Handle user step.
209
        
210
        Args:
211
            user_input: User input data
212
            
213
        Returns:
214
            Flow result
215
        """
216
        
217
    async def async_step_discovery(self, discovery_info: dict) -> dict:
218
        """Handle discovery step.
219
        
220
        Args:
221
            discovery_info: Discovery information
222
            
223
        Returns:
224
            Flow result
225
        """
226
        
227
    async def async_step_import(self, import_config: dict) -> dict:
228
        """Handle import step.
229
        
230
        Args:
231
            import_config: Import configuration
232
            
233
        Returns:
234
            Flow result
235
        """
236
        
237
    async def async_show_form(self, *, step_id: str, data_schema: dict = None,
238
                             errors: dict = None, description_placeholders: dict = None,
239
                             last_step: bool = None) -> dict:
240
        """Show configuration form.
241
        
242
        Args:
243
            step_id: Step ID
244
            data_schema: Voluptuous schema for form
245
            errors: Form validation errors
246
            description_placeholders: Description placeholders
247
            last_step: Whether this is the last step
248
            
249
        Returns:
250
            Flow result
251
        """
252
        
253
    async def async_create_entry(self, *, title: str, data: dict,
254
                                description: str = None, 
255
                                description_placeholders: dict = None) -> dict:
256
        """Create config entry.
257
        
258
        Args:
259
            title: Entry title
260
            data: Entry data
261
            description: Entry description
262
            description_placeholders: Description placeholders
263
            
264
        Returns:
265
            Flow result
266
        """
267
        
268
    async def async_abort(self, *, reason: str, 
269
                         description_placeholders: dict = None) -> dict:
270
        """Abort config flow.
271
        
272
        Args:
273
            reason: Abort reason
274
            description_placeholders: Description placeholders
275
            
276
        Returns:
277
            Flow result
278
        """
279
        
280
    def async_set_unique_id(self, unique_id: str) -> None:
281
        """Set unique ID for flow.
282
        
283
        Args:
284
            unique_id: Unique ID
285
        """
286
        
287
    async def async_set_unique_id_and_abort_if_exists(self, unique_id: str) -> None:
288
        """Set unique ID and abort if already exists.
289
        
290
        Args:
291
            unique_id: Unique ID
292
        """
293
```
294

295
### Config Entry Manager
296

297
Central manager for configuration entries that handles registration, loading, and lifecycle management.
298

299
```python { .api }
300
class ConfigEntries:
301
    """Configuration entries manager."""
302
    
303
    def __init__(self, hass: HomeAssistant, store: Store):
304
        """Initialize config entries manager.
305
        
306
        Args:
307
            hass: Home Assistant instance
308
            store: Storage for config entries
309
        """
310
    
311
    async def async_add(self, entry: ConfigEntry) -> ConfigEntry:
312
        """Add config entry.
313
        
314
        Args:
315
            entry: Config entry to add
316
            
317
        Returns:
318
            Added config entry
319
        """
320
        
321
    async def async_remove(self, entry_id: str) -> dict:
322
        """Remove config entry.
323
        
324
        Args:
325
            entry_id: Entry ID to remove
326
            
327
        Returns:
328
            Removal result
329
        """
330
        
331
    async def async_update_entry(self, entry: ConfigEntry, *, title: str = None,
332
                               data: dict = None, options: dict = None) -> ConfigEntry:
333
        """Update config entry.
334
        
335
        Args:
336
            entry: Config entry to update
337
            title: New title
338
            data: New data
339
            options: New options
340
            
341
        Returns:
342
            Updated config entry
343
        """
344
        
345
    async def async_reload(self, entry_id: str) -> bool:
346
        """Reload config entry.
347
        
348
        Args:
349
            entry_id: Entry ID to reload
350
            
351
        Returns:
352
            True if reload successful
353
        """
354
        
355
    async def async_setup(self, entry_id: str) -> bool:
356
        """Set up config entry.
357
        
358
        Args:
359
            entry_id: Entry ID to set up
360
            
361
        Returns:
362
            True if setup successful
363
        """
364
        
365
    async def async_unload(self, entry_id: str) -> bool:
366
        """Unload config entry.
367
        
368
        Args:
369
            entry_id: Entry ID to unload
370
            
371
        Returns:
372
            True if unload successful
373
        """
374
        
375
    async def async_forward_entry_setup(self, entry: ConfigEntry, domain: str) -> bool:
376
        """Forward config entry setup to domain.
377
        
378
        Args:
379
            entry: Config entry
380
            domain: Target domain
381
            
382
        Returns:
383
            True if setup successful
384
        """
385
        
386
    async def async_forward_entry_unload(self, entry: ConfigEntry, domain: str) -> bool:
387
        """Forward config entry unload to domain.
388
        
389
        Args:
390
            entry: Config entry
391
            domain: Target domain
392
            
393
        Returns:
394
            True if unload successful
395
        """
396
        
397
    def get_entry(self, entry_id: str) -> ConfigEntry:
398
        """Get config entry by ID.
399
        
400
        Args:
401
            entry_id: Entry ID
402
            
403
        Returns:
404
            Config entry or None
405
        """
406
        
407
    @property
408
    def async_entries(self) -> list[ConfigEntry]:
409
        """Return all config entries."""
410
```
411

412
### Options Flow
413

414
Base class for options flows that allow users to modify integration configuration after initial setup.
415

416
```python { .api }
417
class OptionsFlow:
418
    """Base class for options flows."""
419
    
420
    def __init__(self, config_entry: ConfigEntry):
421
        """Initialize options flow.
422
        
423
        Args:
424
            config_entry: Config entry for options
425
        """
426
    
427
    async def async_step_init(self, user_input: dict = None) -> dict:
428
        """Handle options flow initialization.
429
        
430
        Args:
431
            user_input: User input data
432
            
433
        Returns:
434
            Flow result
435
        """
436
        
437
    async def async_create_entry(self, *, title: str = None, data: dict) -> dict:
438
        """Create options entry.
439
        
440
        Args:
441
            title: Entry title
442
            data: Options data
443
            
444
        Returns:
445
            Flow result
446
        """
447
```
448

449
## Configuration Constants
450

451
```python { .api }
452
# Config entry states
453
ENTRY_STATE_LOADED = "loaded"
454
ENTRY_STATE_SETUP_ERROR = "setup_error"
455
ENTRY_STATE_SETUP_RETRY = "setup_retry"
456
ENTRY_STATE_SETUP_IN_PROGRESS = "setup_in_progress"
457
ENTRY_STATE_NOT_LOADED = "not_loaded"
458
ENTRY_STATE_FAILED_UNLOAD = "failed_unload"
459

460
# Config sources
461
SOURCE_USER = "user"
462
SOURCE_DISCOVERY = "discovery"
463
SOURCE_IMPORT = "import"
464
SOURCE_SYSTEM = "system"
465
SOURCE_ZEROCONF = "zeroconf"
466
SOURCE_SSDP = "ssdp"
467
SOURCE_HOMEKIT = "homekit"
468

469
# Connection classes
470
CONN_CLASS_CLOUD_POLLING = "cloud_polling"
471
CONN_CLASS_CLOUD_PUSH = "cloud_push"
472
CONN_CLASS_LOCAL_POLLING = "local_polling"
473
CONN_CLASS_LOCAL_PUSH = "local_push"
474
CONN_CLASS_ASSUMED = "assumed"
475

476
# Flow result types
477
RESULT_TYPE_FORM = "form"
478
RESULT_TYPE_CREATE_ENTRY = "create_entry"
479
RESULT_TYPE_ABORT = "abort"
480
RESULT_TYPE_EXTERNAL_STEP = "external"
481
RESULT_TYPE_EXTERNAL_STEP_DONE = "external_done"
482
RESULT_TYPE_SHOW_PROGRESS = "progress"
483
RESULT_TYPE_SHOW_PROGRESS_DONE = "progress_done"
484
RESULT_TYPE_MENU = "menu"
485
```
486

487
## Types
488

489
```python { .api }
490
from typing import Any, Callable, Dict, List, Optional, Union
491
from enum import Enum
492

493
# Config entry types
494
ConfigType = Dict[str, Any]
495
ConfigEntryDataType = Dict[str, Any]
496
ConfigEntryOptionsType = Dict[str, Any]
497

498
# Flow types
499
FlowResultType = Dict[str, Any]
500
FlowHandlerType = Callable[..., FlowResultType]
501
UserInputType = Dict[str, Any]
502

503
# Schema types
504
import voluptuous as vol
505
SchemaType = vol.Schema
506
ValidatorType = Callable[[Any], Any]
507
```