0
# Integration Framework
1

2
System for loading, managing, and configuring integrations that connect Home Assistant to external devices, services, and platforms. Supports dynamic loading, dependency management, and platform-specific setup for over 1,300 built-in integrations.
3

4
## Capabilities
5

6
### Integration Loading
7

8
Core integration discovery, loading, and metadata management system.
9

10
```python { .api }
11
class Integration:
12
    """Integration metadata and loading information."""
13
    
14
    def __init__(self, hass: HomeAssistant, pkg_path: str, file_path: str, 
15
                 manifest: dict):
16
        """Initialize integration.
17
        
18
        Args:
19
            hass: Home Assistant instance
20
            pkg_path: Package path
21
            file_path: File path to integration
22
            manifest: Integration manifest
23
        """
24
    
25
    @property
26
    def domain(self) -> str:
27
        """Return integration domain."""
28
        
29
    @property
30
    def name(self) -> str:
31
        """Return integration name."""
32
        
33
    @property
34
    def documentation(self) -> str:
35
        """Return integration documentation URL."""
36
        
37
    @property
38
    def requirements(self) -> list[str]:
39
        """Return integration requirements."""
40
        
41
    @property
42
    def dependencies(self) -> list[str]:
43
        """Return integration dependencies."""
44
        
45
    @property
46
    def after_dependencies(self) -> list[str]:
47
        """Return integration after dependencies."""
48
        
49
    @property
50
    def version(self) -> str:
51
        """Return integration version."""
52
        
53
    @property
54
    def issue_tracker(self) -> str:
55
        """Return integration issue tracker URL."""
56
        
57
    @property
58
    def quality_scale(self) -> str:
59
        """Return integration quality scale."""
60
        
61
    @property
62
    def iot_class(self) -> str:
63
        """Return integration IoT class."""
64
        
65
    @property
66
    def config_flow(self) -> bool:
67
        """Return True if integration supports config flow."""
68
        
69
    @property
70
    def homekit(self) -> dict:
71
        """Return HomeKit configuration."""
72
        
73
    @property
74
    def ssdp(self) -> list[dict]:
75
        """Return SSDP configuration."""
76
        
77
    @property
78
    def zeroconf(self) -> list[str]:
79
        """Return Zeroconf configuration."""
80
        
81
    @property
82
    def mqtt(self) -> list[str]:
83
        """Return MQTT configuration."""
84
        
85
    @property
86
    def dhcp(self) -> list[dict]:
87
        """Return DHCP configuration."""
88
        
89
    @property
90
    def usb(self) -> list[dict]:
91
        """Return USB configuration."""
92
        
93
    @property
94
    def codeowners(self) -> list[str]:
95
        """Return integration code owners."""
96
        
97
    @property
98
    def disabled(self) -> str:
99
        """Return disabled reason if integration is disabled."""
100
        
101
    @property
102
    def loggers(self) -> list[str]:
103
        """Return integration loggers."""
104
        
105
    def get_component(self) -> ModuleType:
106
        """Get integration component module.
107
        
108
        Returns:
109
            Integration component module
110
        """
111
        
112
    def get_platform(self, platform_name: str) -> ModuleType:
113
        """Get integration platform module.
114
        
115
        Args:
116
            platform_name: Platform name
117
            
118
        Returns:
119
            Platform module
120
        """
121

122
async def async_get_integration(hass: HomeAssistant, domain: str) -> Integration:
123
    """Get integration by domain.
124
    
125
    Args:
126
        hass: Home Assistant instance
127
        domain: Integration domain
128
        
129
    Returns:
130
        Integration instance
131
        
132
    Raises:
133
        IntegrationNotFound: If integration not found
134
    """
135

136
async def async_get_custom_components(hass: HomeAssistant) -> dict[str, Integration]:
137
    """Get all custom components.
138
    
139
    Args:
140
        hass: Home Assistant instance
141
        
142
    Returns:
143
        Dictionary of domain -> Integration
144
    """
145

146
async def async_component_dependencies(hass: HomeAssistant, domain: str) -> set[str]:
147
    """Get component dependencies.
148
    
149
    Args:
150
        hass: Home Assistant instance
151
        domain: Component domain
152
        
153
    Returns:
154
        Set of dependency domains
155
    """
156

157
def async_get_loaded_integration(hass: HomeAssistant, domain: str) -> Integration:
158
    """Get loaded integration.
159
    
160
    Args:
161
        hass: Home Assistant instance
162
        domain: Integration domain
163
        
164
    Returns:
165
        Loaded integration or None
166
    """
167
```
168

169
### Component Setup
170

171
Integration setup, initialization, and lifecycle management system.
172

173
```python { .api }
174
async def async_setup_component(hass: HomeAssistant, domain: str, 
175
                               config: dict) -> bool:
176
    """Set up integration component.
177
    
178
    Args:
179
        hass: Home Assistant instance
180
        domain: Component domain
181
        config: Component configuration
182
        
183
    Returns:
184
        True if setup successful
185
    """
186

187
async def async_prepare_setup_platform(hass: HomeAssistant, config: dict,
188
                                      domain: str, platform_name: str) -> ModuleType:
189
    """Prepare platform setup.
190
    
191
    Args:
192
        hass: Home Assistant instance
193
        config: Platform configuration
194
        domain: Platform domain
195
        platform_name: Platform name
196
        
197
    Returns:
198
        Platform module
199
    """
200

201
async def async_process_deps_reqs(hass: HomeAssistant, config: dict, 
202
                                 integration: Integration) -> bool:
203
    """Process integration dependencies and requirements.
204
    
205
    Args:
206
        hass: Home Assistant instance
207
        config: Integration configuration
208
        integration: Integration instance
209
        
210
    Returns:
211
        True if processing successful
212
    """
213

214
async def async_setup_multi_components(hass: HomeAssistant, domains: set[str],
215
                                      config: dict) -> dict[str, bool]:
216
    """Set up multiple components.
217
    
218
    Args:
219
        hass: Home Assistant instance
220
        domains: Set of domains to setup
221
        config: Configuration
222
        
223
    Returns:
224
        Dictionary of domain -> setup success
225
    """
226
```
227

228
### Platform Discovery
229

230
Platform discovery and loading system for finding and initializing entity platforms.
231

232
```python { .api }
233
class EntityPlatform:
234
    """Platform for managing a group of entities."""
235
    
236
    def __init__(self, hass: HomeAssistant, logger: logging.Logger, 
237
                 domain: str, platform_name: str, platform: ModuleType,
238
                 scan_interval: timedelta, entity_namespace: str):
239
        """Initialize entity platform.
240
        
241
        Args:
242
            hass: Home Assistant instance
243
            logger: Platform logger
244
            domain: Entity domain
245
            platform_name: Platform name
246
            platform: Platform module
247
            scan_interval: Entity scan interval
248
            entity_namespace: Entity namespace
249
        """
250
    
251
    @property
252
    def domain(self) -> str:
253
        """Return platform domain."""
254
        
255
    @property
256
    def platform_name(self) -> str:
257
        """Return platform name."""
258
        
259
    @property
260
    def scan_interval(self) -> timedelta:
261
        """Return scan interval."""
262
        
263
    async def async_setup(self, platform_config: dict, 
264
                         discovery_info: dict = None) -> None:
265
        """Set up platform.
266
        
267
        Args:
268
            platform_config: Platform configuration
269
            discovery_info: Discovery information
270
        """
271
        
272
    async def async_reset(self) -> None:
273
        """Reset platform and remove all entities."""
274
        
275
    async def async_shutdown(self) -> None:
276
        """Shutdown platform."""
277
        
278
    async def async_add_entities(self, new_entities: list[Entity],
279
                               update_before_add: bool = False) -> None:
280
        """Add entities to platform.
281
        
282
        Args:
283
            new_entities: List of entities to add
284
            update_before_add: Update entities before adding
285
        """
286
        
287
    async def async_remove_entity(self, entity_id: str) -> None:
288
        """Remove entity from platform.
289
        
290
        Args:
291
            entity_id: Entity ID to remove
292
        """
293

294
async def async_setup_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> bool:
295
    """Set up integration from config entry.
296
    
297
    Args:
298
        hass: Home Assistant instance
299
        config_entry: Configuration entry
300
        
301
    Returns:
302
        True if setup successful
303
    """
304

305
async def async_unload_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> bool:
306
    """Unload integration from config entry.
307
    
308
    Args:
309
        hass: Home Assistant instance
310
        config_entry: Configuration entry
311
        
312
    Returns:
313
        True if unload successful
314
    """
315
```
316

317
### Discovery
318

319
Integration discovery mechanisms for finding devices and services on the network.
320

321
```python { .api }
322
async def async_listen_platform(hass: HomeAssistant, service: str, 
323
                               callback: Callable) -> None:
324
    """Listen for platform discoveries.
325
    
326
    Args:
327
        hass: Home Assistant instance
328
        service: Service to listen for
329
        callback: Discovery callback
330
    """
331

332
async def async_discover(hass: HomeAssistant, service: str, discovered: dict,
333
                        component: str, hass_config: dict) -> None:
334
    """Fire discovery event.
335
    
336
    Args:
337
        hass: Home Assistant instance
338
        service: Discovery service
339
        discovered: Discovery data
340
        component: Target component
341
        hass_config: Home Assistant configuration
342
    """
343

344
def discover(hass: HomeAssistant, service: str, discovered: dict,
345
            component: str, hass_config: dict) -> None:
346
    """Fire discovery event (synchronous).
347
    
348
    Args:
349
        hass: Home Assistant instance
350
        service: Discovery service
351
        discovered: Discovery data
352
        component: Target component
353
        hass_config: Home Assistant configuration
354
    """
355

356
async def async_load_platform(hass: HomeAssistant, component: str, 
357
                             platform: str, discovered: dict, 
358
                             hass_config: dict) -> None:
359
    """Load platform from discovery.
360
    
361
    Args:
362
        hass: Home Assistant instance
363
        component: Component name
364
        platform: Platform name
365
        discovered: Discovery data
366
        hass_config: Home Assistant configuration
367
    """
368
```
369

370
### Requirements Management
371

372
Python package requirement installation and management for integrations.
373

374
```python { .api }
375
async def async_process_requirements(hass: HomeAssistant, name: str, 
376
                                   requirements: list[str]) -> bool:
377
    """Process integration requirements.
378
    
379
    Args:
380
        hass: Home Assistant instance
381
        name: Integration name
382
        requirements: List of requirements
383
        
384
    Returns:
385
        True if requirements processed successfully
386
    """
387

388
def pip_kwargs(config_dir: str) -> dict:
389
    """Return pip install arguments.
390
    
391
    Args:
392
        config_dir: Configuration directory
393
        
394
    Returns:
395
        Pip kwargs dictionary
396
    """
397

398
async def async_get_integration_with_requirements(hass: HomeAssistant, 
399
                                                domain: str) -> Integration:
400
    """Get integration and install requirements.
401
    
402
    Args:
403
        hass: Home Assistant instance
404
        domain: Integration domain
405
        
406
    Returns:
407
        Integration with requirements installed
408
    """
409
```
410

411
### Manifest Validation
412

413
Integration manifest file validation and parsing.
414

415
```python { .api }
416
def validate_manifest(manifest: dict) -> dict:
417
    """Validate integration manifest.
418
    
419
    Args:
420
        manifest: Manifest dictionary
421
        
422
    Returns:
423
        Validated manifest
424
        
425
    Raises:
426
        vol.Invalid: If manifest is invalid
427
    """
428

429
MANIFEST_SCHEMA = vol.Schema({
430
    vol.Required("domain"): str,
431
    vol.Required("name"): str,
432
    vol.Optional("config_flow"): bool,
433
    vol.Optional("documentation"): str,
434
    vol.Optional("requirements"): [str],
435
    vol.Optional("dependencies"): [str],
436
    vol.Optional("after_dependencies"): [str],
437
    vol.Optional("codeowners"): [str],
438
    vol.Optional("quality_scale"): vol.In(["gold", "silver", "bronze", "internal"]),
439
    vol.Optional("iot_class"): str,
440
    vol.Optional("homekit"): dict,
441
    vol.Optional("ssdp"): [dict],
442
    vol.Optional("zeroconf"): [str],
443
    vol.Optional("mqtt"): [str],
444
    vol.Optional("dhcp"): [dict],
445
    vol.Optional("usb"): [dict],
446
    vol.Optional("version"): str,
447
    vol.Optional("loggers"): [str],
448
    vol.Optional("issue_tracker"): str,
449
    vol.Optional("disabled"): str,
450
})
451
```
452

453
## Integration Constants
454

455
```python { .api }
456
# Integration quality scales
457
GOLD_SCALE = "gold"
458
SILVER_SCALE = "silver" 
459
BRONZE_SCALE = "bronze"
460
INTERNAL_SCALE = "internal"
461

462
# IoT classes
463
CLOUD_POLLING = "cloud_polling"
464
CLOUD_PUSH = "cloud_push" 
465
LOCAL_POLLING = "local_polling"
466
LOCAL_PUSH = "local_push"
467
ASSUMED = "assumed"
468

469
# Platform types (subset of available platforms)
470
ALARM_CONTROL_PANEL = "alarm_control_panel"
471
BINARY_SENSOR = "binary_sensor"
472
BUTTON = "button"
473
CAMERA = "camera"
474
CLIMATE = "climate"
475
COVER = "cover"
476
DEVICE_TRACKER = "device_tracker"
477
FAN = "fan"
478
LIGHT = "light"
479
LOCK = "lock"
480
MEDIA_PLAYER = "media_player"
481
NOTIFY = "notify"
482
SCENE = "scene"
483
SCRIPT = "script"
484
SENSOR = "sensor"
485
SWITCH = "switch"
486
TTS = "tts"
487
VACUUM = "vacuum"
488
WATER_HEATER = "water_heater"
489

490
# Discovery services
491
SERVICE_HOMEKIT = "homekit"
492
SERVICE_ZEROCONF = "zeroconf"
493
SERVICE_SSDP = "ssdp"
494
SERVICE_MQTT = "mqtt"
495
SERVICE_DHCP = "dhcp"
496
SERVICE_USB = "usb"
497

498
# Setup states
499
SETUP_SUCCESS = True
500
SETUP_FAILED = False
501
SETUP_RETRY = "retry"
502
```
503

504
## Types
505

506
```python { .api }
507
from typing import Any, Callable, Dict, List, Optional, Union, ModuleType
508
from datetime import timedelta
509
import logging
510

511
# Integration types
512
IntegrationType = Dict[str, Any]
513
ManifestType = Dict[str, Any]
514
PlatformType = ModuleType
515
ComponentType = ModuleType
516

517
# Setup types
518
SetupCallbackType = Callable[[HomeAssistant, Dict[str, Any]], bool]
519
AsyncSetupCallbackType = Callable[[HomeAssistant, Dict[str, Any]], Coroutine[Any, Any, bool]]
520
PlatformSetupType = Callable[[HomeAssistant, Dict[str, Any], Callable], None]
521

522
# Discovery types
523
DiscoveryInfoType = Dict[str, Any]
524
DiscoveryCallbackType = Callable[[str, Dict[str, Any]], None]
525

526
# Platform entity setup
527
AddEntitiesCallbackType = Callable[[List[Entity], bool], None]
528
```