Home Assistant Documentation Release 2021.10.0.Dev0

Home Assistant Documentation Release 2021.10.0.dev0

Home Assistant Team

Sep 29, 2021

CONTENTS

1 homeassistant.auth 3 1.1 homeassistant.auth.auth_store...... 5 1.2 homeassistant.auth.const...... 6 1.3 homeassistant.auth.models...... 7

2 homeassistant.bootstrap 9

3 homeassistant.components 11 3.1 air_quality...... 11 3.2 alarm_control_panel...... 12 3.3 binary_sensor...... 15 3.4 camera...... 17 3.5 calendar...... 22 3.6 climate...... 23 3.7 conversation...... 27 3.8 cover...... 28 3.9 device_tracker...... 30 3.10 fan...... 30 3.11 light...... 34 3.12 lock...... 37 3.13 media_player...... 38 3.14 notify...... 45 3.15 remote...... 46 3.16 switch...... 47 3.17 sensor...... 49 3.18 vacuum...... 50 3.19 water_heater...... 53 3.20 weather...... 56 3.21 webhook...... 58

4 homeassistant.config_entries 61

5 homeassistant.core 67

6 homeassistant.data_entry_flow 75

7 homeassistant.exceptions 77

8 homeassistant.helpers 79 8.1 homeassistant.helpers.aiohttp_client...... 79 8.2 homeassistant.helpers.area_registry...... 80

i 8.3 homeassistant.helpers.check_config...... 82 8.4 homeassistant.helpers.collection...... 82 8.5 homeassistant.helpers.condition...... 85 8.6 homeassistant.helpers.config_entry_flow...... 89 8.7 homeassistant.helpers.config_entry_oauth2_flow...... 91 8.8 homeassistant.helpers.config_validation...... 95 8.9 homeassistant.helpers.data_entry_flow...... 99 8.10 homeassistant.helpers.debounce...... 99 8.11 homeassistant.helpers.deprecation...... 100 8.12 homeassistant.helpers.device_registry...... 100 8.13 homeassistant.helpers.discovery...... 104 8.14 homeassistant.helpers.dispatcher...... 105 8.15 homeassistant.helpers.entity...... 106 8.16 homeassistant.helpers.entity_component...... 111 8.17 homeassistant.helpers.entity_platform...... 112 8.18 homeassistant.helpers.entity_registry...... 114 8.19 homeassistant.helpers.entity_values...... 117 8.20 homeassistant.helpers.entityfilter...... 118 8.21 homeassistant.helpers.event...... 118 8.22 homeassistant.helpers.icon...... 125 8.23 homeassistant.helpers.integration_platform...... 125 8.24 homeassistant.helpers.intent...... 126 8.25 homeassistant.helpers.json...... 128 8.26 homeassistant.helpers.location...... 128 8.27 homeassistant.helpers.logging...... 129 8.28 homeassistant.helpers.network...... 129 8.29 homeassistant.helpers.restore_state...... 130 8.30 homeassistant.helpers.script...... 131 8.31 homeassistant.helpers.service...... 132 8.32 homeassistant.helpers.signal...... 136 8.33 homeassistant.helpers.state...... 137 8.34 homeassistant.helpers.storage...... 137 8.35 homeassistant.helpers.sun...... 138 8.36 homeassistant.helpers.system_info...... 139 8.37 homeassistant.helpers.temperature...... 139 8.38 homeassistant.helpers.template...... 139 8.39 homeassistant.helpers.translation...... 145 8.40 homeassistant.helpers.typing...... 146 8.41 homeassistant.helpers.update_coordinator...... 146

9 homeassistant.loader 149

10 homeassistant.util 153 10.1 homeassistant.util.yaml...... 154 10.2 homeassistant.util.aiohttp...... 155 10.3 homeassistant.util.async_...... 155 10.4 homeassistant.util.color...... 156 10.5 homeassistant.util.decorator...... 159 10.6 homeassistant.util.distance...... 159 10.7 homeassistant.util.dt...... 159 10.8 homeassistant.util.json...... 160 10.9 homeassistant.util.location...... 161 10.10 homeassistant.util.logging...... 162 10.11 homeassistant.util.network...... 163 ii 10.12 homeassistant.util.package...... 164 10.13 homeassistant.util.pil...... 164 10.14 homeassistant.util.pressure...... 164 10.15 homeassistant.util.ssl...... 165 10.16 homeassistant.util.temperature...... 165 10.17 homeassistant.util.unit_system...... 165 10.18 homeassistant.util.volume...... 166

11 Indices and tables 167

Python Module Index 169

Index 171

iii iv Home Assistant Documentation, Release 2021.10.0.dev0

Public API documentation for Home Assistant developers. Contents:

CONTENTS 1 Home Assistant Documentation, Release 2021.10.0.dev0

2 CONTENTS CHAPTER ONE

HOMEASSISTANT.AUTH

Provide an authentication layer for Home Assistant. class homeassistant.auth.AuthManager(hass: homeassistant.core.HomeAssistant, store: homeassistant.auth.auth_store.AuthStore, providers: Dict[Tuple[str, Optional[str]], homeassistant.auth.providers.AuthProvider], mfa_modules: Dict[str, homeassistant.auth.mfa_modules.MultiFactorAuthModule]) Manage the authentication for Home Assistant. async async_activate_user(user: homeassistant.auth.models.User) → None Activate a user. async_create_access_token(refresh_token: models.RefreshToken, remote_ip: str | None = None) → str Create a new access token. async async_create_refresh_token(user: models.User, client_id: str | None = None, client_name: str | None = None, client_icon: str | None = None, token_type: str | None = None, access_token_expiration: timedelta = datetime.timedelta(seconds=1800), credential: models.Credentials | None = None) → models.RefreshToken Create a new refresh token for a user. async async_create_system_user(name: str, group_ids: list[str] | None = None) → models.User Create a system user. async async_create_user(name: str, group_ids: list[str] | None = None) → models.User Create a user. async async_deactivate_user(user: homeassistant.auth.models.User) → None Deactivate a user. async async_disable_user_mfa(user: homeassistant.auth.models.User, mfa_module_id: str) → None Disable a multi-factor auth module for user. async async_enable_user_mfa(user: homeassistant.auth.models.User, mfa_module_id: str, data: Any) → None Enable a multi-factor auth module for user. async async_get_enabled_mfa(user: models.User) → dict[str, str] List enabled mfa modules for user.

3 Home Assistant Documentation, Release 2021.10.0.dev0

async async_get_group(group_id: str) → models.Group | None Retrieve all groups. async async_get_or_create_user(credentials: homeassistant.auth.models.Credentials) → homeassistant.auth.models.User Get or create a user. async async_get_owner() → models.User | None Retrieve the owner. async async_get_refresh_token(token_id: str) → models.RefreshToken | None Get refresh token by id. async async_get_refresh_token_by_token(token: str) → models.RefreshToken | None Get refresh token by token. async async_get_user(user_id: str) → models.User | None Retrieve a user. async async_get_user_by_credentials(credentials: models.Credentials) → models.User | None Get a user by credential, return None if not found. async async_get_users() → list[models.User] Retrieve all users. async async_link_user(user: homeassistant.auth.models.User, credentials: homeassistant.auth.models.Credentials) → None Link credentials to an existing user. async async_remove_credentials(credentials: homeassistant.auth.models.Credentials) → None Remove credentials. async async_remove_refresh_token(refresh_token: homeassistant.auth.models.RefreshToken) → None Delete a refresh token. async async_remove_user(user: homeassistant.auth.models.User) → None Remove a user. async async_update_user(user: models.User, name: str | None = None, is_active: bool | None = None, group_ids: list[str] | None = None) → None Update a user. async async_validate_access_token(token: str) → models.RefreshToken | None Return refresh token if an access token is valid. async_validate_refresh_token(refresh_token: models.RefreshToken, remote_ip: str | None = None) → None Validate that a refresh token is usable. Will raise InvalidAuthError on errors. property auth_mfa_modules Return a list of available auth modules. property auth_providers Return a list of available auth providers. get_auth_mfa_module(module_id: str) → MultiFactorAuthModule | None Return a multi-factor auth module, None if not found. get_auth_provider(provider_type: str, provider_id: str | None) → AuthProvider | None Return an auth provider, None if not found.

4 Chapter 1. homeassistant.auth Home Assistant Documentation, Release 2021.10.0.dev0

get_auth_providers(provider_type: str) → list[AuthProvider] Return a List of auth provider of one type, Empty if not found. class homeassistant.auth.AuthManagerFlowManager(hass: homeassistant.core.HomeAssistant, auth_manager: homeassistant.auth.AuthManager) Manage authentication flows. async async_create_flow(handler_key: Any, *, context: dict[str, Any] | None = None, data: dict[str, Any] | None = None) → data_entry_flow.FlowHandler Create a login flow. async async_finish_flow(flow: homeassistant.data_entry_flow.FlowHandler, result: homeassistant.data_entry_flow.FlowResult) → homeassistant.data_entry_flow.FlowResult Return a user as result of login flow. exception homeassistant.auth.InvalidAuthError Raised when a authentication error occurs. exception homeassistant.auth.InvalidProvider Authentication provider not found. async homeassistant.auth.auth_manager_from_config(hass: HomeAssistant, provider_configs: list[dict[str, Any]], module_configs: list[dict[str, Any]]) → AuthManager Initialize an auth manager from config. CORE_CONFIG_SCHEMA will make sure do duplicated auth providers or mfa modules exist in configs.

1.1 homeassistant.auth.auth_store

Storage for auth models. class homeassistant.auth.auth_store.AuthStore(hass: homeassistant.core.HomeAssistant) Bases: object Stores authentication info. Any mutation to an object should happen inside the auth store. The auth store is lazy. It won’t load the data from disk until a method is called that needs it. async async_activate_user(user: homeassistant.auth.models.User) → None Activate a user. async async_create_refresh_token(user: models.User, client_id: str | None = None, client_name: str | None = None, client_icon: str | None = None, token_type: str = 'normal', access_token_expiration: timedelta = datetime.timedelta(seconds=1800), credential: models.Credentials | None = None) → models.RefreshToken Create a new token for a user.

1.1. homeassistant.auth.auth_store 5 Home Assistant Documentation, Release 2021.10.0.dev0

async async_create_user(name: str | None, is_owner: bool | None = None, is_active: bool | None = None, system_generated: bool | None = None, credentials: models.Credentials | None = None, group_ids: list[str] | None = None) → models.User Create a new user. async async_deactivate_user(user: homeassistant.auth.models.User) → None Activate a user. async async_get_group(group_id: str) → models.Group | None Retrieve all users. async async_get_groups() → list[models.Group] Retrieve all users. async async_get_refresh_token(token_id: str) → models.RefreshToken | None Get refresh token by id. async async_get_refresh_token_by_token(token: str) → models.RefreshToken | None Get refresh token by token. async async_get_user(user_id: str) → models.User | None Retrieve a user by id. async async_get_users() → list[models.User] Retrieve all users. async async_link_user(user: homeassistant.auth.models.User, credentials: homeassistant.auth.models.Credentials) → None Add credentials to an existing user. async_log_refresh_token_usage(refresh_token: models.RefreshToken, remote_ip: str | None = None) → None Update refresh token last used information. async async_remove_credentials(credentials: homeassistant.auth.models.Credentials) → None Remove credentials. async async_remove_refresh_token(refresh_token: homeassistant.auth.models.RefreshToken) → None Remove a refresh token. async async_remove_user(user: homeassistant.auth.models.User) → None Remove a user. async async_update_user(user: models.User, name: str | None = None, is_active: bool | None = None, group_ids: list[str] | None = None) → None Update a user.

1.2 homeassistant.auth.const

Constants for the auth module.

6 Chapter 1. homeassistant.auth Home Assistant Documentation, Release 2021.10.0.dev0

1.3 homeassistant.auth.models

Auth models. class homeassistant.auth.models.Credentials(auth_provider_type: str, auth_provider_id: str | None, data: dict, id: str = NOTHING, is_new: bool = True) Bases: object Credentials for a user on an auth provider. auth_provider_id auth_provider_type data id is_new class homeassistant.auth.models.Group(name: str | None, policy: perm_mdl.PolicyType, id: str = NOTHING, system_generated: bool = False) Bases: object A group. id name policy system_generated class homeassistant.auth.models.RefreshToken(user: User, client_id: str | None, access_token_expiration: timedelta, client_name: str | None = None, client_icon: str | None = None, token_type: str = 'normal', id: str = NOTHING, cre- ated_at: datetime = NOTHING, token: str = NOTHING, jwt_key: str = NOTHING, last_used_at: datetime | None = None, last_used_ip: str | None = None, credential: Credentials | None = None, version: str | None = '2021.10.0.dev0') Bases: object RefreshToken for a user to grant new access tokens. access_token_expiration client_icon client_id client_name created_at credential id jwt_key

1.3. homeassistant.auth.models 7 Home Assistant Documentation, Release 2021.10.0.dev0

last_used_at last_used_ip token token_type user version class homeassistant.auth.models.User(name: str | None, perm_lookup: perm_mdl.PermissionLookup, id: str = NOTH- ING, is_owner: bool = False, is_active: bool = False, system_generated: bool = False, groups: list[Group] = NOTHING, credentials: list[Credentials] = NOTHING, refresh_tokens: dict[str, RefreshToken] = NOTHING) Bases: object A user. credentials groups id invalidate_permission_cache() → None Invalidate permission cache. is_active property is_admin Return if user is part of the admin group. is_owner name perm_lookup property permissions Return permissions object for user. refresh_tokens system_generated class homeassistant.auth.models.UserMeta Bases: tuple User metadata. is_active Alias for ﬁeld number 1 name Alias for ﬁeld number 0

8 Chapter 1. homeassistant.auth CHAPTER TWO

HOMEASSISTANT.BOOTSTRAP

Provide methods to bootstrap a Home Assistant instance. homeassistant.bootstrap.async_enable_logging(hass: core.HomeAssistant, verbose: bool = False, log_rotate_days: int | None = None, log_file: str | None = None, log_no_color: bool = False) → None Set up the logging. This method must be run in the event loop. async homeassistant.bootstrap.async_from_config_dict(config: ConfigType, hass: core.HomeAssistant) → core.HomeAssistant | None Try to configure Home Assistant from a configuration dictionary. Dynamically loads required components and its dependencies. This method is a coroutine. async homeassistant.bootstrap.async_mount_local_lib_path(config_dir: str) → str Add local library to Python Path. This function is a coroutine. async homeassistant.bootstrap.async_setup_hass(runtime_config: RuntimeConfig) → core.HomeAssistant | None Set up Home Assistant. async homeassistant.bootstrap.async_setup_multi_components(hass: core.HomeAssistant, domains: set[str], config: dict[str, Any]) → None Set up multiple domains. Log on failure. homeassistant.bootstrap.open_hass_ui(hass: homeassistant.core.HomeAssistant) → None Open the UI.

9 Home Assistant Documentation, Release 2021.10.0.dev0

10 Chapter 2. homeassistant.bootstrap CHAPTER THREE

HOMEASSISTANT.COMPONENTS

3.1 air_quality

Component for handling Air Quality data for your location. class homeassistant.components.air_quality.AirQualityEntity Bases: homeassistant.helpers.entity.Entity ABC for air quality data. property air_quality_index Return the Air Quality Index (AQI). property attribution Return the attribution. property carbon_dioxide Return the CO2 (carbon dioxide) level. property carbon_monoxide Return the CO (carbon monoxide) level. entity_description = None property nitrogen_dioxide Return the NO2 (nitrogen dioxide) level. property nitrogen_monoxide Return the NO (nitrogen monoxide) level. property nitrogen_oxide Return the N2O (nitrogen oxide) level. property ozone Return the O3 (ozone) level. property particulate_matter_0_1 Return the particulate matter 0.1 level. property particulate_matter_10 Return the particulate matter 10 level. property particulate_matter_2_5 Return the particulate matter 2.5 level. property state Return the current state.

11 Home Assistant Documentation, Release 2021.10.0.dev0

property state_attributes Return the state attributes. property sulphur_dioxide Return the SO2 (sulphur dioxide) level. property unit_of_measurement Return the unit of measurement of this entity. async homeassistant.components.air_quality.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Set up the air quality component. async homeassistant.components.air_quality.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.air_quality.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

3.2 alarm_control_panel

Component to interface with an alarm control panel. class homeassistant.components.alarm_control_panel.AlarmControlPanel Bases: homeassistant.components.alarm_control_panel.AlarmControlPanelEntity An abstract class for alarm control entities (for backwards compatibility). entity_description = None class homeassistant.components.alarm_control_panel.AlarmControlPanelEntity Bases: homeassistant.helpers.entity.Entity An abstract class for alarm control entities. alarm_arm_away(code: str | None = None) → None Send arm away command. alarm_arm_custom_bypass(code: str | None = None) → None Send arm custom bypass command. alarm_arm_home(code: str | None = None) → None Send arm home command. alarm_arm_night(code: str | None = None) → None Send arm night command. alarm_arm_vacation(code: str | None = None) → None Send arm vacation command.

12 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

alarm_disarm(code: str | None = None) → None Send disarm command. alarm_trigger(code: str | None = None) → None Send alarm trigger command. async async_alarm_arm_away(code: str | None = None) → None Send arm away command. async async_alarm_arm_custom_bypass(code: str | None = None) → None Send arm custom bypass command. async async_alarm_arm_home(code: str | None = None) → None Send arm home command. async async_alarm_arm_night(code: str | None = None) → None Send arm night command. async async_alarm_arm_vacation(code: str | None = None) → None Send arm vacation command. async async_alarm_disarm(code: str | None = None) → None Send disarm command. async async_alarm_trigger(code: str | None = None) → None Send alarm trigger command. property changed_by Last change triggered by. property code_arm_required Whether the code is required for arm actions. property code_format Regex for code format or None if no code is required. entity_description = None property state_attributes Return the state attributes. property supported_features Return the list of supported features.

3.2. alarm_control_panel 13 Home Assistant Documentation, Release 2021.10.0.dev0

class homeassistant.components.alarm_control_panel.AlarmControlPanelEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes alarm control panel entities. key = None async homeassistant.components.alarm_control_panel.async_setup(hass: homeassis- tant.core.HomeAssistant, conﬁg: Dict[str, Any]) → bool Track states and offer events for sensors.

14 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.alarm_control_panel.async_setup_entry(hass: homeassis- tant.core.HomeAssistant, entry: homeassis- tant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.alarm_control_panel.async_unload_entry(hass: homeassis- tant.core.HomeAssistant, entry: homeassis- tant.config_entries.ConfigEntry) → bool Unload a config entry.

3.3 binary_sensor

Component to interface with binary sensors. class homeassistant.components.binary_sensor.BinarySensorDevice Bases: homeassistant.components.binary_sensor.BinarySensorEntity Represent a binary sensor (for backwards compatibility). entity_description = None class homeassistant.components.binary_sensor.BinarySensorEntity Bases: homeassistant.helpers.entity.Entity Represent a binary sensor. entity_description = None property is_on Return true if the binary sensor is on. property state Return the state of the binary sensor.

3.3. binary_sensor 15 Home Assistant Documentation, Release 2021.10.0.dev0

class homeassistant.components.binary_sensor.BinarySensorEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes binary sensor entities. key = None async homeassistant.components.binary_sensor.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Track states and offer events for binary sensors. async homeassistant.components.binary_sensor.async_setup_entry(hass: homeassis- tant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry.

16 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.binary_sensor.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

3.4 camera

Component to interface with cameras. class homeassistant.components.camera.Camera Bases: homeassistant.helpers.entity.Entity The base class for camera entities. async async_camera_image(width: int | None = None, height: int | None = None) → bytes | None Return bytes of camera image. async async_disable_motion_detection() → None Call the job and disable motion detection. async async_enable_motion_detection() → None Call the job and enable motion detection. async async_turn_off() → None Turn off camera. async async_turn_on() → None Turn off camera. async_update_token() → None Update the used token. async_warn_old_async_camera_image_signature() → None Warn once when calling async_camera_image with the function old signature. property brand Return the camera brand. camera_image(width: int | None = None, height: int | None = None) → bytes | None Return bytes of camera image. async create_stream() → Stream | None Create a Stream for stream_source. disable_motion_detection() → None Disable motion detection in camera. enable_motion_detection() → None Enable motion detection in the camera. entity_description = None property entity_picture Return a link to the camera feed as entity picture.

3.4. camera 17 Home Assistant Documentation, Release 2021.10.0.dev0

property frame_interval Return the interval between frames of the mjpeg stream. async handle_async_mjpeg_stream(request: web.Request) → web.StreamResponse | None Serve an HTTP MJPEG stream from the camera. This method can be overridden by camera platforms to proxy a direct stream from the camera. async handle_async_still_stream(request: aiohttp.web_request.Request, interval: ﬂoat) → aiohttp.web_response.StreamResponse Generate an HTTP MJPEG stream from camera images. property is_on Return true if on. property is_recording Return true if the device is recording. property model Return the camera model. property motion_detection_enabled Return the camera motion detection status. property should_poll No need to poll cameras. property state Return the camera state. property state_attributes Return the camera state attributes. async stream_source() → str | None Return the source of the stream. property supported_features Flag supported features. turn_off() → None Turn off camera. turn_on() → None Turn off camera. class homeassistant.components.camera.CameraEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes camera entities. key = None

18 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

class homeassistant.components.camera.CameraImageView(component: homeassistant.helpers.entity_component.EntityComponent) Bases: homeassistant.components.camera.CameraView Camera view to serve an image. async handle(request: aiohttp.web_request.Request, camera: homeassistant.components.camera.Camera) → aiohttp.web_response.Response Serve camera image. name = 'api:camera:image' url: str | None = '/api/camera_proxy/{entity_id}' class homeassistant.components.camera.CameraMjpegStream(component: homeassistant.helpers.entity_component.EntityComponent) Bases: homeassistant.components.camera.CameraView Camera View to serve an MJPEG stream. async handle(request: aiohttp.web_request.Request, camera: homeassistant.components.camera.Camera) → aiohttp.web_response.StreamResponse Serve camera stream, possibly with interval. name = 'api:camera:stream' url: str | None = '/api/camera_proxy_stream/{entity_id}' class homeassistant.components.camera.CameraView(component: homeassistant.helpers.entity_component.EntityComponent) Bases: homeassistant.components.http.view.HomeAssistantView Base CameraView. async get(request: aiohttp.web_request.Request, entity_id: str) → aiohttp.web_response.StreamResponse Start a GET request. async handle(request: aiohttp.web_request.Request, camera: homeassistant.components.camera.Camera) → aiohttp.web_response.StreamResponse Handle the camera request. requires_auth = False class homeassistant.components.camera.Image(content_type: str, content: bytes) Bases: object Represent an image. content = None content_type = None async homeassistant.components.camera.async_get_image(hass: HomeAssistant, en- tity_id: str, timeout: int = 10, width: int | None = None, height: int | None = None) → Image Fetch an image from a camera entity. width and height will be passed to the underlying camera.

3.4. camera 19 Home Assistant Documentation, Release 2021.10.0.dev0 async homeassistant.components.camera.async_get_mjpeg_stream(hass: HomeAs- sistant, request: web.Request, entity_id: str) → web.StreamResponse | None Fetch an mjpeg stream from a camera entity. async homeassistant.components.camera.async_get_still_stream(request: web.Request, image_cb: Callable[[], Awaitable[bytes | None]], con- tent_type: str, interval: ﬂoat) → web.StreamResponse Generate an HTTP MJPEG stream from camera images. This method must be run in the event loop. async homeassistant.components.camera.async_get_stream_source(hass: HomeAs- sistant, entity_id: str) → str | None Fetch the stream source for a camera entity. async homeassistant.components.camera.async_handle_play_stream_service(camera: homeas- sistant.components.camera.Camera, ser- vice_call: homeas- sistant.core.ServiceCall) → None Handle play stream services calls. async homeassistant.components.camera.async_handle_record_service(camera: homeassistant.components.camera.Camera, ser- vice_call: homeassistant.core.ServiceCall) → None Handle stream recording service calls.

20 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0 async homeassistant.components.camera.async_handle_snapshot_service(camera: homeassis- tant.components.camera.Camera, ser- vice_call: homeassis- tant.core.ServiceCall) → None Handle snapshot services calls. async homeassistant.components.camera.async_request_stream(hass: homeassistant.core.HomeAssistant, entity_id: str, fmt: str) → str Request a stream for a camera entity. async homeassistant.components.camera.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Set up the camera component. async homeassistant.components.camera.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.camera.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.camera.websocket_camera_thumbnail(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None Handle get camera thumbnail websocket command. Async friendly. homeassistant.components.camera.websocket_get_prefs(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None Handle request for account info. homeassistant.components.camera.websocket_update_prefs(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None Handle request for account info.

3.4. camera 21 Home Assistant Documentation, Release 2021.10.0.dev0 homeassistant.components.camera.ws_camera_stream(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None Handle get camera stream websocket command. Async friendly.

3.5 calendar

Support for Google Calendar event device sensors. class homeassistant.components.calendar.CalendarEventDevice Bases: homeassistant.helpers.entity.Entity Base class for calendar event entities. async async_get_events(hass, start_date, end_date) Return calendar events within a datetime range. entity_description = None property event Return the next upcoming event. property state Return the state of the calendar event. property state_attributes Return the entity state attributes. class homeassistant.components.calendar.CalendarEventView(component: homeassistant.helpers.entity_component.EntityComponent) Bases: homeassistant.components.http.view.HomeAssistantView View to retrieve calendar content. async get(request, entity_id) Return calendar events. name = 'api:calendars:calendar' url: str | None = '/api/calendars/{entity_id}' class homeassistant.components.calendar.CalendarListView(component: homeassistant.helpers.entity_component.EntityComponent) Bases: homeassistant.components.http.view.HomeAssistantView View to retrieve calendar list. async get(request: aiohttp.web_request.Request) → aiohttp.web_response.Response Retrieve calendar list. name = 'api:calendars' url: str | None = '/api/calendars' async homeassistant.components.calendar.async_setup(hass, conﬁg) Track states and offer events for calendars.

22 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.calendar.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.calendar.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.calendar.calculate_offset(event, offset) Calculate event offset. Return the updated event with the offset_time included. homeassistant.components.calendar.get_date(date) Get the dateTime from date or dateTime as a local. homeassistant.components.calendar.is_offset_reached(event) Have we reached the offset time specified in the event title. homeassistant.components.calendar.normalize_event(event) Normalize a calendar event.

3.6 climate

Provides functionality to interact with climate devices. class homeassistant.components.climate.ClimateDevice Bases: homeassistant.components.climate.ClimateEntity Representation of a climate entity (for backwards compatibility). entity_description = None class homeassistant.components.climate.ClimateEntity Bases: homeassistant.helpers.entity.Entity Base class for climate entities. async async_set_fan_mode(fan_mode: str) → None Set new target fan mode. async async_set_humidity(humidity: int) → None Set new target humidity. async async_set_hvac_mode(hvac_mode: str) → None Set new target hvac mode. async async_set_preset_mode(preset_mode: str) → None Set new preset mode. async async_set_swing_mode(swing_mode: str) → None Set new target swing operation. async async_set_temperature(**kwargs) → None Set new target temperature.

3.6. climate 23 Home Assistant Documentation, Release 2021.10.0.dev0

async async_turn_aux_heat_off() → None Turn auxiliary heater off. async async_turn_aux_heat_on() → None Turn auxiliary heater on. async async_turn_off() → None Turn the entity off. async async_turn_on() → None Turn the entity on. property capability_attributes Return the capability attributes. property current_humidity Return the current humidity. property current_temperature Return the current temperature. entity_description = None property fan_mode Return the fan setting. Requires SUPPORT_FAN_MODE. property fan_modes Return the list of available fan modes. Requires SUPPORT_FAN_MODE. property hvac_action Return the current running hvac operation if supported. Need to be one of CURRENT_HVAC_*. property hvac_mode Return hvac operation ie. heat, cool mode. Need to be one of HVAC_MODE_*. property hvac_modes Return the list of available hvac operation modes. Need to be a subset of HVAC_MODES. property is_aux_heat Return true if aux heater. Requires SUPPORT_AUX_HEAT. property max_humidity Return the maximum humidity. property max_temp Return the maximum temperature. property min_humidity Return the minimum humidity. property min_temp Return the minimum temperature.

24 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

property precision Return the precision of the system. property preset_mode Return the current preset mode, e.g., home, away, temp. Requires SUPPORT_PRESET_MODE. property preset_modes Return a list of available preset modes. Requires SUPPORT_PRESET_MODE. set_fan_mode(fan_mode: str) → None Set new target fan mode. set_humidity(humidity: int) → None Set new target humidity. set_hvac_mode(hvac_mode: str) → None Set new target hvac mode. set_preset_mode(preset_mode: str) → None Set new preset mode. set_swing_mode(swing_mode: str) → None Set new target swing operation. set_temperature(**kwargs) → None Set new target temperature. property state Return the current state. property state_attributes Return the optional state attributes. property supported_features Return the list of supported features. property swing_mode Return the swing setting. Requires SUPPORT_SWING_MODE. property swing_modes Return the list of available swing modes. Requires SUPPORT_SWING_MODE. property target_humidity Return the humidity we try to reach. property target_temperature Return the temperature we try to reach. property target_temperature_high Return the highbound target temperature we try to reach. Requires SUPPORT_TARGET_TEMPERATURE_RANGE. property target_temperature_low Return the lowbound target temperature we try to reach. Requires SUPPORT_TARGET_TEMPERATURE_RANGE.

3.6. climate 25 Home Assistant Documentation, Release 2021.10.0.dev0

property target_temperature_step Return the supported step of target temperature. property temperature_unit Return the unit of measurement used by the platform. turn_aux_heat_off() → None Turn auxiliary heater off. turn_aux_heat_on() → None Turn auxiliary heater on. class homeassistant.components.climate.ClimateEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes climate entities. key = None async homeassistant.components.climate.async_service_aux_heat(entity: homeassistant.components.climate.ClimateEntity, service_call: homeassistant.core.ServiceCall) → None Handle aux heat service. async homeassistant.components.climate.async_service_temperature_set(entity: homeassis- tant.components.climate.ClimateEntity, ser- vice_call: homeassis- tant.core.ServiceCall) → None Handle set temperature service. async homeassistant.components.climate.async_setup(hass: homeassistant.core.HomeAssistant, conﬁg: Dict[str, Any]) → bool Set up climate entities.

26 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.climate.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.climate.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

3.7 conversation

Support for functionality to have conversations with Home Assistant. class homeassistant.components.conversation.ConversationProcessView Bases: homeassistant.components.http.view.HomeAssistantView View to process text. name = 'api:conversation:process' async post(request, data) Send a request for processing. url: str | None = '/api/conversation/process' homeassistant.components.conversation.async_set_agent(hass: homeassistant.core.HomeAssistant, agent: homeassistant.components.conversation.agent.AbstractConversationAgent) Set the agent to handle the conversations. async homeassistant.components.conversation.async_setup(hass, conﬁg) Register the process service. homeassistant.components.conversation.websocket_get_agent_info(hass, connection, msg) Do we need onboarding. homeassistant.components.conversation.websocket_process(hass, connection, msg) Process text. homeassistant.components.conversation.websocket_set_onboarding(hass, connection, msg) Set onboarding status.

3.7. conversation 27 Home Assistant Documentation, Release 2021.10.0.dev0

3.8 cover

Support for Cover devices. class homeassistant.components.cover.CoverDevice Bases: homeassistant.components.cover.CoverEntity Representation of a cover (for backwards compatibility). entity_description = None class homeassistant.components.cover.CoverEntity Bases: homeassistant.helpers.entity.Entity Base class for cover entities. async async_close_cover(**kwargs) Close cover. async async_close_cover_tilt(**kwargs) Close the cover tilt. async async_open_cover(**kwargs) Open the cover. async async_open_cover_tilt(**kwargs) Open the cover tilt. async async_set_cover_position(**kwargs) Move the cover to a speciﬁc position. async async_set_cover_tilt_position(**kwargs) Move the cover tilt to a speciﬁc position. async async_stop_cover(**kwargs) Stop the cover. async async_stop_cover_tilt(**kwargs) Stop the cover. async async_toggle(**kwargs) Toggle the entity. async async_toggle_tilt(**kwargs) Toggle the entity. close_cover(**kwargs: Any) → None Close cover. close_cover_tilt(**kwargs: Any) → None Close the cover tilt. property current_cover_position Return current position of cover. None is unknown, 0 is closed, 100 is fully open. property current_cover_tilt_position Return current position of cover tilt. None is unknown, 0 is closed, 100 is fully open. entity_description = None

28 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

property is_closed Return if the cover is closed or not. property is_closing Return if the cover is closing or not. property is_opening Return if the cover is opening or not. open_cover(**kwargs: Any) → None Open the cover. open_cover_tilt(**kwargs: Any) → None Open the cover tilt. set_cover_position(**kwargs) Move the cover to a specific position. set_cover_tilt_position(**kwargs) Move the cover tilt to a specific position. property state Return the state of the cover. property state_attributes Return the state attributes. stop_cover(**kwargs) Stop the cover. stop_cover_tilt(**kwargs) Stop the cover. property supported_features Flag supported features. toggle(**kwargs: Any) → None Toggle the entity. toggle_tilt(**kwargs: Any) → None Toggle the entity. class homeassistant.components.cover.CoverEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes cover entities. key = None async homeassistant.components.cover.async_setup(hass, config) Track states and offer events for covers.

3.8. cover 29 Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.cover.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.cover.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.cover.is_closed(hass, entity_id) Return if the cover is closed based on the statemachine.

3.9 device_tracker

Provide functionality to keep track of devices. async homeassistant.components.device_tracker.async_setup(hass: homeassistant.core.HomeAssistant, conﬁg: Dict[str, Any]) → bool Set up the device tracker. homeassistant.components.device_tracker.is_on(hass: homeassistant.core.HomeAssistant, entity_id: str) → bool Return the state if any or a speciﬁed device is home.

3.10 fan

Provides functionality to interact with fans. class homeassistant.components.fan.FanEntity Bases: homeassistant.helpers.entity.ToggleEntity Base class for fan entities. async async_decrease_speed(percentage_step: int | None = None) → None Decrease the speed of the fan. async async_increase_speed(percentage_step: int | None = None) → None Increase the speed of the fan. async async_oscillate(oscillating: bool) Oscillate the fan. async async_set_direction(direction: str) Set the direction of the fan. async async_set_percentage(percentage: int) → None Set the speed of the fan, as a percentage. async async_set_preset_mode(preset_mode: str) → None Set new preset mode.

30 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

async async_set_speed(speed: str) Set the speed of the fan. async async_set_speed_deprecated(speed: str) Set the speed of the fan. async async_turn_on(speed: str | None = None, percentage: int | None = None, preset_mode: str | None = None, **kwargs) → None Turn on the fan. async async_turn_on_compat(speed: str | None = None, percentage: int | None = None, pre- set_mode: str | None = None, **kwargs) → None Turn on the fan. This _compat version wraps async_turn_on with backwards and forward compatibility. After the transition to percentage and preset_modes concludes, it should be removed. property capability_attributes Return capability attributes. property current_direction Return the current direction of the fan. entity_description: FanEntityDescription = None property is_on Return true if the entity is on. oscillate(oscillating: bool) → None Oscillate the fan. property oscillating Return whether or not the fan is currently oscillating. property percentage Return the current speed as a percentage. property percentage_step Return the step size for percentage. percentage_to_speed(percentage: int) → str Map a percentage onto self.speed_list. Ofﬁcially, this should only have to deal with 4 pre-deﬁned speeds. if value == 0: return SPEED_OFF elif value <= 33: return SPEED_LOW elif value <= 66: return SPEED_MEDIUM else: return SPEED_HIGH Unfortunately there is currently a high degree of non-conformancy. Until fans have been corrected a more complicated and dynamic mapping is used. property preset_mode Return the current preset mode, e.g., auto, smart, interval, favorite. Requires SUPPORT_SET_SPEED. property preset_modes Return a list of available preset modes. Requires SUPPORT_SET_SPEED.

3.10. fan 31 Home Assistant Documentation, Release 2021.10.0.dev0

set_direction(direction: str) → None Set the direction of the fan. set_percentage(percentage: int) → None Set the speed of the fan, as a percentage. set_preset_mode(preset_mode: str) → None Set new preset mode. set_speed(speed: str) → None Set the speed of the fan. property speed Return the current speed. property speed_count Return the number of speeds the fan supports. property speed_list Get the list of available speeds. speed_to_percentage(speed: str) → int Map a speed to a percentage. Ofﬁcially this should only have to deal with the 4 pre-deﬁned speeds: return { SPEED_OFF: 0, SPEED_LOW: 33, SPEED_MEDIUM: 66, SPEED_HIGH: 100, }[speed] Unfortunately lots of fans make up their own speeds. So the default mapping is more dynamic. property state_attributes Return optional state attributes. property supported_features Flag supported features. turn_on(speed: str | None = None, percentage: int | None = None, preset_mode: str | None = None, **kwargs) → None Turn on the fan. class homeassistant.components.fan.FanEntityDescription(key: str, device_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.ToggleEntityDescription A class that describes fan entities. key = None exception homeassistant.components.fan.NoValidSpeedsError Bases: ValueError Exception class when there are no valid speeds. exception homeassistant.components.fan.NotValidPresetModeError Bases: ValueError

32 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

Exception class when the preset_mode in not in the preset_modes list. exception homeassistant.components.fan.NotValidSpeedError Bases: ValueError Exception class when the speed in not in the speed list. async homeassistant.components.fan.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Expose fan control via statemachine and services. async homeassistant.components.fan.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.fan.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.fan.is_on(hass, entity_id: str) → bool Return if the fans are on based on the statemachine. homeassistant.components.fan.preset_modes_from_speed_list(speed_list: list) Filter out non-preset modes from the speed list. The goal is to return only preset modes. Examples: input: [“off”, “low”, “low-medium”, “medium”, “medium-high”, “high”, “auto”] output: [“auto”] input: [“off”, “auto”, “low”, “medium”, “high”] output: [“auto”] input: [“off”, “1”, “2”, “3”, “4”, “5”, “6”, “7”, “smart”] output: [“smart”] input: [“Auto”, “Silent”, “Favorite”, “Idle”, “Medium”, “High”, “Strong”] output: [“Auto”, “Silent”, “Fa- vorite”, “Idle”] homeassistant.components.fan.speed_list_without_preset_modes(speed_list: list) Filter out non-speeds from the speed list. The goal is to get the speeds in a list from lowest to highest by removing speeds that are not valid or out of order so we can map them to percentages. Examples: input: [“off”, “low”, “low-medium”, “medium”, “medium-high”, “high”, “auto”] output: [“low”, “low-medium”, “medium”, “medium-high”, “high”] input: [“off”, “auto”, “low”, “medium”, “high”] output: [“low”, “medium”, “high”] input: [“off”, “1”, “2”, “3”, “4”, “5”, “6”, “7”, “smart”] output: [“1”, “2”, “3”, “4”, “5”, “6”, “7”] input: [“Auto”, “Silent”, “Favorite”, “Idle”, “Medium”, “High”, “Strong”] output: [“Medium”, “High”, “Strong”]

3.10. fan 33 Home Assistant Documentation, Release 2021.10.0.dev0

3.11 light

Provides functionality to interact with lights. class homeassistant.components.light.Light Bases: homeassistant.components.light.LightEntity Representation of a light (for backwards compatibility). entity_description = None class homeassistant.components.light.LightEntity Bases: homeassistant.helpers.entity.ToggleEntity Base class for light entities. property brightness Return the brightness of this light between 0..255. property capability_attributes Return capability attributes. property color_mode Return the color mode of the light. property color_temp Return the CT color value in mireds. property effect Return the current effect. property effect_list Return the list of supported effects. entity_description = None property hs_color Return the hue and saturation color value [ﬂoat, ﬂoat]. property max_mireds Return the warmest color_temp that this light supports. property min_mireds Return the coldest color_temp that this light supports. property rgb_color Return the rgb color value [int, int, int]. property rgbw_color Return the rgbw color value [int, int, int, int]. property rgbww_color Return the rgbww color value [int, int, int, int, int]. property state_attributes Return state attributes. property supported_color_modes Flag supported color modes. property supported_features Flag supported features.

34 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

property white_value Return the white value of this light between 0..255. property xy_color Return the xy color value [float, float]. class homeassistant.components.light.LightEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.ToggleEntityDescription A class that describes binary sensor entities. key = None class homeassistant.components.light.Profile(name: str, color_x: float | None, color_y: float | None, brightness: int | None, transition: int | None = None) Bases: object Representation of a profile. SCHEMA = , Any(All(Coerce(float, msg=None), Range(min=0, max=1, min_included=True, max_included=True, msg=None), msg=None), , msg=None), Any(All(Coerce(float, msg=None), Range(min=0, max=1, min_included=True, max_included=True, msg=None), msg=None), , msg=None), Any(All(Coerce(int, msg=None), Range(min=0, max=255, min_included=True, max_included=True, msg=None), msg=None), , msg=None)]), ExactSequence([, Any(All(Coerce(float, msg=None), Range(min=0, max=1, min_included=True, max_included=True, msg=None), msg=None), , msg=None), Any(All(Coerce(float, msg=None), Range(min=0, max=1, min_included=True, max_included=True, msg=None), msg=None), , msg=None), Any(All(Coerce(int, msg=None), Range(min=0, max=255, min_included=True, max_included=True, msg=None), msg=None), , msg=None), Any(All(Coerce(float, msg=None), Clamp(min=0, max=6553), msg=None), , msg=None)]), msg=None), extra=PREVENT_EXTRA, required=False) object> brightness = None color_x = None color_y = None classmethod from_csv_row(csv_row: list[str]) → Profile Create profile from a CSV row tuple. hs_color = None name = None transition: int | None = None class homeassistant.components.light.Profiles(hass: homeassistant.core.HomeAssistant) Bases: object Representation of available color profiles. apply_default(entity_id: str, state_on: bool, params: dict) → None Return the default profile for the given light. apply_profile(name: str, params: dict) → None Apply a profile. async async_initialize() → None Load and cache profiles. async homeassistant.components.light.async_setup(hass, config) Expose light control via state machine and services.

3.11. light 35 Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.light.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.light.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.light.brightness_supported(color_modes: Iterable[str] | None) → bool Test if brightness is supported. homeassistant.components.light.color_supported(color_modes: Iterable[str] | None) → bool Test if color is supported. homeassistant.components.light.color_temp_supported(color_modes: Iterable[str] | None) → bool Test if color temperature is supported. homeassistant.components.light.filter_turn_off_params(light, params) Filter out params not used in turn off or not supported by the light. homeassistant.components.light.filter_turn_on_params(light, params) Filter out params not supported by the light. homeassistant.components.light.get_supported_color_modes(hass: HomeAssistant, en- tity_id: str) → set | None Get supported color modes for a light entity. First try the statemachine, then entity registry. This is the equivalent of entity helper get_supported_features. homeassistant.components.light.is_on(hass: homeassistant.core.HomeAssistant, entity_id: str) → bool Return if the lights are on based on the statemachine. homeassistant.components.light.legacy_supported_features(supported_features: int, supported_color_modes: list[str] | None) → int Calculate supported features with backwards compatibility. homeassistant.components.light.preprocess_turn_on_alternatives(hass, params) Process extra data for turn light on request. Async friendly. homeassistant.components.light.valid_supported_color_modes(color_modes: Iter- able[str]) → set[str] Validate the given color modes.

36 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

3.12 lock

Component to interface with locks that can be controlled remotely. class homeassistant.components.lock.LockDevice Bases: homeassistant.components.lock.LockEntity Representation of a lock (for backwards compatibility). entity_description = None class homeassistant.components.lock.LockEntity Bases: homeassistant.helpers.entity.Entity Base class for lock entities. async async_lock(**kwargs: Any) → None Lock the lock. async async_open(**kwargs: Any) → None Open the door latch. async async_unlock(**kwargs: Any) → None Unlock the lock. property changed_by Last change triggered by. property code_format Regex for code format or None if no code is required. entity_description = None property is_jammed Return true if the lock is jammed (incomplete locking). property is_locked Return true if the lock is locked. property is_locking Return true if the lock is locking. property is_unlocking Return true if the lock is unlocking. lock(**kwargs: Any) → None Lock the lock. open(**kwargs: Any) → None Open the door latch. property state Return the state. property state_attributes Return the state attributes. unlock(**kwargs: Any) → None Unlock the lock.

3.12. lock 37 Home Assistant Documentation, Release 2021.10.0.dev0

class homeassistant.components.lock.LockEntityDescription(key: str, device_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes lock entities. key = None async homeassistant.components.lock.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Track states and offer events for locks. async homeassistant.components.lock.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.lock.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

3.13 media_player

Component to interface with various media players. class homeassistant.components.media_player.BrowseMedia(*, media_class: str, me- dia_content_id: str, me- dia_content_type: str, title: str, can_play: bool, can_expand: bool, children: list[BrowseMedia] | None = None, chil- dren_media_class: str | None = None, thumbnail: str | None = None) Bases: object Represent a browsable media ﬁle. as_dict(*, parent: bool = True) → dict Convert Media class to browse media dictionary. calculate_children_class() → None Count the children media classes and calculate the correct class.

38 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0 class homeassistant.components.media_player.MediaPlayerDevice Bases: homeassistant.components.media_player.MediaPlayerEntity ABC for media player devices (for backwards compatibility). entity_description = None class homeassistant.components.media_player.MediaPlayerEntity Bases: homeassistant.helpers.entity.Entity ABC for media player entities. property access_token Access token for this media player. property app_id ID of the current running app. property app_name Name of the current running app. async async_browse_media(media_content_type: str | None = None, media_content_id: str | None = None) → BrowseMedia Return a BrowseMedia instance. The BrowseMedia instance will be used by the “media_player/browse_media” websocket command. async async_clear_playlist() Clear players playlist. async async_get_browse_image(media_content_type: str, media_content_id: str, me- dia_image_id: str | None = None) → tuple[str | None, str | None] Optionally fetch internally accessible image for media browser. Must be implemented by integration. async async_get_media_image() Fetch media image of current playing image. async async_join_players(group_members) Join group_members as a player group with the current player. async async_media_next_track() Send next track command. async async_media_pause() Send pause command. async async_media_play() Send play command. async async_media_play_pause() Play or pause the media player. async async_media_previous_track() Send previous track command. async async_media_seek(position) Send seek command. async async_media_stop() Send stop command.

3.13. media_player 39 Home Assistant Documentation, Release 2021.10.0.dev0

async async_mute_volume(mute) Mute the volume. async async_play_media(media_type, media_id, **kwargs) Play a piece of media. async async_select_sound_mode(sound_mode) Select sound mode. async async_select_source(source) Select input source. async async_set_repeat(repeat) Set repeat mode. async async_set_shuffle(shufﬂe) Enable/disable shufﬂe mode. async async_set_volume_level(volume) Set volume level, range 0..1. async async_toggle() Toggle the power on the media player. async async_turn_off() Turn the media player off. async async_turn_on() Turn the media player on. async async_unjoin_player() Remove this player from any group. async async_volume_down() Turn volume down for media player. This method is a coroutine. async async_volume_up() Turn volume up for media player. This method is a coroutine. property capability_attributes Return capability attributes. clear_playlist() Clear players playlist. entity_description = None property entity_picture Return image of the media playing. get_browse_image_url(media_content_type: str, media_content_id: str, media_image_id: str | None = None) → str Generate an url for a media browser image. property group_members List of members which are currently grouped together. property is_volume_muted Boolean if volume is currently muted.

40 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

join_players(group_members) Join group_members as a player group with the current player. property media_album_artist Album artist of current playing media, music track only. property media_album_name Album name of current playing media, music track only. property media_artist Artist of current playing media, music track only. property media_channel Channel currently playing. property media_content_id Content ID of current playing media. property media_content_type Content type of current playing media. property media_duration Duration of current playing media in seconds. property media_episode Episode of current playing media, TV show only. property media_image_hash Hash value for media image. property media_image_local Return local url to media image. property media_image_remotely_accessible If the image url is remotely accessible. property media_image_url Image url of current playing media. media_next_track() Send next track command. media_pause() Send pause command. media_play() Send play command. property media_playlist Title of Playlist currently playing. property media_position Position of current playing media in seconds. property media_position_updated_at When was the position of the current playing media valid. Returns value from homeassistant.util.dt.utcnow(). media_previous_track() Send previous track command. property media_season Season of current playing media, TV show only.

3.13. media_player 41 Home Assistant Documentation, Release 2021.10.0.dev0

media_seek(position) Send seek command. property media_series_title Title of series of current playing media, TV show only. media_stop() Send stop command. property media_title Title of current playing media. property media_track Track number of current playing media, music track only. mute_volume(mute) Mute the volume. play_media(media_type, media_id, **kwargs) Play a piece of media. property repeat Return current repeat mode. select_sound_mode(sound_mode) Select sound mode. select_source(source) Select input source. set_repeat(repeat) Set repeat mode. set_shuffle(shuffle) Enable/disable shuffle mode. set_volume_level(volume) Set volume level, range 0..1. property shuffle Boolean if shuffle is enabled. property sound_mode Name of the current sound mode. property sound_mode_list List of available sound modes. property source Name of the current input source. property source_list List of available input sources. property state State of the player. property state_attributes Return the state attributes. property support_clear_playlist Boolean if clear playlist command supported.

42 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

property support_grouping Boolean if player grouping is supported. property support_next_track Boolean if next track command supported. property support_pause Boolean if pause is supported. property support_play Boolean if play is supported. property support_play_media Boolean if play media command supported. property support_previous_track Boolean if previous track command supported. property support_seek Boolean if seek is supported. property support_select_sound_mode Boolean if select sound mode command supported. property support_select_source Boolean if select source command supported. property support_shuffle_set Boolean if shufﬂe is supported. property support_stop Boolean if stop is supported. property support_volume_mute Boolean if muting volume is supported. property support_volume_set Boolean if setting volume is supported. property supported_features Flag media player features that are supported. turn_off() Turn the media player off. turn_on() Turn the media player on. unjoin_player() Remove this player from any group. property volume_level Volume level of the media player (0..1).

3.13. media_player 43 Home Assistant Documentation, Release 2021.10.0.dev0

class homeassistant.components.media_player.MediaPlayerEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes media player entities. key = None class homeassistant.components.media_player.MediaPlayerImageView(component) Bases: homeassistant.components.http.view.HomeAssistantView Media player view to serve an image. extra_urls: list[str] = ['/api/media_player_proxy/{entity_id}/browse_media/{media_content_type}/{media_content_id}'] async get(request: web.Request, entity_id: str, media_content_type: str | None = None, me- dia_content_id: str | None = None) → web.Response Start a get request. name = 'api:media_player:image' requires_auth = False url: str | None = '/api/media_player_proxy/{entity_id}'

44 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.media_player.async_setup(hass, config) Track states and offer events for media_players. async homeassistant.components.media_player.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.media_player.async_unload_entry(hass: homeassis- tant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.media_player.is_on(hass, entity_id=None) Return true if specified media player entity_id is on. Check all media player if no entity_id specified. homeassistant.components.media_player.websocket_browse_media(hass, connection, msg) Browse media available to the media_player entity. To use, media_player integrations can implement MediaPlayerEntity.async_browse_media() homeassistant.components.media_player.websocket_handle_thumbnail(hass, connection, msg) Handle get media player cover command. Async friendly.

3.14 notify

Provides functionality to notify people. class homeassistant.components.notify.BaseNotificationService Bases: object An abstract class for notiﬁcation services. async async_register_services() → None Create or update the notify services. async async_send_message(message: Any, **kwargs: Any) → None Send a message. kwargs can contain ATTR_TITLE to specify a title. async async_setup(hass: homeassistant.core.HomeAssistant, service_name: str, tar- get_service_name_preﬁx: str) → None Store the data for the notify service. async async_unregister_services() → None Unregister the notify services. hass: HomeAssistant = None

3.14. notify 45 Home Assistant Documentation, Release 2021.10.0.dev0

registered_targets: dict[str, str] = None send_message(message, **kwargs) Send a message. kwargs can contain ATTR_TITLE to specify a title. async homeassistant.components.notify.async_reload(hass: homeassistant.core.HomeAssistant, inte- gration_name: str) → None Register notify services for an integration. async homeassistant.components.notify.async_reset_platform(hass: homeassistant.core.HomeAssistant, integration_name: str) → None Unregister notify services for an integration. async homeassistant.components.notify.async_setup(hass, conﬁg) Set up the notify services.

3.15 remote

Support to interface with universal remote control devices. class homeassistant.components.remote.RemoteDevice Bases: homeassistant.components.remote.RemoteEntity Representation of a remote (for backwards compatibility). entity_description = None class homeassistant.components.remote.RemoteEntity Bases: homeassistant.helpers.entity.ToggleEntity Base class for remote entities. property activity_list List of available activities. async async_delete_command(**kwargs: Any) → None Delete commands from the database. async async_learn_command(**kwargs: Any) → None Learn a command from a device. async async_send_command(command: Iterable[str], **kwargs: Any) → None Send commands to a device. property current_activity Active activity. delete_command(**kwargs: Any) → None Delete commands from the database. entity_description = None learn_command(**kwargs: Any) → None Learn a command from a device. send_command(command: Iterable[str], **kwargs: Any) → None Send commands to a device.

46 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

property state_attributes Return optional state attributes. property supported_features Flag supported features. class homeassistant.components.remote.RemoteEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.ToggleEntityDescription A class that describes remote entities. key = None async homeassistant.components.remote.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Track states and offer events for remotes. async homeassistant.components.remote.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.remote.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.remote.is_on(hass: homeassistant.core.HomeAssistant, entity_id: str) → bool Return if the remote is on based on the statemachine.

3.16 switch

Component to interface with switches that can be controlled remotely. class homeassistant.components.switch.SwitchDevice Bases: homeassistant.components.switch.SwitchEntity Representation of a switch (for backwards compatibility). entity_description = None

3.16. switch 47 Home Assistant Documentation, Release 2021.10.0.dev0 class homeassistant.components.switch.SwitchEntity Bases: homeassistant.helpers.entity.ToggleEntity Base class for switch entities. property current_power_w Return the current power usage in W. entity_description = None property state_attributes Return the optional state attributes. property today_energy_kwh Return the today total energy usage in kWh. class homeassistant.components.switch.SwitchEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.ToggleEntityDescription A class that describes switch entities. key = None async homeassistant.components.switch.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Track states and offer events for switches. async homeassistant.components.switch.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.switch.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. homeassistant.components.switch.is_on(hass: homeassistant.core.HomeAssistant, entity_id: str) → bool Return if the switch is on based on the statemachine. Async friendly.

48 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

3.17 sensor

Component to interface with various sensors that can be monitored. class homeassistant.components.sensor.SensorEntity Bases: homeassistant.helpers.entity.Entity Base class for sensor entities. property capability_attributes Return the capability attributes. entity_description = None property last_reset Return the time when the sensor was last reset, if any. property native_unit_of_measurement Return the unit of measurement of the sensor, if any. property native_value Return the value reported by the sensor. property state Return the state of the sensor and perform unit conversions, if needed. property state_attributes Return state attributes. property state_class Return the state class of this entity, from STATE_CLASSES, if any. property unit_of_measurement Return the unit of measurement of the entity, after unit conversion. class homeassistant.components.sensor.SensorEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: None = None, last_reset: datetime | None = None, na- tive_unit_of_measurement: str | None = None, state_class: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes sensor entities. last_reset: datetime | None = None native_unit_of_measurement: str | None = None

3.17. sensor 49 Home Assistant Documentation, Release 2021.10.0.dev0

state_class: str | None = None unit_of_measurement: None = None async homeassistant.components.sensor.async_setup(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → bool Track states and offer events for sensors. async homeassistant.components.sensor.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.sensor.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

3.18 vacuum

Support for vacuum cleaner robots (botvacs). class homeassistant.components.vacuum.StateVacuumDevice Bases: homeassistant.components.vacuum.StateVacuumEntity Representation of a vacuum (for backwards compatibility). entity_description = None class homeassistant.components.vacuum.StateVacuumEntity Bases: homeassistant.components.vacuum._BaseVacuum Representation of a vacuum cleaner robot that supports states. async async_pause() Pause the cleaning task. This method must be run in the event loop. async async_start() Start or resume the cleaning task. This method must be run in the event loop. async async_toggle(**kwargs) Not supported. async async_turn_off(**kwargs) Not supported. async async_turn_on(**kwargs) Not supported. property battery_icon Return the battery icon for the vacuum cleaner. entity_description: StateVacuumEntityDescription = None

50 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

pause() Pause the cleaning task. start() Start or resume the cleaning task. property state Return the state of the vacuum cleaner. class homeassistant.components.vacuum.StateVacuumEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes vacuum entities. key = None class homeassistant.components.vacuum.VacuumDevice Bases: homeassistant.components.vacuum.VacuumEntity Representation of a vacuum (for backwards compatibility). entity_description = None class homeassistant.components.vacuum.VacuumEntity Bases: homeassistant.components.vacuum._BaseVacuum, homeassistant.helpers. entity.ToggleEntity Representation of a vacuum cleaner robot. async async_pause() Not supported. async async_start() Not supported. async async_start_pause(**kwargs) Start, pause or resume the cleaning task. This method must be run in the event loop. async async_turn_off(**kwargs) Turn the vacuum off stopping the cleaning and returning home.

3.18. vacuum 51 Home Assistant Documentation, Release 2021.10.0.dev0

This method must be run in the event loop. async async_turn_on(**kwargs) Turn the vacuum on and start cleaning. This method must be run in the event loop. property battery_icon Return the battery icon for the vacuum cleaner. entity_description: VacuumEntityDescription = None start_pause(**kwargs) Start, pause or resume the cleaning task. property state_attributes Return the state attributes of the vacuum cleaner. property status Return the status of the vacuum cleaner. turn_off(**kwargs) Turn the vacuum off stopping the cleaning and returning home. turn_on(**kwargs) Turn the vacuum on and start cleaning. class homeassistant.components.vacuum.VacuumEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.ToggleEntityDescription A class that describes vacuum entities. key = None async homeassistant.components.vacuum.async_setup(hass, config) Set up the vacuum component. async homeassistant.components.vacuum.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.vacuum.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

52 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0 homeassistant.components.vacuum.is_on(hass, entity_id) Return if the vacuum is on based on the statemachine.

3.19 water_heater

Support for water heater devices. class homeassistant.components.water_heater.WaterHeaterDevice Bases: homeassistant.components.water_heater.WaterHeaterEntity Representation of a water heater (for backwards compatibility). entity_description = None class homeassistant.components.water_heater.WaterHeaterEntity Bases: homeassistant.helpers.entity.Entity Base class for water heater entities. async async_set_operation_mode(operation_mode) Set new target operation mode. async async_set_temperature(**kwargs) Set new target temperature. async async_turn_away_mode_off() Turn away mode off. async async_turn_away_mode_on() Turn away mode on. property capability_attributes Return capability attributes. property current_operation Return current operation ie. eco, electric, performance, . . . property current_temperature Return the current temperature. entity_description = None property is_away_mode_on Return true if away mode is on. property max_temp Return the maximum temperature. property min_temp Return the minimum temperature. property operation_list Return the list of available operation modes. property precision Return the precision of the system. set_operation_mode(operation_mode) Set new target operation mode. set_temperature(**kwargs) Set new target temperature.

3.19. water_heater 53 Home Assistant Documentation, Release 2021.10.0.dev0

property state Return the current state. property state_attributes Return the optional state attributes. property target_temperature Return the temperature we try to reach. property target_temperature_high Return the highbound target temperature we try to reach. property target_temperature_low Return the lowbound target temperature we try to reach. property temperature_unit Return the unit of measurement used by the platform. turn_away_mode_off() Turn away mode off. turn_away_mode_on() Turn away mode on.

54 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

class homeassistant.components.water_heater.WaterHeaterEntityEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes water heater entities. key = None async homeassistant.components.water_heater.async_service_away_mode(entity, service) Handle away mode service. async homeassistant.components.water_heater.async_service_temperature_set(entity, service) Handle set temperature service. async homeassistant.components.water_heater.async_setup(hass, conﬁg) Set up water_heater devices.

3.19. water_heater 55 Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.components.water_heater.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async homeassistant.components.water_heater.async_unload_entry(hass: homeassis- tant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

3.20 weather

Weather component that handles meteorological data for your location. class homeassistant.components.weather.Forecast Bases: dict Typed weather forecast dict. condition = None datetime = None precipitation = None precipitation_probability = None pressure = None temperature = None templow = None wind_bearing = None wind_speed = None class homeassistant.components.weather.WeatherEntity Bases: homeassistant.helpers.entity.Entity ABC for weather data. property attribution Return the attribution. property condition Return the current condition. entity_description = None property forecast Return the forecast. property humidity Return the humidity.

56 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0

property ozone Return the ozone level. property precision Return the precision of the temperature value. property pressure Return the pressure. property state Return the current state. property state_attributes Return the state attributes. property temperature Return the platform temperature. property temperature_unit Return the unit of measurement. property visibility Return the visibility. property wind_bearing Return the wind bearing. property wind_speed Return the wind speed. class homeassistant.components.weather.WeatherEntityDescription(key: str, de- vice_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes weather entities. key = None async homeassistant.components.weather.async_setup(hass, config) Set up the weather component. async homeassistant.components.weather.async_setup_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry.

3.20. weather 57 Home Assistant Documentation, Release 2021.10.0.dev0 async homeassistant.components.weather.async_unload_entry(hass: homeassistant.core.HomeAssistant, entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry.

3.21 webhook

Webhooks for Home Assistant. class homeassistant.components.webhook.WebhookView Bases: homeassistant.components.http.view.HomeAssistantView Handle incoming webhook requests. cors_allowed = True async head(request: aiohttp.web_request.Request, webhook_id) Handle webhook call. name = 'api:webhook' async post(request: aiohttp.web_request.Request, webhook_id) Handle webhook call. async put(request: aiohttp.web_request.Request, webhook_id) Handle webhook call. requires_auth = False url: str | None = '/api/webhook/{webhook_id}' homeassistant.components.webhook.async_generate_id() → str Generate a webhook_id. homeassistant.components.webhook.async_generate_path(webhook_id: str) → str Generate the path component for a webhook_id. homeassistant.components.webhook.async_generate_url(hass: homeassistant.core.HomeAssistant, web- hook_id: str) → str Generate the full URL for a webhook_id. async homeassistant.components.webhook.async_handle_webhook(hass, webhook_id, request) Handle a webhook. homeassistant.components.webhook.async_register(hass: HomeAssistant, domain: str, name: str, webhook_id: str, handler: Callable[[HomeAssistant, str, Re- quest], Awaitable[Response | None]]) → None Register a webhook. async homeassistant.components.webhook.async_setup(hass, conﬁg) Initialize the webhook component. homeassistant.components.webhook.async_unregister(hass: homeassistant.core.HomeAssistant, web- hook_id: str) → None Remove a webhook.

58 Chapter 3. homeassistant.components Home Assistant Documentation, Release 2021.10.0.dev0 homeassistant.components.webhook.websocket_list(hass, connection, msg) Return a list of webhooks.

3.21. webhook 59 Home Assistant Documentation, Release 2021.10.0.dev0

60 Chapter 3. homeassistant.components CHAPTER FOUR

HOMEASSISTANT.CONFIG_ENTRIES

Manage config entries in Home Assistant. class homeassistant.config_entries.ConfigEntries(hass: homeassistant.core.HomeAssistant, hass_config: Dict[str, Any]) Manage the configuration entries. An instance of this object is available via hass.config_entries. async async_add(entry: homeassistant.config_entries.ConfigEntry) → None Add and setup an entry. async_domains(include_ignore: bool = False, include_disabled: bool = False) → list[str] Return domains for which we have entries. async_entries(domain: str | None = None) → list[ConfigEntry] Return all entries or entries for a specific domain. async async_forward_entry_setup(entry: homeassistant.config_entries.ConfigEntry, domain: str) → bool Forward the setup of an entry to a different component. By default an entry is setup with the component it belongs to. If that component also has related platforms, the component will have to forward the entry to be setup by that component. You don’t want to await this coroutine if it is called as part of the setup of a component, because it can cause a deadlock. async async_forward_entry_unload(entry: homeassistant.config_entries.ConfigEntry, domain: str) → bool Forward the unloading of an entry to a different component. async_get_entry(entry_id: str) → ConfigEntry | None Return entry with matching entry_id. async async_initialize() → None Initialize config entry config. async async_reload(entry_id: str) → bool Reload an entry. If an entry was not loaded, will just load. async async_remove(entry_id: str) → dict[str, Any] Remove an entry. async async_set_disabled_by(entry_id: str, disabled_by: str | None) → bool Disable an entry. If disabled_by is changed, the config entry will be reloaded.

61 Home Assistant Documentation, Release 2021.10.0.dev0

async async_setup(entry_id: str) → bool Set up a config entry. Return True if entry has been successfully loaded. async_setup_platforms(entry: ConfigEntry, platforms: Iterable[str]) → None Forward the setup of an entry to platforms. async async_unload(entry_id: str) → bool Unload a config entry. async async_unload_platforms(entry: ConfigEntry, platforms: Iterable[str]) → bool Forward the unloading of an entry to platforms. async_update_entry(entry: ConfigEntry, *, unique_id: str | None | UndefinedType = , title: str | UndefinedType = , data: dict | UndefinedType = , options: Mapping[str, Any] | UndefinedType = , pref_disable_new_entities: bool | UndefinedType = , pref_disable_polling: bool | UndefinedType = ) → bool Update a config entry. If the entry was changed, the update_listeners are fired and this function returns True If the entry was not changed, the update_listeners are not fired and this function returns False class homeassistant.config_entries.ConfigEntriesFlowManager(hass: homeassistant.core.HomeAssistant, config_entries: homeassistant.config_entries.ConfigEntries, hass_config: Dict[str, Any]) Manage all the config entry flows that are in progress. async async_create_flow(handler_key: Any, *, context: dict | None = None, data: Any = None) → ConfigFlow Create a flow for specified handler. Handler key is the domain of the component that we want to set up. async async_finish_flow(flow: homeassistant.data_entry_flow.FlowHandler, result: homeassistant.data_entry_flow.FlowResult) → homeassistant.data_entry_flow.FlowResult Finish a config flow and add an entry. async async_post_init(flow: homeassistant.data_entry_flow.FlowHandler, result: homeassistant.data_entry_flow.FlowResult) → None After a flow is initialised trigger new flow notifications. class homeassistant.config_entries.ConfigEntry(version: int, domain: str, title: str, data: Mapping[str, Any], source: str, pref_disable_new_entities: bool | None = None, pref_disable_polling: bool | None = None, options: Mapping[str, Any] | None = None, unique_id: str | None = None, entry_id: str | None = None, state: ConfigEntryState = , disabled_by: str | None = None)

62 Chapter 4. homeassistant.config_entries Home Assistant Documentation, Release 2021.10.0.dev0

Hold a configuration entry. add_update_listener(listener: Callable[[homeassistant.core.HomeAssistant, ConfigEntry], Any]) → Callable[[], None] Listen for when entry is updated. Returns function to unlisten. as_dict() → dict[str, Any] Return dictionary version of this entry. async_cancel_retry_setup() → None Cancel retry setup. async async_migrate(hass: homeassistant.core.HomeAssistant) → bool Migrate an entry. Returns True if config entry is up-to-date or has been migrated. async_on_unload(func: Callable[[], None]) → None Add a function to call when config entry is unloaded. async async_remove(hass: homeassistant.core.HomeAssistant) → None Invoke remove callback on component. async async_setup(hass: HomeAssistant, *, integration: loader.Integration | None = None, tries: int = 0) → None Set up an entry. async async_shutdown() → None Call when Home Assistant is stopping. async_start_reauth(hass: homeassistant.core.HomeAssistant) → None Start a reauth flow. async async_unload(hass: HomeAssistant, *, integration: loader.Integration | None = None) → bool Unload an entry. Returns if unload is possible and was successful. class homeassistant.config_entries.ConfigEntryState Config entry state. property recoverable Get if the state is recoverable. exception homeassistant.config_entries.ConfigError Error while configuring an account. class homeassistant.config_entries.ConfigFlow Base class for config flows with some helpers. async_abort(*, reason: str, description_placeholders: dict | None = None) → data_entry_flow.FlowResult Abort the config flow. async_create_entry(*, title: str, data: Mapping[str, Any], description: str | None = None, descrip- tion_placeholders: dict | None = None, options: Mapping[str, Any] | None = None) → data_entry_flow.FlowResult Finish config flow and create a config entry. static async_get_options_flow(config_entry: homeassistant.config_entries.ConfigEntry) → homeassistant.config_entries.OptionsFlow Get the options flow for this handler.

63 Home Assistant Documentation, Release 2021.10.0.dev0

async async_set_unique_id(unique_id: str | None = None, *, raise_on_progress: bool = True) → ConfigEntry | None Set a unique ID for the config flow. Returns optionally existing config entry with same ID. async async_step_dhcp(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by DHCP discovery. async async_step_discovery(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by discovery. async async_step_hassio(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by HASS IO discovery. async async_step_homekit(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by Homekit discovery. async async_step_ignore(user_input: dict[str, Any]) → data_entry_flow.FlowResult Ignore this config flow. async async_step_mqtt(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by MQTT discovery. async async_step_ssdp(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by SSDP discovery. async async_step_unignore(user_input: dict[str, Any]) → data_entry_flow.FlowResult Rediscover a config entry by it’s unique_id. async async_step_usb(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by USB discovery. async async_step_user(user_input: dict[str, Any] | None = None) → data_entry_flow.FlowResult Handle a flow initiated by the user. async async_step_zeroconf(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by Zeroconf discovery. property unique_id Return unique ID if available. class homeassistant.config_entries.EntityRegistryDisabledHandler(hass: homeassistant.core.HomeAssistant) Handler to handle when entities related to config entries updating disabled_by. async_setup() → None Set up the disable handler. exception homeassistant.config_entries.OperationNotAllowed Raised when a config entry operation is not allowed. class homeassistant.config_entries.OptionsFlow Base class for config option flows.

64 Chapter 4. homeassistant.config_entries Home Assistant Documentation, Release 2021.10.0.dev0 class homeassistant.config_entries.OptionsFlowManager(hass: homeassistant.core.HomeAssistant) Flow to set options for a configuration entry. async async_create_flow(handler_key: Any, *, context: dict[str, Any] | None = None, data: dict[str, Any] | None = None) → OptionsFlow Create an options flow for a config entry. Entry_id and flow.handler is the same thing to map entry with flow. async async_finish_flow(flow: homeassistant.data_entry_flow.FlowHandler, result: homeassistant.data_entry_flow.FlowResult) → homeassistant.data_entry_flow.FlowResult Finish an options flow and update options for configuration entry. Flow.handler and entry_id is the same thing to map flow with entry. exception homeassistant.config_entries.UnknownEntry Unknown entry specified. async homeassistant.config_entries.support_entry_unload(hass: homeassistant.core.HomeAssistant, domain: str) → bool Test if a domain supports entry unloading.

65 Home Assistant Documentation, Release 2021.10.0.dev0

66 Chapter 4. homeassistant.config_entries CHAPTER FIVE

HOMEASSISTANT.CORE

Core components of Home Assistant. Home Assistant is a Home Automation framework for observing the state of entities and react to changes. class homeassistant.core.Config(hass: homeassistant.core.HomeAssistant) Configuration settings for Home Assistant. as_dict() → dict Create a dictionary representation of the configuration. Async friendly. async async_load() → None Load [homeassistant] core config. async async_store() → None Store [homeassistant] core config. async async_update(**kwargs: Any) → None Update the configuration from a dictionary. distance(lat: float, lon: float) → float | None Calculate distance from Home Assistant. Async friendly. is_allowed_external_url(url: str) → bool Check if an external URL is allowed. is_allowed_path(path: str) → bool Check if the path is valid for access from outside. path(*path: str) → str Generate path to the file within the configuration directory. Async friendly. set_time_zone(time_zone_str: str) → None Help to set the time zone. class homeassistant.core.Context(user_id: str = None, parent_id: str | None = None, id: str = NOTHING) The context that triggered something. as_dict() → dict[str, str | None] Return a dictionary representation of the context. class homeassistant.core.CoreState Represent the current state of Home Assistant.

67 Home Assistant Documentation, Release 2021.10.0.dev0 class homeassistant.core.Event(event_type: str, data: dict[str, Any] | None = None, origin: EventOrigin = , time_fired: datetime.datetime | None = None, context: Context | None = None) Representation of an event within the bus. as_dict() → dict[str, Any] Create a dict representation of this Event. Async friendly. class homeassistant.core.EventBus(hass: homeassistant.core.HomeAssistant) Allow the firing of and listening for events. async_fire(event_type: str, event_data: dict[str, Any] | None = None, origin: EventOrigin = , context: Context | None = None, time_fired: datetime.datetime | None = None) → None Fire an event. This method must be run in the event loop. async_listen(event_type: str, listener: Callable, event_filter: Callable | None = None) → CALL- BACK_TYPE Listen for all events or events of a specific type. To listen to all events specify the constant MATCH_ALL as event_type. An optional event_filter, which must be a callable decorated with @callback that returns a boolean value, determines if the listener callable should run. This method must be run in the event loop. async_listen_once(event_type: str, listener: Callable) → Callable[[], None] Listen once for event of a specific type. To listen to all events specify the constant MATCH_ALL as event_type. Returns registered listener that can be used with remove_listener. This method must be run in the event loop. async_listeners() → dict[str, int] Return dictionary with events and the number of listeners. This method must be run in the event loop. fire(event_type: str, event_data: dict | None = None, origin: EventOrigin = , context: Context | None = None) → None Fire an event. listen(event_type: str, listener: Callable) → Callable[[], None] Listen for all events or events of a specific type. To listen to all events specify the constant MATCH_ALL as event_type. listen_once(event_type: str, listener: Callable[[homeassistant.core.Event], None]) → Callable[[], None] Listen once for event of a specific type. To listen to all events specify the constant MATCH_ALL as event_type. Returns function to unsubscribe the listener. property listeners Return dictionary with events and the number of listeners. class homeassistant.core.EventOrigin Represent the origin of an event.

68 Chapter 5. homeassistant.core Home Assistant Documentation, Release 2021.10.0.dev0

class homeassistant.core.HassJob(target: Callable) Represent a job to be run later. We check the callable type in advance so we can avoid checking it every time we run the job. class homeassistant.core.HassJobType Represent a job type. class homeassistant.core.HomeAssistant Root object of the Home Assistant home automation. add_job(target: Callable[[...], Any], *args: Any) → None Add job to the executor pool. target: target to call. args: parameters for method to call. async_add_executor_job(target: Callable[..., T], *args: Any) → Awaitable[T] Add an executor job from within the event loop. async_add_hass_job(hassjob: HassJob, *args: Any) → asyncio.Future | None Add a HassJob from within the event loop. This method must be run in the event loop. hassjob: HassJob to call. args: parameters for method to call. async_add_job(target: Callable[..., Any], *args: Any) → asyncio.Future | None Add a job from within the event loop. This method must be run in the event loop. target: target to call. args: parameters for method to call. async async_block_till_done() → None Block until all pending work is done. async_create_task(target: collections.abc.Awaitable) → _asyncio.Task Create a task from within the eventloop. This method must be run in the event loop. target: target to call. async async_run(*, attach_signals: bool = True) → int Home Assistant main entry point. Start Home Assistant and block until stopped. This method is a coroutine. async_run_hass_job(hassjob: HassJob, *args: Any) → asyncio.Future | None Run a HassJob from within the event loop. This method must be run in the event loop. hassjob: HassJob args: parameters for method to call. async_run_job(target: Callable[..., None | Awaitable], *args: Any) → asyncio.Future | None Run a job from within the event loop. This method must be run in the event loop. target: target to call. args: parameters for method to call. async async_start() → None Finalize startup from inside the event loop. This method is a coroutine.

69 Home Assistant Documentation, Release 2021.10.0.dev0

async async_stop(exit_code: int = 0, *, force: bool = False) → None Stop Home Assistant and shuts down all threads. The “force” flag commands async_stop to proceed regardless of Home Assistant’s current state. You should not set this flag unless you’re testing. This method is a coroutine. async_stop_track_tasks() → None Stop track tasks so you can’t wait for all tasks to be done. async_track_tasks() → None Track tasks so you can wait for all tasks to be done. block_till_done() → None Block until all pending work is done. create_task(target: collections.abc.Awaitable) → None Add task to the executor pool. target: target to call. property is_running Return if Home Assistant is running. property is_stopping Return if Home Assistant is stopping. start() → int Start Home Assistant. Note: This function is only used for testing. For regular use, use “await hass.run()”. stop() → None Stop Home Assistant and shuts down all threads. class homeassistant.core.Service(func: Callable, schema: vol.Schema | None, context: Context | None = None) Representation of a callable service. class homeassistant.core.ServiceCall(domain: str, service: str, data: dict | None = None, context: Context | None = None) Representation of a call to a service. class homeassistant.core.ServiceRegistry(hass: homeassistant.core.HomeAssistant) Offer the services over the eventbus. async async_call(domain: str, service: str, service_data: dict | None = None, blocking: bool = False, context: Context | None = None, limit: float | None = 10, target: dict | None = None) → bool | None Call a service. Specify blocking=True to wait until service is executed. Waits a maximum of limit, which may be None for no timeout. If blocking = True, will return boolean if service executed successfully within limit. This method will fire an event to indicate the service has been called. Because the service is sent as an event you are not allowed to use the keys ATTR_DOMAIN and ATTR_SERVICE in your service_data. This method is a coroutine.

70 Chapter 5. homeassistant.core Home Assistant Documentation, Release 2021.10.0.dev0

async_register(domain: str, service: str, service_func: Callable, schema: vol.Schema | None = None) → None Register a service. Schema is called to coerce and validate the service data. This method must be run in the event loop. async_remove(domain: str, service: str) → None Remove a registered service from service handler. This method must be run in the event loop. async_services() → dict[str, dict[str, Service]] Return dictionary with per domain a list of available services. This method must be run in the event loop. call(domain: str, service: str, service_data: dict | None = None, blocking: bool = False, context: Context | None = None, limit: ﬂoat | None = 10, target: dict | None = None) → bool | None Call a service. See description of async_call for details. has_service(domain: str, service: str) → bool Test if speciﬁed service exists. Async friendly. register(domain: str, service: str, service_func: Callable, schema: vol.Schema | None = None) → None Register a service. Schema is called to coerce and validate the service data. remove(domain: str, service: str) → None Remove a registered service from service handler. property services Return dictionary with per domain a list of available services. class homeassistant.core.State(entity_id: str, state: str, attributes: Mapping[str, Any] | None = None, last_changed: datetime.datetime | None = None, last_updated: datetime.datetime | None = None, context: Con- text | None = None, validate_entity_id: bool | None = True) Object to represent a state within the state machine. entity_id: the entity that is represented. state: the state of the entity attributes: extra information on entity and state last_changed: last time the state was changed, not the attributes. last_updated: last time this object was updated. context: Context in which it was created domain: Domain of this state. object_id: Object id of this state. as_dict() → dict Return a dict representation of the State. Async friendly. To be used for JSON serialization. Ensures: state == State.from_dict(state.as_dict()) classmethod from_dict(json_dict: dict) → Any Initialize a state from a dict. Async friendly. Ensures: state == State.from_json_dict(state.to_json_dict())

71 Home Assistant Documentation, Release 2021.10.0.dev0

property name Name of this state. class homeassistant.core.StateMachine(bus: homeassistant.core.EventBus, loop: asyncio.events.AbstractEventLoop) Helper class that tracks the state of different entities. all(domain_filter: str | Iterable | None = None) → list[State] Create a list of all states. async_all(domain_filter: str | Iterable | None = None) → list[State] Create a list of all states matching the filter. This method must be run in the event loop. async_available(entity_id: str) → bool Check to see if an entity_id is available to be used. async_entity_ids(domain_filter: str | Iterable | None = None) → list[str] List of entity ids that are being tracked. This method must be run in the event loop. async_entity_ids_count(domain_filter: str | Iterable | None = None) → int Count the entity ids that are being tracked. This method must be run in the event loop. async_remove(entity_id: str, context: Context | None = None) → bool Remove the state of an entity. Returns boolean to indicate if an entity was removed. This method must be run in the event loop. async_reserve(entity_id: str) → None Reserve a state in the state machine for an entity being added. This must not fire an event when the state is reserved. This avoids a race condition where multiple entities with the same entity_id are added. async_set(entity_id: str, new_state: str, attributes: Mapping[str, Any] | None = None, force_update: bool = False, context: Context | None = None) → None Set the state of an entity, add entity if it does not exist. Attributes is an optional dict to specify attributes of this state. If you just update the attributes and not the state, last changed will not be affected. This method must be run in the event loop. entity_ids(domain_filter: str | None = None) → list[str] List of entity ids that are being tracked. get(entity_id: str) → State | None Retrieve state of entity_id or None if not found. Async friendly. is_state(entity_id: str, state: str) → bool Test if entity exists and is in specified state. Async friendly.

72 Chapter 5. homeassistant.core Home Assistant Documentation, Release 2021.10.0.dev0

remove(entity_id: str) → bool Remove the state of an entity. Returns boolean to indicate if an entity was removed. set(entity_id: str, new_state: str, attributes: Mapping[str, Any] | None = None, force_update: bool = False, context: Context | None = None) → None Set the state of an entity, add entity if it does not exist. Attributes is an optional dict to specify attributes of this state. If you just update the attributes and not the state, last changed will not be affected. homeassistant.core.callback(func: CALLABLE_T) → CALLABLE_T Annotation to mark method as safe to call from within the event loop. homeassistant.core.is_callback(func: Callable[[...], Any]) → bool Check if function is safe to be called in the event loop. homeassistant.core.split_entity_id(entity_id: str) → list[str] Split a state entity ID into domain and object ID. homeassistant.core.valid_entity_id(entity_id: str) → bool Test if an entity ID is a valid format. Format: . where both are slugs. homeassistant.core.valid_state(state: str) → bool Test if a state is valid.

73 Home Assistant Documentation, Release 2021.10.0.dev0

74 Chapter 5. homeassistant.core CHAPTER SIX

HOMEASSISTANT.DATA_ENTRY_FLOW

Classes to help gather user submissions. exception homeassistant.data_entry_flow.AbortFlow(reason: str, descrip- tion_placeholders: dict | None = None) Exception to indicate a flow needs to be aborted. exception homeassistant.data_entry_flow.FlowError Error while configuring an account. class homeassistant.data_entry_flow.FlowHandler Handle the configuration flow of a component. async_abort(*, reason: str, description_placeholders: dict | None = None) → FlowResult Abort the config flow. async_create_entry(*, title: str, data: Mapping[str, Any], description: str | None = None, descrip- tion_placeholders: dict | None = None) → FlowResult Finish config flow and create a config entry. async_external_step(*, step_id: str, url: str, description_placeholders: dict | None = None) → FlowResult Return the definition of an external step for the user to take. async_external_step_done(*, next_step_id: str) → homeassistant.data_entry_flow.FlowResult Return the definition of an external step for the user to take. async_show_form(*, step_id: str, data_schema: vol.Schema = None, errors: dict[str, str] | None = None, description_placeholders: dict[str, Any] | None = None, last_step: bool | None = None) → FlowResult Return the definition of a form to gather user input. async_show_progress(*, step_id: str, progress_action: str, description_placeholders: dict | None = None) → FlowResult Show a progress message to the user, without user input allowed. async_show_progress_done(*, next_step_id: str) → homeassistant.data_entry_flow.FlowResult Mark the progress done. property show_advanced_options If we should show advanced options. property source Source that initialized the flow. class homeassistant.data_entry_flow.FlowManager(hass: homeassistant.core.HomeAssistant) Manage all the flows that are in progress.

75 Home Assistant Documentation, Release 2021.10.0.dev0

async_abort(flow_id: str) → None Abort a flow. async async_configure(flow_id: str, user_input: dict | None = None) → FlowResult Continue a configuration flow. abstract async async_create_flow(handler_key: Any, *, context: dict[str, Any] | None = None, data: dict[str, Any] | None = None) → FlowHan- dler Create a flow for specified handler. Handler key is the domain of the component that we want to set up. abstract async async_finish_flow(flow: homeassistant.data_entry_flow.FlowHandler, result: homeassistant.data_entry_flow.FlowResult) → homeassistant.data_entry_flow.FlowResult Finish a config flow and add an entry. async async_init(handler: str, *, context: dict[str, Any] | None = None, data: Any = None) → FlowResult Start a configuration flow. async async_post_init(flow: homeassistant.data_entry_flow.FlowHandler, result: homeassistant.data_entry_flow.FlowResult) → None Entry has finished executing its first step asynchronously. async_progress(include_uninitialized: bool = False) → list[FlowResult] Return the flows in progress. async async_shutdown() → None Cancel any initializing flows. async async_wait_init_flow_finish(handler: str) → None Wait till all flows in progress are initialized. class homeassistant.data_entry_flow.FlowResult Typed result dict. exception homeassistant.data_entry_flow.UnknownFlow Unknown flow specified. exception homeassistant.data_entry_flow.UnknownHandler Unknown handler specified. exception homeassistant.data_entry_flow.UnknownStep Unknown step specified.

76 Chapter 6. homeassistant.data_entry_flow CHAPTER SEVEN

HOMEASSISTANT.EXCEPTIONS

The exceptions used by Home Assistant. exception homeassistant.exceptions.ConditionError(type: str) Error during condition evaluation. output(indent: int) → Generator[str, None, None] Yield an indented representation. exception homeassistant.exceptions.ConditionErrorContainer(type: str, errors: Se- quence[ConditionError]) Condition error with subconditions. output(indent: int) → Generator[str, None, None] Yield an indented representation. exception homeassistant.exceptions.ConditionErrorIndex(type: str, index: int, total: int, error: homeassistant.exceptions.ConditionError) Condition error with index. output(indent: int) → Generator[str, None, None] Yield an indented representation. exception homeassistant.exceptions.ConditionErrorMessage(type: str, message: str) Condition error message. output(indent: int) → Generator[str, None, None] Yield an indented representation. exception homeassistant.exceptions.ConfigEntryAuthFailed Error to indicate that config entry could not authenticate. exception homeassistant.exceptions.ConfigEntryNotReady Error to indicate that config entry is not ready. exception homeassistant.exceptions.HomeAssistantError General Home Assistant exception occurred. exception homeassistant.exceptions.IntegrationError Base class for platform and config entry exceptions. exception homeassistant.exceptions.InvalidEntityFormatError When an invalid formatted entity is encountered. exception homeassistant.exceptions.InvalidStateError When an invalid state is encountered.

77 Home Assistant Documentation, Release 2021.10.0.dev0 exception homeassistant.exceptions.MaxLengthExceeded(value: str, property_name: str, max_length: int) Raised when a property value has exceeded the max character length. exception homeassistant.exceptions.NoEntitySpecifiedError When no entity is specified. exception homeassistant.exceptions.PlatformNotReady Error to indicate that platform is not ready. exception homeassistant.exceptions.RequiredParameterMissing(parameter_names: list[str]) Raised when a required parameter is missing from a function call. exception homeassistant.exceptions.ServiceNotFound(domain: str, service: str) Raised when a service is not found. exception homeassistant.exceptions.TemplateError(exception: Exception) Error during template rendering. exception homeassistant.exceptions.Unauthorized(context: Context | None = None, user_id: str | None = None, entity_id: str | None = None, config_entry_id: str | None = None, perm_category: str | None = None, permission: str | None = None) When an action is unauthorized. exception homeassistant.exceptions.UnknownUser(context: Context | None = None, user_id: str | None = None, entity_id: str | None = None, config_entry_id: str | None = None, perm_category: str | None = None, permission: str | None = None) When call is made with user ID that doesn’t exist.

78 Chapter 7. homeassistant.exceptions CHAPTER EIGHT

HOMEASSISTANT.HELPERS

Helper methods for components within Home Assistant. homeassistant.helpers.config_per_platform(config: ConfigType, domain: str) → Iter- able[tuple[Any, Any]] Break a component config into different platforms. For example, will find ‘switch’, ‘switch 2’, ‘switch 3’, .. etc Async friendly. homeassistant.helpers.extract_domain_configs(config: ConfigType, domain: str) → Se- quence[str] Extract keys from config for given domain name. Async friendly.

8.1 homeassistant.helpers.aiohttp_client

Helper for aiohttp webclient stuff. async homeassistant.helpers.aiohttp_client.async_aiohttp_proxy_stream(hass: Home- Assis- tant, request: web.BaseRequest, stream: aiohttp.StreamReader, con- tent_type: str | None, buffer_size: int = 102400, timeout: int = 10) → web.StreamResponse Stream a stream to aiohttp web response.

79 Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.helpers.aiohttp_client.async_aiohttp_proxy_web(hass: HomeAs- sistant, request: web.BaseRequest, web_coro: Await- able[aiohttp.ClientResponse], buffer_size: int = 102400, timeout: int = 10) → web.StreamResponse | None Stream websession request to aiohttp web response. homeassistant.helpers.aiohttp_client.async_create_clientsession(hass: homeassistant.core.HomeAssistant, verify_ssl: bool = True, auto_cleanup: bool = True, **kwargs: Any) → aiohttp.client.ClientSession Create a new ClientSession with kwargs, i.e. for cookies. If auto_cleanup is False, you need to call detach() after the session returned is no longer used. Default is True, the session will be automatically detached on homeassistant_stop or when being created in conﬁg entry setup, the conﬁg entry is unloaded. This method must be run in the event loop. homeassistant.helpers.aiohttp_client.async_get_clientsession(hass: homeassistant.core.HomeAssistant, verify_ssl: bool = True) → aiohttp.client.ClientSession Return default aiohttp ClientSession. This method must be run in the event loop.

8.2 homeassistant.helpers.area_registry

Provide a way to connect devices to one physical location. class homeassistant.helpers.area_registry.AreaEntry(name: str, normalized_name: str, id: str | None = None) Bases: object Area Registry Entry. generate_id(existing_ids: Container[str]) → None Initialize ID.

80 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

id name normalized_name class homeassistant.helpers.area_registry.AreaRegistry(hass: homeassistant.core.HomeAssistant) Bases: object Class to hold a registry of areas. async_create(name: str) → homeassistant.helpers.area_registry.AreaEntry Create a new area. async_delete(area_id: str) → None Delete area. async_get_area(area_id: str) → AreaEntry | None Get area by id. async_get_area_by_name(name: str) → AreaEntry | None Get area by name. async_get_or_create(name: str) → homeassistant.helpers.area_registry.AreaEntry Get or create an area. async_list_areas() → Iterable[AreaEntry] Get all areas. async async_load() → None Load the area registry. async_schedule_save() → None Schedule saving the area registry. async_update(area_id: str, name: str) → homeassistant.helpers.area_registry.AreaEntry Update name of area. homeassistant.helpers.area_registry.async_get(hass: homeassistant.core.HomeAssistant) → homeassistant.helpers.area_registry.AreaRegistry Get area registry. async homeassistant.helpers.area_registry.async_get_registry(hass: homeassistant.core.HomeAssistant) → homeassistant.helpers.area_registry.AreaRegistry Get area registry. This is deprecated and will be removed in the future. Use async_get instead. async homeassistant.helpers.area_registry.async_load(hass: homeassistant.core.HomeAssistant) → None Load area registry. homeassistant.helpers.area_registry.normalize_area_name(area_name: str) → str Normalize an area name by removing whitespace and case folding.

8.2. homeassistant.helpers.area_registry 81 Home Assistant Documentation, Release 2021.10.0.dev0

8.3 homeassistant.helpers.check_conﬁg

Helper to check the configuration file. class homeassistant.helpers.check_config.CheckConfigError Bases: tuple Configuration check error. config Alias for field number 2 domain Alias for field number 1 message Alias for field number 0 class homeassistant.helpers.check_config.HomeAssistantConfig Bases: collections.OrderedDict Configuration result with errors attribute. add_error(message: str, domain: str | None = None, config: ConfigType | None = None) → Home- AssistantConfig Add a single error. property error_str Return errors as a string. async homeassistant.helpers.check_config.async_check_ha_config_file(hass: homeassis- tant.core.HomeAssistant) → homeassis- tant.helpers.check_config.HomeAssistantConfig Load and check if Home Assistant configuration file is valid. This method is a coroutine.

8.4 homeassistant.helpers.collection

Helper to deal with YAML + storage. class homeassistant.helpers.collection.CollectionChangeSet(change_type: str, item_id: str, item: Any) Bases: object Class to represent a change set. change_type: One of CHANGE_* item_id: The id of the item item: The item change_type: str = None item: Any = None item_id: str = None

82 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

exception homeassistant.helpers.collection.CollectionError Bases: homeassistant.exceptions.HomeAssistantError Base class for collection related errors. class homeassistant.helpers.collection.IDLessCollection(logger: logging.Logger, id_manager: IDManager | None = None) Bases: homeassistant.helpers.collection.ObservableCollection A collection without IDs. async async_load(data: list[dict]) → None Load the collection. Overrides existing data. counter = 0 class homeassistant.helpers.collection.IDManager Bases: object Keep track of IDs across different collections. add_collection(collection: dict[str, Any]) → None Add a collection to check for ID usage. generate_id(suggestion: str) → str Generate an ID. has_id(item_id: str) → bool Test if the ID exists. exception homeassistant.helpers.collection.ItemNotFound(item_id: str) Bases: homeassistant.helpers.collection.CollectionError Raised when an item is not found. class homeassistant.helpers.collection.ObservableCollection(logger: logging.Logger, id_manager: ID- Manager | None = None) Bases: abc.ABC Base collection type that can be observed. async_add_change_set_listener(listener: Callable[[Iterable[homeassistant.helpers.collection.CollectionChangeSet]], Awaitable[None]]) → None Add a listener for a full change set. Will be called with [(change_type, item_id, updated_conﬁg), . . . ] async_add_listener(listener: Callable[[str, str, dict], Awaitable[None]]) → None Add a listener. Will be called with (change_type, item_id, updated_conﬁg). async_items() → list[dict] Return list of items in collection. async notify_changes(change_sets: Iterable[homeassistant.helpers.collection.CollectionChangeSet]) → None Notify listeners of a change.

8.4. homeassistant.helpers.collection 83 Home Assistant Documentation, Release 2021.10.0.dev0 class homeassistant.helpers.collection.StorageCollection(store: Store, logger: logging.Logger, id_manager: IDManager | None = None) Bases: homeassistant.helpers.collection.ObservableCollection Offer a CRUD interface on top of JSON storage. async async_create_item(data: dict) → dict Create a new item. async async_delete_item(item_id: str) → None Delete item. async async_load() → None Load the storage Manager. async async_update_item(item_id: str, updates: dict) → dict Update item. property hass Home Assistant object. class homeassistant.helpers.collection.StorageCollectionWebsocket(storage_collection: homeassistant.helpers.collection.StorageCollection, api_preﬁx: str, model_name: str, cre- ate_schema: dict, up- date_schema: dict) Bases: object Class to expose storage collection management over websocket. async_setup(hass: homeassistant.core.HomeAssistant, *, create_list: bool = True, create_create: bool = True) → None Set up the websocket commands. property item_id_key Return item ID key. async ws_create_item(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None Create a item. async ws_delete_item(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None Delete a item. ws_list_item(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None List items. async ws_update_item(hass: homeassistant.core.HomeAssistant, connection: homeassistant.components.websocket_api.connection.ActiveConnection, msg: dict) → None Update a item.

84 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0 class homeassistant.helpers.collection.YamlCollection(logger: logging.Logger, id_manager: IDManager | None = None) Bases: homeassistant.helpers.collection.ObservableCollection Offer a collection based on static data. async async_load(data: list[dict]) → None Load the YAML collection. Overrides existing data. homeassistant.helpers.collection.sync_entity_lifecycle(hass: homeassistant.core.HomeAssistant, domain: str, platform: str, en- tity_component: homeassistant.helpers.entity_component.EntityComponent, collection: homeassistant.helpers.collection.ObservableCollection, create_entity: Callable[[dict], homeassistant.helpers.entity.Entity]) → None Map a collection to an entity component.

8.5 homeassistant.helpers.condition

Offer reusable conditions. async homeassistant.helpers.condition.async_and_from_config(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Op- tional[Mapping[str, Any]]], bool] Create multi condition matcher using ‘AND’. async homeassistant.helpers.condition.async_device_from_config(hass: homeassis- tant.core.HomeAssistant, config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Op- tional[Mapping[str, Any]]], bool] Test a device condition. homeassistant.helpers.condition.async_extract_devices(config: ConfigType | Tem- plate) → set[str] Extract devices from a condition.

8.5. homeassistant.helpers.condition 85 Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.condition.async_extract_entities(config: ConfigType | Tem- plate) → set[str] Extract entities from a condition. async homeassistant.helpers.condition.async_from_config(hass: HomeAssistant, config: ConfigType | Template, config_validation: bool = True) → ConditionCheck- erType Turn a condition configuration into a method. Should be run on the event loop. async homeassistant.helpers.condition.async_not_from_config(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Op- tional[Mapping[str, Any]]], bool] Create multi condition matcher using ‘NOT’. homeassistant.helpers.condition.async_numeric_state(hass: HomeAssistant, entity: None | str | State, below: float | str | None = None, above: float | str | None = None, value_template: Template | None = None, variables: Template- VarsType = None, attribute: str | None = None) → bool Test a numeric state condition. homeassistant.helpers.condition.async_numeric_state_from_config(config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Op- tional[Mapping[str, Any]]], bool] Wrap action method with state based condition. async homeassistant.helpers.condition.async_or_from_config(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any], config_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool] Create multi condition matcher using ‘OR’.

86 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.condition.async_template(hass: homeassistant.core.HomeAssistant, value_template: homeassistant.helpers.template.Template, variables: Optional[Mapping[str, Any]] = None, trace_result: bool = True) → bool Test if template condition matches. homeassistant.helpers.condition.async_template_from_config(config: Dict[str, Any], config_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool] Wrap action method with state based condition. async homeassistant.helpers.condition.async_trigger_from_config(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Op- tional[Mapping[str, Any]]], bool] Test a trigger condition. async homeassistant.helpers.condition.async_validate_condition_config(hass: Home- Assis- tant, config: Con- fig- Type | Tem- plate) → Con- fig- Type | Tem- plate Validate config. homeassistant.helpers.condition.condition_trace_append(variables: Op- tional[Mapping[str, Any]], path: str) → homeassistant.helpers.trace.TraceElement Append a TraceElement to trace[path].

8.5. homeassistant.helpers.condition 87 Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.condition.condition_trace_set_result(result: bool, **kwargs: Any) → None Set the result of TraceElement at the top of the stack. homeassistant.helpers.condition.condition_trace_update_result(**kwargs: Any) → None Update the result of TraceElement at the top of the stack. homeassistant.helpers.condition.numeric_state(hass: HomeAssistant, entity: None | str | State, below: float | str | None = None, above: float | str | None = None, value_template: Template | None = None, variables: TemplateVarsType = None) → bool Test a numeric state condition. homeassistant.helpers.condition.state(hass: HomeAssistant, entity: None | str | State, req_state: Any, for_period: timedelta | None = None, attribute: str | None = None) → bool Test if state matches requirements. Async friendly. homeassistant.helpers.condition.state_from_config(config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool] Wrap action method with state based condition. homeassistant.helpers.condition.sun(hass: HomeAssistant, before: str | None = None, after: str | None = None, before_offset: timedelta | None = None, after_offset: timedelta | None = None) → bool Test if current time matches sun requirements. homeassistant.helpers.condition.sun_from_config(config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool] Wrap action method with sun based condition. homeassistant.helpers.condition.template(hass: homeassistant.core.HomeAssistant, value_template: homeassistant.helpers.template.Template, variables: Optional[Mapping[str, Any]] = None) → bool Test if template condition matches. homeassistant.helpers.condition.time(hass: HomeAssistant, before: dt_util.dt.time | str | None = None, after: dt_util.dt.time | str | None = None, week- day: None | str | Container[str] = None) → bool Test if local time condition matches. Handle the fact that time is continuous and we may be testing for a period that crosses midnight. In that case it is easier to test for the opposite. “(23:59 <= now < 00:01)” would be the same as “not (00:01 <= now < 23:59)”. homeassistant.helpers.condition.time_from_config(config: Dict[str, Any], con- fig_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool] Wrap action method with time based condition.

88 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.condition.trace_condition(variables: TemplateVarsType) → Gen- erator[TraceElement, None, None] Trace condition evaluation. homeassistant.helpers.condition.trace_condition_function(condition: Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool]) → Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool] Wrap a condition function to enable basic tracing. homeassistant.helpers.condition.zone(hass: HomeAssistant, zone_ent: None | str | State, entity: None | str | State) → bool Test if zone-condition matches. Async friendly. homeassistant.helpers.condition.zone_from_config(conﬁg: Dict[str, Any], con- ﬁg_validation: bool = True) → Callable[[homeassistant.core.HomeAssistant, Optional[Mapping[str, Any]]], bool] Wrap action method with zone based condition.

8.6 homeassistant.helpers.conﬁg_entry_ﬂow

Helpers for data entry flows for config entries. class homeassistant.helpers.config_entry_flow.DiscoveryFlowHandler(domain: str, title: str, discov- ery_function: Callable[[homeassistant.core.HomeAssistant], Union[Awaitable[bool], bool]]) Bases: homeassistant.config_entries.ConfigFlow Handle a discovery config flow. VERSION = 1 async async_step_confirm(user_input: dict[str, Any] | None = None) → FlowResult Confirm setup. async async_step_dhcp(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by discovery. async async_step_discovery(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by discovery. async async_step_homekit(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by discovery. async async_step_import(_: dict[str, Any] | None) → FlowResult Handle a flow initialized by import.

8.6. homeassistant.helpers.conﬁg_entry_ﬂow 89 Home Assistant Documentation, Release 2021.10.0.dev0

async async_step_mqtt(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by discovery. async async_step_ssdp(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by discovery. async async_step_user(user_input: dict[str, Any] | None = None) → FlowResult Handle a flow initialized by the user. async async_step_zeroconf(discovery_info: Dict[str, Any]) → homeassistant.data_entry_flow.FlowResult Handle a flow initialized by discovery. class homeassistant.helpers.config_entry_flow.WebhookFlowHandler(domain: str, title: str, descrip- tion_placeholder: dict, al- low_multiple: bool) Bases: homeassistant.config_entries.ConfigFlow Handle a webhook config flow. VERSION = 1 async async_step_user(user_input: dict[str, Any] | None = None) → FlowResult Handle a user initiated set up flow to create a webhook. homeassistant.helpers.config_entry_flow.register_discovery_flow(domain: str, title: str, discov- ery_function: Discovery- FunctionType, connec- tion_class: str | Unde- finedType = ) → None Register flow for discovered integrations that not require auth. homeassistant.helpers.config_entry_flow.register_webhook_flow(domain: str, title: str, descrip- tion_placeholder: dict, al- low_multiple: bool = False) → None Register flow for webhook integrations.

90 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0 async homeassistant.helpers.config_entry_flow.webhook_async_remove_entry(hass: homeas- sistant.core.HomeAssistant, entry: homeas- sistant.config_entries.ConfigEntry) → None Remove a webhook config entry.

8.7 homeassistant.helpers.conﬁg_entry_oauth2_ﬂow

Config Flow using OAuth2. This module exists of the following parts: • OAuth2 config flow which supports multiple OAuth2 implementations • OAuth2 implementation that works with local provided client ID/secret class homeassistant.helpers.config_entry_oauth2_flow.AbstractOAuth2FlowHandler Bases: homeassistant.config_entries.ConfigFlow Handle a config flow. DOMAIN = '' VERSION = 1 async async_oauth_create_entry(data: dict) → homeassistant.data_entry_flow.FlowResult Create an entry for the flow. Ok to override if you want to fetch extra info or even add another step. classmethod async_register_implementation(hass: homeassistant.core.HomeAssistant, local_impl: homeassistant.helpers.config_entry_oauth2_flow.LocalOAuth2Implementation) → None Register a local implementation. async async_step_auth(user_input: dict[str, Any] | None = None) → FlowResult Create an entry for auth. async async_step_creation(user_input: dict[str, Any] | None = None) → FlowResult Create config entry from external data. async async_step_pick_implementation(user_input: dict | None = None) → FlowResult Handle a flow start. async async_step_user(user_input: dict[str, Any] | None = None) → FlowResult Handle a flow start. property extra_authorize_data Extra data that needs to be appended to the authorize url.

8.7. homeassistant.helpers.conﬁg_entry_oauth2_ﬂow 91 Home Assistant Documentation, Release 2021.10.0.dev0

abstract property logger Return logger. class homeassistant.helpers.config_entry_oauth2_flow.AbstractOAuth2Implementation Bases: abc.ABC Base class to abstract OAuth2 authentication. abstract async async_generate_authorize_url(flow_id: str) → str Generate a url for the user to authorize. This step is called when a config flow is initialized. It should redirect the user to the vendor website where they can authorize Home Assistant. The implementation is responsible to get notified when the user is authorized and pass this to the specified config flow. Do as little work as possible once notified. You can do the work inside async_resolve_external_data. This will give the best UX. Pass external data in with: await hass.config_entries.flow.async_configure( flow_id=flow_id, user_input={‘code’: ‘abcd’, ‘state’: {...} ) async async_refresh_token(token: dict) → dict Refresh a token and update expires info. abstract async async_resolve_external_data(external_data: Any) → dict Resolve external data to tokens. Turn the data that the implementation passed to the config flow as external step data into tokens. These tokens will be stored as ‘token’ in the config entry data. abstract property domain Domain that is providing the implementation. abstract property name Name of the implementation. class homeassistant.helpers.config_entry_oauth2_flow.LocalOAuth2Implementation(hass: homeas- sistant.core.HomeAssistant, domain: str, client_id: str, client_secret: str, au- tho- rize_url: str, to- ken_url: str) Bases: homeassistant.helpers.config_entry_oauth2_flow. AbstractOAuth2Implementation

92 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

Local OAuth2 implementation. async async_generate_authorize_url(flow_id: str) → str Generate a url for the user to authorize. async async_resolve_external_data(external_data: Any) → dict Resolve the authorization code to tokens. property domain Domain providing the implementation. property extra_authorize_data Extra data that needs to be appended to the authorize url. property name Name of the implementation. property redirect_uri Return the redirect uri. class homeassistant.helpers.config_entry_oauth2_flow.OAuth2AuthorizeCallbackView Bases: homeassistant.components.http.view.HomeAssistantView OAuth2 Authorization Callback View. async get(request: aiohttp.web_request.Request) → aiohttp.web_response.Response Receive authorization code. name = 'auth:external:callback' requires_auth = False url: str | None = '/auth/external/callback' class homeassistant.helpers.config_entry_oauth2_flow.OAuth2Session(hass: homeassis- tant.core.HomeAssistant, con- fig_entry: homeassis- tant.config_entries.ConfigEntry, implementation: homeassis- tant.helpers.config_entry_oauth2_flow.AbstractOAuth2Implementation) Bases: object Session to make requests authenticated with OAuth2. async async_ensure_token_valid() → None Ensure that the current token is valid. async async_request(method: str, url: str, **kwargs: Any) → aiohttp.client_reqrep.ClientResponse Make a request. property token Return the token.

8.7. homeassistant.helpers.conﬁg_entry_oauth2_ﬂow 93 Home Assistant Documentation, Release 2021.10.0.dev0

property valid_token Return if token is still valid. homeassistant.helpers.config_entry_oauth2_flow.async_add_implementation_provider(hass: Home- As- sistant, provider_domain: str, async_provide_implementation: Callable[[HomeAssistant, str], Await- able[AbstractOAuth2Implementation | None]]) → None Add an implementation provider. If no implementation found, return None. async homeassistant.helpers.config_entry_oauth2_flow.async_get_config_entry_implementation(hass: homeas- sistant.core.HomeAssistant, con- fig_entry: homeas- sistant.config_entries.ConfigEntry) → homeas- sistant.helpers.config_entry_oauth2_flow.AbstractOAuth2Implementation Return the implementation for this config entry. async homeassistant.helpers.config_entry_oauth2_flow.async_get_implementations(hass: Home- As- sistant, domain: str) → dict[str, Ab- strac- tOAuth2Implementation] Return OAuth2 implementations for specified domain.

94 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.helpers.config_entry_oauth2_flow.async_oauth2_request(hass: homeas- sistant.core.HomeAssistant, token: dict, method: str, url: str, **kwargs: Any) → aiohttp.client_reqrep.ClientResponse Make an OAuth2 authenticated request. This method will not refresh tokens. Use OAuth2 session for that. homeassistant.helpers.config_entry_oauth2_flow.async_register_implementation(hass: homeas- sistant.core.HomeAssistant, domain: str, im- ple- men- ta- tion: homeas- sistant.helpers.config_entry_oauth2_flow.AbstractOAuth2Implementation) → None Register an OAuth2 flow implementation for an integration.

8.8 homeassistant.helpers.conﬁg_validation

Helpers for conﬁg validation using voluptuous. homeassistant.helpers.config_validation.STATE_CONDITION_SCHEMA(value: Any) → dict Validate a state condition. homeassistant.helpers.config_validation.boolean(value: Any) → bool Validate and coerce a boolean value. homeassistant.helpers.config_validation.custom_serializer(schema: Any) → Any Serialize additional types for voluptuous_serialize.

8.8. homeassistant.helpers.conﬁg_validation 95 Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.config_validation.date(value: Any) → datetime.date Validate and transform a date. homeassistant.helpers.config_validation.datetime(value: Any) → datetime.datetime Validate datetime. homeassistant.helpers.config_validation.deprecated(key: str, replacement_key: str | None = None, default: Any | None = None) → Callable[[dict], dict] Log key as deprecated and provide a replacement (if exists). Expected behavior: • Outputs the appropriate deprecation warning if key is detected • Processes schema moving the value from key to replacement_key • Processes schema changing nothing if only replacement_key provided • No warning if only replacement_key provided • No warning if neither key nor replacement_key are provided – Adds replacement_key with default value in this case homeassistant.helpers.config_validation.determine_script_action(action: dict[str, Any]) → str Determine action type. homeassistant.helpers.config_validation.dynamic_template(value: Any | None) → tem- plate_helper.Template Validate a dynamic (non static) jinja2 template. homeassistant.helpers.config_validation.ensure_list(value: T | list[T] | None) → list[T] Wrap value in list if it is not one. homeassistant.helpers.config_validation.ensure_list_csv(value: Any) → list Ensure that input is a list or make one from comma-separated string. homeassistant.helpers.config_validation.entities_domain(domain: str | list[str]) → Callable[[str | list], list[str]] Validate that entities belong to domain. homeassistant.helpers.config_validation.entity_domain(domain: str | list[str]) → Callable[[Any], str] Validate that entity belong to domain. homeassistant.helpers.config_validation.entity_id(value: Any) → str Validate Entity ID. homeassistant.helpers.config_validation.entity_ids(value: str | list) → list[str] Validate Entity IDs. homeassistant.helpers.config_validation.enum(enumClass: type[Enum]) → vol.All Create validator for speciﬁed enum. homeassistant.helpers.config_validation.has_at_least_one_key(*keys: Any) → Callable[[dict], dict] Validate that at least one key exists.

96 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.config_validation.has_at_most_one_key(*keys: Any) → Callable[[dict], dict] Validate that zero keys exist or one key exists. homeassistant.helpers.config_validation.icon(value: Any) → str Validate icon. homeassistant.helpers.config_validation.is_regex(value: Any) → re.Pattern[Any] Validate that a string is a valid regular expression. homeassistant.helpers.config_validation.isdevice(value: Any) → str Validate that value is a real device. homeassistant.helpers.config_validation.isdir(value: Any) → str Validate that the value is an existing dir. homeassistant.helpers.config_validation.isfile(value: Any) → str Validate that the value is an existing ﬁle. homeassistant.helpers.config_validation.key_dependency(key: Hashable, dependency: Hashable) → Callable[[dict[Hashable, Any]], dict[Hashable, Any]] Validate that all dependencies exist for key. homeassistant.helpers.config_validation.key_value_schemas(key: str, value_schemas: dict[Hashable, vol.Schema]) → Callable[[Any], dict[Hashable, Any]] Create a validator that validates based on a value for speciﬁc key. This gives better error messages. homeassistant.helpers.config_validation.make_entity_service_schema(schema: dict, *, extra: int = 0) → voluptuous.schema_builder.Schema Create an entity service schema. homeassistant.helpers.config_validation.match_all(value: T) → T Validate that matches all values. homeassistant.helpers.config_validation.matches_regex(regex: str) → Callable[[Any], str] Validate that the value is a string that matches a regex. class homeassistant.helpers.config_validation.multi_select(options: dict) Bases: object Multi select validator returning list of selected values. homeassistant.helpers.config_validation.path(value: Any) → str Validate it’s a safe path. homeassistant.helpers.config_validation.positive_timedelta(value: datetime.timedelta) → datetime.timedelta Validate timedelta is positive.

8.8. homeassistant.helpers.conﬁg_validation 97 Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.config_validation.remove_falsy(value: list[T]) → list[T] Remove falsy values from a list. homeassistant.helpers.config_validation.schema_with_slug_keys(value_schema: T | Callable, *, slug_validator: Callable[[Any], str] = ) → Callable Ensure dicts have slugs as keys. Replacement of vol.Schema({cv.slug: value_schema}) to prevent misleading “Extra keys” errors from voluptuous. homeassistant.helpers.config_validation.script_action(value: Any) → dict Validate a script action. homeassistant.helpers.config_validation.service(value: Any) → str Validate service. homeassistant.helpers.config_validation.slug(value: Any) → str Validate value is a valid slug. homeassistant.helpers.config_validation.slugify(value: Any) → str Coerce a value to a slug. homeassistant.helpers.config_validation.socket_timeout(value: Any | None) → object Validate timeout ﬂoat > 0.0. None coerced to socket._GLOBAL_DEFAULT_TIMEOUT bare object. homeassistant.helpers.config_validation.string(value: Any) → str Coerce value to string, except for None. homeassistant.helpers.config_validation.string_with_no_html(value: Any) → str Validate that the value is a string without HTML. homeassistant.helpers.config_validation.temperature_unit(value: Any) → str Validate and transform temperature unit. homeassistant.helpers.config_validation.template(value: Any | None) → tem- plate_helper.Template Validate a jinja2 template. homeassistant.helpers.config_validation.template_complex(value: Any) → Any Validate a complex jinja2 template. homeassistant.helpers.config_validation.time(value: Any) → datetime.time Validate and transform a time. homeassistant.helpers.config_validation.time_period_seconds(value: ﬂoat | str) → timedelta Validate and transform seconds to a time offset. homeassistant.helpers.config_validation.time_period_str(value: str) → datetime.timedelta Validate and transform time offset. homeassistant.helpers.config_validation.time_zone(value: str) → str Validate timezone.

98 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.config_validation.url(value: Any) → str Validate an URL. homeassistant.helpers.config_validation.url_no_path(value: Any) → str Validate a url without a path. homeassistant.helpers.config_validation.uuid4_hex(value: Any) → str Validate a v4 UUID in hex format. homeassistant.helpers.config_validation.whitespace(value: Any) → str Validate result contains only whitespace. homeassistant.helpers.config_validation.x10_address(value: str) → str Validate an x10 address.

8.9 homeassistant.helpers.data_entry_ﬂow

Helpers for the data entry flow. class homeassistant.helpers.data_entry_flow.FlowManagerIndexView(flow_mgr: homeassistant.data_entry_flow.FlowManager) Bases: homeassistant.helpers.data_entry_flow._BaseFlowManagerView View to create config flows. async post(request: web.Request, data: dict[str, Any]) → web.Response Handle a POST request. class homeassistant.helpers.data_entry_flow.FlowManagerResourceView(flow_mgr: homeassis- tant.data_entry_flow.FlowManager) Bases: homeassistant.helpers.data_entry_flow._BaseFlowManagerView View to interact with the flow manager. async delete(request: aiohttp.web_request.Request, flow_id: str) → aiohttp.web_response.Response Cancel a flow in progress. async get(request: aiohttp.web_request.Request, flow_id: str) → aiohttp.web_response.Response Get the current state of a data_entry_flow. async post(request: web.Request, flow_id: str, data: dict[str, Any]) → web.Response Handle a POST request.

8.10 homeassistant.helpers.debounce

Debounce helper. class homeassistant.helpers.debounce.Debouncer(hass: HomeAssistant, logger: Logger, *, cooldown: ﬂoat, immediate: bool, function: Callable[..., Awaitable[Any]] | None = None) Bases: object Class to rate limit calls to a speciﬁc command.

8.9. homeassistant.helpers.data_entry_ﬂow 99 Home Assistant Documentation, Release 2021.10.0.dev0

async async_call() → None Call the function. async_cancel() → None Cancel any scheduled call. property function Return the function being wrapped by the Debouncer.

8.11 homeassistant.helpers.deprecation

Deprecation helpers for Home Assistant. homeassistant.helpers.deprecation.deprecated_class(replacement: str) → Any Mark class as deprecated and provide a replacement class to be used instead. homeassistant.helpers.deprecation.deprecated_function(replacement: str) → Callable[[...], Callable] Mark function as deprecated and provide a replacement function to be used instead. homeassistant.helpers.deprecation.deprecated_substitute(substitute_name: str) → Callable[[...], Callable] Help migrate properties to new names. When a property is added to replace an older property, this decorator can be added to the new property, listing the old property as the substitute. If the old property is defined, its value will be used instead, and a log warning will be issued alerting the user of the impending change. homeassistant.helpers.deprecation.get_deprecated(config: dict[str, Any], new_name: str, old_name: str, default: Any | None = None) → Any | None Allow an old config name to be deprecated with a replacement. If the new config isn’t found, but the old one is, the old value is used and a warning is issued to the user.

8.12 homeassistant.helpers.device_registry

Provide a way to connect entities belonging to one device. class homeassistant.helpers.device_registry.DeletedDeviceEntry(config_entries: set[str], connections: set[tuple[str, str]], identifiers: set[tuple[str, str]], id: str, or- phaned_timestamp: float | None) Bases: object Deleted Device Registry Entry. config_entries connections id

100 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

identifiers orphaned_timestamp to_device_entry(config_entry_id: str, connections: set[tuple[str, str]], identifiers: set[tuple[str, str]]) → DeviceEntry Create DeviceEntry from DeletedDeviceEntry. class homeassistant.helpers.device_registry.DeviceEntry(config_entries=NOTHING, connections=NOTHING, identifiers=NOTHING, manufacturer: str | None = None, model: str | None = None, name: str | None = None, sw_version: str | None = None, via_device_id: str | None = None, area_id: str | None = None, name_by_user: str | None = None, entry_type: str | None = None, id: str = NOTHING, is_new: bool = False, disabled_by: str | None = None, sug- gested_area: str | None = None) Bases: object Device Registry Entry. area_id config_entries connections property disabled Return if entry is disabled. disabled_by entry_type id identifiers is_new manufacturer model name name_by_user suggested_area sw_version via_device_id

8.12. homeassistant.helpers.device_registry 101 Home Assistant Documentation, Release 2021.10.0.dev0 class homeassistant.helpers.device_registry.DeviceRegistry(hass: homeassistant.core.HomeAssistant) Bases: object Class to hold a registry of devices. async_clear_area_id(area_id: str) → None Clear area id from registry entries. async_clear_config_entry(config_entry_id: str) → None Clear config entry from registry entries. async_get(device_id: str) → DeviceEntry | None Get device. async_get_device(identifiers: set[tuple[str, str]], connections: set[tuple[str, str]] | None = None) → DeviceEntry | None Check if device is registered. async_get_or_create(*, config_entry_id: str, connections: set[tuple[str, str]] | None = None, identifiers: set[tuple[str, str]] | None = None, manufacturer: str | None | Un- definedType = , model: str | None | Unde- finedType = , name: str | None | Undefined- Type = , default_manufacturer: str | None | UndefinedType = , default_model: str | None | UndefinedType = , default_name: str | None | UndefinedType = , sw_version: str | None | UndefinedType = , entry_type: str | None | UndefinedType = , via_device: tuple[str, str] | None = None, disabled_by: str | None | UndefinedType = , suggested_area: str | None | Undefined- Type = ) → DeviceEntry Get device. Create if it doesn’t exist. async async_load() → None Load the device registry. async_purge_expired_orphaned_devices() → None Purge expired orphaned devices from the registry. We need to purge these periodically to avoid the database growing without bound. async_remove_device(device_id: str) → None Remove a device from the device registry. async_schedule_save() → None Schedule saving the device registry.

102 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

async_update_device(device_id: str, *, area_id: str | None | UndefinedType = , manufacturer: str | None | Undefined- Type = , model: str | None | Unde- finedType = , name: str | None | Un- definedType = , name_by_user: str | None | UndefinedType = , new_identifiers: set[tuple[str, str]] | UndefinedType = , sw_version: str | None | UndefinedType = , via_device_id: str | None | UndefinedType = , add_config_entry_id: str | UndefinedType = , remove_config_entry_id: str | UndefinedType = , disabled_by: str | None | UndefinedType = , suggested_area: str | None | Undefined- Type = ) → DeviceEntry | None Update properties of a device. deleted_devices = None devices = None homeassistant.helpers.device_registry.async_cleanup(hass: HomeAssistant, dev_reg: DeviceRegistry, ent_reg: en- tity_registry.EntityRegistry) → None Clean up device registry. homeassistant.helpers.device_registry.async_config_entry_disabled_by_changed(registry: De- viceReg- istry, con- fig_entry: Con- fi- gEn- try) → None Handle a config entry being disabled or enabled. Disable devices in the registry that are associated with a config entry when the config entry is disabled, enable devices in the registry that are associated with a config entry when the config entry is enabled and the devices are marked DISABLED_CONFIG_ENTRY. Only disable a device if all associated config entries are disabled. homeassistant.helpers.device_registry.async_entries_for_area(registry: De- viceRegistry, area_id: str) → list[DeviceEntry] Return entries that match an area. homeassistant.helpers.device_registry.async_entries_for_config_entry(registry: De- viceReg- istry, con- fig_entry_id: str) → list[DeviceEntry] Return entries that match a config entry.

8.12. homeassistant.helpers.device_registry 103 Home Assistant Documentation, Release 2021.10.0.dev0 homeassistant.helpers.device_registry.async_get(hass: homeassistant.core.HomeAssistant) → homeassistant.helpers.device_registry.DeviceRegistry Get device registry. async homeassistant.helpers.device_registry.async_get_registry(hass: homeassis- tant.core.HomeAssistant) → homeassistant.helpers.device_registry.DeviceRegistry Get device registry. This is deprecated and will be removed in the future. Use async_get instead. async homeassistant.helpers.device_registry.async_load(hass: homeassistant.core.HomeAssistant) → None Load device registry. homeassistant.helpers.device_registry.async_setup_cleanup(hass: homeassistant.core.HomeAssistant, dev_reg: homeassistant.helpers.device_registry.DeviceRegistry) → None Clean up device registry when entities removed. homeassistant.helpers.device_registry.format_mac(mac: str) → str Format the mac address string for entry into dev reg.

8.13 homeassistant.helpers.discovery

Helper methods to help with platform discovery. There are two different types of discoveries that can be fired/listened for. • listen/discover is for services. These are targeted at a component. • listen_platform/discover_platform is for platforms. These are used by components to allow discovery of their platforms. class homeassistant.helpers.discovery.DiscoveryDict Bases: dict Discovery data. discovered = None platform = None service = None async homeassistant.helpers.discovery.async_discover(hass: core.HomeAssistant, service: str, discovered: Dis- coveryInfoType | None, component: str | None, hass_config: ConfigType) → None Fire discovery event. Can ensure a component is loaded.

104 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.discovery.async_listen(hass: homeassistant.core.HomeAssistant, service: str, callback: Callable[[], None]) → None Set up listener for discovery of specific service. Service can be a string or a list/tuple. homeassistant.helpers.discovery.async_listen_platform(hass: core.HomeAssistant, component: str, callback: Callable[[str, dict[str, Any] | None], Any]) → None Register a platform loader listener. This method must be run in the event loop. async homeassistant.helpers.discovery.async_load_platform(hass: homeassistant.core.HomeAssistant, component: str, platform: str, discovered: Dict[str, Any], hass_config: Dict[str, Any]) → None Load a component and platform dynamically. Use async_listen_platform to register a callback for these events. Warning: Do not await this inside a setup method to avoid a dead lock. Use hass.async_create_task(async_load_platform(..)) instead. homeassistant.helpers.discovery.discover(hass: homeassistant.core.HomeAssistant, service: str, discovered: Dict[str, Any], component: str, hass_config: Dict[str, Any]) → None Fire discovery event. Can ensure a component is loaded. homeassistant.helpers.discovery.load_platform(hass: homeassistant.core.HomeAssistant, component: str, platform: str, discovered: Dict[str, Any], hass_config: Dict[str, Any]) → None Load a component and platform dynamically.

8.14 homeassistant.helpers.dispatcher

Helpers for Home Assistant dispatcher & internal component/platform. homeassistant.helpers.dispatcher.async_dispatcher_connect(hass: homeassistant.core.HomeAssistant, signal: str, target: Callable[[...], Any]) → Callable[[], None] Connect a callable function to a signal. This method must be run in the event loop. homeassistant.helpers.dispatcher.async_dispatcher_send(hass: homeassistant.core.HomeAssistant, signal: str, *args: Any) → None Send signal and data. This method must be run in the event loop.

8.14. homeassistant.helpers.dispatcher 105 Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.dispatcher.dispatcher_connect(hass: homeassistant.core.HomeAssistant, signal: str, target: Callable[[...], None]) → Callable[[], None] Connect a callable function to a signal. homeassistant.helpers.dispatcher.dispatcher_send(hass: homeassistant.core.HomeAssistant, signal: str, *args: Any) → None Send signal and data.

8.15 homeassistant.helpers.entity

An abstract class for entities. class homeassistant.helpers.entity.DeviceInfo Bases: dict Entity device information for device registry. connections = None default_manufacturer = None default_model = None default_name = None entry_type = None identifiers = None manufacturer = None model = None name = None suggested_area = None sw_version = None via_device = None class homeassistant.helpers.entity.Entity Bases: abc.ABC An abstract class for Home Assistant entities. add_to_platform_abort() → None Abort adding an entity to a platform. async add_to_platform_finish() → None Finish adding an entity to a platform. add_to_platform_start(hass: HomeAssistant, platform: EntityPlatform, parallel_updates: asyncio.Semaphore | None) → None Start adding an entity to a platform. property assumed_state Return True if unable to access real state of the entity.

106 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

async async_added_to_hass() → None Run when entity about to be added to hass. To be extended by integrations. async async_device_update(warning: bool = True) → None Process ‘update’ or ‘async_update’ from entity. This method is a coroutine. async async_internal_added_to_hass() → None Run when entity about to be added to hass. Not to be extended by integrations. async async_internal_will_remove_from_hass() → None Run when entity will be removed from hass. Not to be extended by integrations. async_on_remove(func: Callable[[], None]) → None Add a function to call when entity removed. async async_remove(*, force_remove: bool = False) → None Remove entity from Home Assistant. If the entity has a non disabled entry in the entity registry, the entity’s state will be set to unavailable, in the same way as when the entity registry is loaded. If the entity doesn’t have a non disabled entry in the entity registry, or if force_remove=True, its state will be removed. async async_removed_from_registry() → None Run when entity has been removed from entity registry. To be extended by integrations. async async_request_call(coro: collections.abc.Awaitable) → None Process request batched. async_schedule_update_ha_state(force_refresh: bool = False) → None Schedule an update ha state change task. This method must be run in the event loop. Scheduling the update avoids executor deadlocks. Entity state and attributes are read when the update ha state change task is executed. If state is changed more than once before the ha state change task has been executed, the intermediate state transitions will be missed. async_set_context(context: homeassistant.core.Context) → None Set the context the entity currently operates under. async async_update_ha_state(force_refresh: bool = False) → None Update Home Assistant with current state of entity. If force_refresh == True will update entity before setting state. This method must be run in the event loop. async async_will_remove_from_hass() → None Run when entity will be removed from hass. To be extended by integrations. async_write_ha_state() → None Write the state to the state machine.

8.15. homeassistant.helpers.entity 107 Home Assistant Documentation, Release 2021.10.0.dev0

property available Return True if entity is available. property capability_attributes Return the capability attributes. Attributes that explain the capabilities of an entity. Implemented by component base class. Convention for attribute names is lowercase snake_case. property context_recent_time Time that a context is considered recent. property device_class Return the class of this device, from component DEVICE_CLASSES. property device_info Return device specific attributes. Implemented by platform classes. property device_state_attributes Return entity specific state attributes. This method is deprecated, platform classes should implement extra_state_attributes instead. property enabled Return if the entity is enabled in the entity registry. If an entity is not part of the registry, it cannot be disabled and will therefore always be enabled. entity_description = None entity_id: str = None property entity_picture Return the entity picture to use in the frontend, if any. property entity_registry_enabled_default Return if the entity should be enabled when first added to the entity registry. property extra_state_attributes Return entity specific state attributes. Implemented by platform classes. Convention for attribute names is lowercase snake_case. property force_update Return True if state updates should be forced. If True, a state change will be triggered anytime the state property is updated, not just when the value changes. hass: HomeAssistant = None property icon Return the icon to use in the frontend, if any. property name Return the name of the entity. parallel_updates: asyncio.Semaphore | None = None platform: EntityPlatform | None = None registry_entry: RegistryEntry | None = None

108 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

schedule_update_ha_state(force_refresh: bool = False) → None Schedule an update ha state change task. Scheduling the update avoids executor deadlocks. Entity state and attributes are read when the update ha state change task is executed. If state is changed more than once before the ha state change task has been executed, the intermediate state transitions will be missed. property should_poll Return True if entity has to be polled for state. False if entity pushes its state to HA. property state Return the state of the entity. property state_attributes Return the state attributes. Implemented by component base class, should not be extended by integrations. Convention for attribute names is lowercase snake_case. property supported_features Flag supported features. property unique_id Return a unique ID. property unit_of_measurement Return the unit of measurement of this entity, if any. class homeassistant.helpers.entity.EntityDescription(key: str, device_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: object A class that describes Home Assistant entities. device_class: str | None = None entity_registry_enabled_default: bool = True force_update: bool = False icon: str | None = None key = None name: str | None = None unit_of_measurement: str | None = None class homeassistant.helpers.entity.ToggleEntity Bases: homeassistant.helpers.entity.Entity An abstract class for entities that can be turned on and off. async async_toggle(**kwargs: Any) → None Toggle the entity.

8.15. homeassistant.helpers.entity 109 Home Assistant Documentation, Release 2021.10.0.dev0

async async_turn_off(**kwargs: Any) → None Turn the entity off. async async_turn_on(**kwargs: Any) → None Turn the entity on. entity_description = None property is_on Return True if entity is on. property state Return the state. toggle(**kwargs: Any) → None Toggle the entity. turn_off(**kwargs: Any) → None Turn the entity off. turn_on(**kwargs: Any) → None Turn the entity on. class homeassistant.helpers.entity.ToggleEntityDescription(key: str, device_class: str | None = None, en- tity_registry_enabled_default: bool = True, force_update: bool = False, icon: str | None = None, name: str | None = None, unit_of_measurement: str | None = None) Bases: homeassistant.helpers.entity.EntityDescription A class that describes toggle entities. key = None homeassistant.helpers.entity.async_generate_entity_id(entity_id_format: str, name: str | None, current_ids: It- erable[str] | None = None, hass: HomeAssistant | None = None) → str Generate a unique entity ID based on given entity IDs or used IDs. homeassistant.helpers.entity.entity_sources(hass: HomeAssistant) → dict[str, dict[str, str]] Get the entity sources. homeassistant.helpers.entity.generate_entity_id(entity_id_format: str, name: str | None, current_ids: list[str] | None = None, hass: HomeAssistant | None = None) → str Generate a unique entity ID based on given entity IDs or used IDs. homeassistant.helpers.entity.get_capability(hass: HomeAssistant, entity_id: str, capability: str) → Any | None Get a capability attribute of an entity. First try the statemachine, then entity registry.

110 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0 homeassistant.helpers.entity.get_device_class(hass: HomeAssistant, entity_id: str) → str | None Get device class of an entity. First try the statemachine, then entity registry. homeassistant.helpers.entity.get_supported_features(hass: homeassistant.core.HomeAssistant, en- tity_id: str) → int Get supported features for an entity. First try the statemachine, then entity registry. homeassistant.helpers.entity.get_unit_of_measurement(hass: HomeAssistant, en- tity_id: str) → str | None Get unit of measurement class of an entity. First try the statemachine, then entity registry.

8.16 homeassistant.helpers.entity_component

Helpers for components that manage entities. class homeassistant.helpers.entity_component.EntityComponent(logger: logging.Logger, domain: str, hass: homeassistant.core.HomeAssistant, scan_interval: datetime.timedelta = datetime.timedelta(seconds=15)) Bases: object The EntityComponent manages platforms that manages entities. This class has the following responsibilities: • Process the configuration and set up a platform based component. • Manage the platforms and their entities. • Help extract the entities from a service call. • Listen for discovery events for platforms related to the domain. async async_extract_from_service(service_call: ServiceCall, expand_group: bool = True) → list[entity.Entity] Extract all known and available entities from a service call. Will return an empty list if entities specified but unknown. This method must be run in the event loop. async async_prepare_reload(*, skip_reset: bool = False) → ConfigType | None Prepare reloading this entity component. This method must be run in the event loop. async_register_entity_service(name: str, schema: dict[str, Any] | vol.Schema, func: str | Callable[..., Any], required_features: list[int] | None = None) → None Register an entity service.

8.16. homeassistant.helpers.entity_component 111 Home Assistant Documentation, Release 2021.10.0.dev0

async async_remove_entity(entity_id: str) → None Remove an entity managed by one of the platforms. async async_setup(config: Dict[str, Any]) → None Set up a full entity component. Loads the platforms from the config and will listen for supported discovered platforms. This method must be run in the event loop. async async_setup_entry(config_entry: homeassistant.config_entries.ConfigEntry) → bool Set up a config entry. async async_setup_platform(platform_type: str, platform_config: ConfigType, discovery_info: DiscoveryInfoType | None = None) → None Set up a platform for this component. async async_unload_entry(config_entry: homeassistant.config_entries.ConfigEntry) → bool Unload a config entry. property entities Return an iterable that returns all entities. get_entity(entity_id: str) → entity.Entity | None Get an entity. setup(config: Dict[str, Any]) → None Set up a full entity component. This doesn’t block the executor to protect from deadlocks. async homeassistant.helpers.entity_component.async_update_entity(hass: homeassistant.core.HomeAssistant, entity_id: str) → None Trigger an update for an entity.

8.17 homeassistant.helpers.entity_platform

Class to manage the entities for a single platform. class homeassistant.helpers.entity_platform.AddEntitiesCallback(*args, **kwargs) Bases: typing.Protocol Protocol type for EntityPlatform.add_entities callback. class homeassistant.helpers.entity_platform.EntityPlatform(*, hass: Home- Assistant, logger: Logger, domain: str, platform_name: str, platform: ModuleType | None, scan_interval: timedelta, en- tity_namespace: str | None) Bases: object Manage the entities for a single platform.

112 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

add_entities(new_entities: Iterable[Entity], update_before_add: bool = False) → None Add entities for a single platform. async async_add_entities(new_entities: Iterable[Entity], update_before_add: bool = False) → None Add entities for a single platform async. This method must be run in the event loop. async_cancel_retry_setup() → None Cancel retry setup. async async_destroy() → None Destroy an entity platform. Call before discarding the object. async async_extract_from_service(service_call: ServiceCall, expand_group: bool = True) → list[Entity] Extract all known and available entities from a service call. Will return an empty list if entities specified but unknown. This method must be run in the event loop. async_register_entity_service(name: str, schema: dict | vol.Schema, func: str | Callable[..., Any], required_features: Iterable[int] | None = None) → None Register an entity service. Services will automatically be shared by all platforms of the same domain. async async_remove_entity(entity_id: str) → None Remove entity id from platform. async async_reset() → None Remove all entities and reset data. This method must be run in the event loop. async async_setup(platform_config: ConfigType, discovery_info: DiscoveryInfoType | None = None) → None Set up the platform from a config file. async async_setup_entry(config_entry: homeassistant.config_entries.ConfigEntry) → bool Set up the platform from a config entry. async async_shutdown() → None Call when Home Assistant is stopping. async_unsub_polling() → None Stop polling. homeassistant.helpers.entity_platform.async_get_current_platform() → homeassistant.helpers.entity_platform.EntityPlatform Get the current platform from context. homeassistant.helpers.entity_platform.async_get_platforms(hass: HomeAssistant, integration_name: str) → list[EntityPlatform] Find existing platforms.

8.17. homeassistant.helpers.entity_platform 113 Home Assistant Documentation, Release 2021.10.0.dev0

8.18 homeassistant.helpers.entity_registry

Provide a registry to track entity IDs. The Entity Registry keeps a registry of entities. Entities are uniquely identified by their domain, platform and a unique id provided by that platform. The Entity Registry will persist itself 10 seconds after a new entity is registered. Registering a new entity while a timer is in progress resets the timer. class homeassistant.helpers.entity_registry.EntityRegistry(hass: homeassistant.core.HomeAssistant) Bases: object Class to hold a registry of entities. async_clear_area_id(area_id: str) → None Clear area id from registry entries. async_clear_config_entry(config_entry: str) → None Clear config entry from registry entries. async_device_modified(event: homeassistant.core.Event) → None Handle the removal or update of a device. Remove entities from the registry that are associated to a device when the device is removed. Disable entities in the registry that are associated to a device when the device is disabled. async_generate_entity_id(domain: str, suggested_object_id: str, known_object_ids: Iter- able[str] | None = None) → str Generate an entity ID that does not conflict. Conflicts checked against registered and currently existing entities. async_get(entity_id: str) → RegistryEntry | None Get EntityEntry for an entity_id. async_get_device_class_lookup(domain_device_classes: set[tuple[str, str | None]]) → dict Return a lookup of entity ids for devices which have matching entities. Entities must match a set of (domain, device_class) tuples. The result is indexed by device_id, then by the matching (domain, device_class) async_get_entity_id(domain: str, platform: str, unique_id: str) → str | None Check if an entity_id is currently registered. async_get_or_create(domain: str, platform: str, unique_id: str, *, suggested_object_id: str | None = None, known_object_ids: Iterable[str] | None = None, disabled_by: str | None = None, config_entry: ConfigEntry | None = None, device_id: str | None = None, area_id: str | None = None, capabilities: Mapping[str, Any] | None = None, supported_features: int | None = None, device_class: str | None = None, unit_of_measurement: str | None = None, original_name: str | None = None, original_icon: str | None = None) → RegistryEntry Get entity. Create if it doesn’t exist. async_is_registered(entity_id: str) → bool Check if an entity_id is currently registered. async async_load() → None Load the entity registry.

114 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

async_remove(entity_id: str) → None Remove an entity from registry. async_schedule_save() → None Schedule saving the entity registry. async_update_entity(entity_id: str, *, name: str | None | UndefinedType = , icon: str | None | UndefinedType = , config_entry_id: str | None | UndefinedType = , area_id: str | None | UndefinedType = , new_entity_id: str | UndefinedType = , new_unique_id: str | UndefinedType = , disabled_by: str | None | UndefinedType = ) → RegistryEntry Update properties of an entity. class homeassistant.helpers.entity_registry.RegistryEntry(entity_id: str, unique_id: str, platform: str, name: str | None = None, icon: str | None = None, device_id: str | None = None, area_id: str | None = None, con- fig_entry_id: str | None = None, disabled_by: str | None = None, capabilities: Mapping[str, Any] | None = None, supported_features: int = 0, device_class: str | None = None, unit_of_measurement: str | None = None, orig- inal_name: str | None = None, original_icon: str | None = None) Bases: object Entity Registry Entry. area_id capabilities config_entry_id device_class device_id property disabled Return if entry is disabled. disabled_by domain entity_id icon

8.18. homeassistant.helpers.entity_registry 115 Home Assistant Documentation, Release 2021.10.0.dev0

name original_icon original_name platform supported_features unique_id unit_of_measurement write_unavailable_state(hass: homeassistant.core.HomeAssistant) → None Write the unavailable state to the state machine. homeassistant.helpers.entity_registry.async_config_entry_disabled_by_changed(registry: En- ti- tyReg- istry, con- fig_entry: Con- fi- gEn- try) → None Handle a config entry being disabled or enabled. Disable entities in the registry that are associated with a config entry when the config entry is disabled, enable entities in the registry that are associated with a config entry when the config entry is enabled and the entities are marked DISABLED_CONFIG_ENTRY. homeassistant.helpers.entity_registry.async_entries_for_area(registry: En- tityRegistry, area_id: str) → list[RegistryEntry] Return entries that match an area. homeassistant.helpers.entity_registry.async_entries_for_config_entry(registry: Enti- tyReg- istry, con- fig_entry_id: str) → list[RegistryEntry] Return entries that match a config entry. homeassistant.helpers.entity_registry.async_entries_for_device(registry: Enti- tyRegistry, de- vice_id: str, in- clude_disabled_entities: bool = False) → list[RegistryEntry] Return entries that match a device.

116 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0 homeassistant.helpers.entity_registry.async_get(hass: homeassistant.core.HomeAssistant) → homeassistant.helpers.entity_registry.EntityRegistry Get entity registry. async homeassistant.helpers.entity_registry.async_get_registry(hass: homeassis- tant.core.HomeAssistant) → homeassistant.helpers.entity_registry.EntityRegistry Get entity registry. This is deprecated and will be removed in the future. Use async_get instead. async homeassistant.helpers.entity_registry.async_load(hass: homeassistant.core.HomeAssistant) → None Load entity registry. async homeassistant.helpers.entity_registry.async_migrate_entries(hass: HomeAssis- tant, con- ﬁg_entry_id: str, en- try_callback: Callable[[RegistryEntry], dict | None]) → None Migrator of unique IDs. homeassistant.helpers.entity_registry.async_setup_entity_restore(hass: homeassistant.core.HomeAssistant, registry: homeassistant.helpers.entity_registry.EntityRegistry) → None Set up the entity restore mechanism.

8.19 homeassistant.helpers.entity_values

A class to hold entity values. class homeassistant.helpers.entity_values.EntityValues(exact: dict[str, dict[str, str]] | None = None, domain: dict[str, dict[str, str]] | None = None, glob: dict[str, dict[str, str]] | None = None) Bases: object Class to store entity id based values. get(entity_id: str) → dict[str, str] Get conﬁg for an entity id.

8.19. homeassistant.helpers.entity_values 117 Home Assistant Documentation, Release 2021.10.0.dev0

8.20 homeassistant.helpers.entityﬁlter

Helper class to implement include/exclude of entities and domains. homeassistant.helpers.entityfilter.convert_filter(config: dict[str, list[str]]) → Callable[[str], bool] Convert the filter schema into a filter. homeassistant.helpers.entityfilter.convert_include_exclude_filter(config: dict[str, dict[str, list[str]]]) → Callable[[str], bool] Convert the include exclude filter schema into a filter. homeassistant.helpers.entityfilter.generate_filter(include_domains: list[str], include_entities: list[str], exclude_domains: list[str], exclude_entities: list[str], in- clude_entity_globs: list[str] = [], exclude_entity_globs: list[str] = []) → Callable[[str], bool] Return a function that will filter entities based on the args.

8.21 homeassistant.helpers.event

Helpers for listening to events. class homeassistant.helpers.event.SunListener(hass: HomeAssistant, job: HassJob, event: str, offset: timedelta | None, un- sub_sun: CALLBACK_TYPE | None = None, unsub_conﬁg: CALLBACK_TYPE | None = None) Bases: object Helper class to help listen to sun events. async_attach() → None Attach a sun listener. async_detach() → None Detach the sun listener. event = None hass = None job = None offset = None class homeassistant.helpers.event.TrackStates(all_states: bool, entities: set[str], domains: set[str]) Bases: object Class for keeping track of states being tracked. all_states: All states on the system are being tracked entities: Entities to track domains: Domains to track

118 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

all_states = None domains = None entities = None class homeassistant.helpers.event.TrackTemplate(template: Template, variables: Tem- plateVarsType, rate_limit: timedelta | None = None) Bases: object Class for keeping track of a template with variables. The template is template to calculate. The variables are variables to pass to the template. The rate_limit is a rate limit on how often the template is re-rendered. rate_limit: timedelta | None = None template = None variables = None class homeassistant.helpers.event.TrackTemplateResult(template: homeassistant.helpers.template.Template, last_result: Any, result: Any) Bases: object Class for result of template tracking. template The template that has changed. last_result The output from the template on the last successful run, or None if no previous successful run. result Result from the template run. This will be a string or an TemplateError if the template resulted in an error. last_result = None result = None template = None homeassistant.helpers.event.async_call_later(hass: HomeAssistant, delay: ﬂoat | timedelta, action: HassJob | Callable[..., Awaitable[None] | None]) → CALL- BACK_TYPE Add a listener that is called in . homeassistant.helpers.event.async_track_entity_registry_updated_event(hass: Home- Assis- tant, en- tity_ids: str | Iter- able[str], action: Callable[[Event], Any]) → Callable[[], None]

8.21. homeassistant.helpers.event 119 Home Assistant Documentation, Release 2021.10.0.dev0

Track specific entity registry updated events indexed by entity_id. Similar to async_track_state_change_event. homeassistant.helpers.event.async_track_point_in_time(hass: HomeAssistant, action: HassJob | Callable[..., Awaitable[None] | None], point_in_time: datetime) → CALLBACK_TYPE Add a listener that fires once after a specific point in time. homeassistant.helpers.event.async_track_point_in_utc_time(hass: HomeAssis- tant, action: Has- sJob | Callable[..., Awaitable[None] | None], point_in_time: datetime) → CALL- BACK_TYPE Add a listener that fires once after a specific point in UTC time. homeassistant.helpers.event.async_track_same_state(hass: HomeAssistant, period: timedelta, action: Callable[..., Awaitable[None] | None], async_check_same_func: Callable[[str, State | None, State | None], bool], entity_ids: str | Iterable[str] = '*') → CALLBACK_TYPE Track the state of entities for a period and run an action. If async_check_func is None it use the state of orig_value. Without entity_ids we track all state changes. homeassistant.helpers.event.async_track_state_added_domain(hass: HomeAssis- tant, domains: str | Iterable[str], action: Callable[[Event], Any]) → Callable[[], None] Track state change events when an entity is added to domains. homeassistant.helpers.event.async_track_state_change(hass: HomeAssistant, en- tity_ids: str | Iterable[str], action: Callable[[str, State, State], Awaitable[None] | None], from_state: None | str | Iterable[str] = None, to_state: None | str | Iterable[str] = None) → CALLBACK_TYPE Track specific state changes. entity_ids, from_state and to_state can be string or list. Use list to match multiple. Returns a function that can be called to remove the listener. If entity_ids are not MATCH_ALL along with from_state and to_state being None, async_track_state_change_event should be used instead as it is slightly faster. Must be run within the event loop.

120 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0 homeassistant.helpers.event.async_track_state_change_event(hass: HomeAssistant, entity_ids: str | It- erable[str], action: Callable[[Event], Any]) → Callable[[], None] Track specific state change events indexed by entity_id. Unlike async_track_state_change, async_track_state_change_event passes the full event to the callback. In order to avoid having to iterate a long list of EVENT_STATE_CHANGED and fire and create a job for each one, we keep a dict of entity ids that care about the state change events so we can do a fast dict lookup to route events. homeassistant.helpers.event.async_track_state_change_filtered(hass: homeassistant.core.HomeAssistant, track_states: homeassistant.helpers.event.TrackStates, action: Callable[[homeassistant.core.Event], Any]) → homeassistant.helpers.event._TrackStateChangeFiltered Track state changes with a TrackStates filter that can be updated. hass Home assistant object. track_states A TrackStates data class. action Callable to call with results. Object used to update the listeners (async_update_listeners) with a new TrackStates or cancel the tracking (async_remove). homeassistant.helpers.event.async_track_state_removed_domain(hass: Home- Assistant, domains: str | Iter- able[str], action: Callable[[Event], Any]) → Callable[[], None] Track state change events when an entity is removed from domains. homeassistant.helpers.event.async_track_sunrise(hass: HomeAssistant, action: Callable[(Ellipsis, None)], offset: timedelta | None = None) → CALL- BACK_TYPE Add a listener that will fire a specified offset from sunrise daily. homeassistant.helpers.event.async_track_sunset(hass: HomeAssistant, action: Callable[(Ellipsis, None)], offset: timedelta | None = None) → CALL- BACK_TYPE Add a listener that will fire a specified offset from sunset daily. homeassistant.helpers.event.async_track_template(hass: HomeAssistant, template: Tem- plate, action: Callable[[str, State | None, State | None], Awaitable[None] | None], variables: TemplateVarsType | None = None) → Callable[[], None]

8.21. homeassistant.helpers.event 121 Home Assistant Documentation, Release 2021.10.0.dev0

Add a listener that ﬁres when a a template evaluates to ‘true’. Listen for the result of the template becoming true, or a true-like string result, such as ‘On’, ‘Open’, or ‘Yes’. If the template results in an error state when the value changes, this will be logged and not passed through. If the initial check of the template is invalid and results in an exception, the listener will still be registered but will only ﬁre if the template result becomes true without an exception. entity_id ID of the entity that triggered the state change. old_state The old state of the entity that changed. new_state New state of the entity that changed.

hass Home assistant object. template The template to calculate. action Callable to call with results. See above for arguments. variables Variables to pass to the template.

Callable to unregister the listener. homeassistant.helpers.event.async_track_template_result(hass: HomeAssistant, track_templates: Iter- able[TrackTemplate], action: TrackTem- plateResultListener, raise_on_template_error: bool = False, strict: bool = False) → _TrackTem- plateResultInfo Add a listener that fires when the result of a template changes. The action will fire with the initial result from the template, and then whenever the output from the template changes. The template will be reevaluated if any states referenced in the last run of the template change, or if manually triggered. If the result of the evaluation is different from the previous run, the listener is passed the result. If the template results in an TemplateError, this will be returned to the listener the first time this happens but not for subsequent errors. Once the template returns to a non-error condition the result is sent to the action as usual. hass Home assistant object. track_templates An iterable of TrackTemplate. action Callable to call with results. raise_on_template_error When set to True, if there is an exception processing the template during setup, the system will raise the exception instead of setting up tracking. strict When set to True, raise on undefined variables. Info object used to unregister the listener, and refresh the template. homeassistant.helpers.event.async_track_time_change(hass: HomeAssistant, action: Callable[(Ellipsis, None)], hour: Any | None = None, minute: Any | None = None, second: Any | None = None) → CALL- BACK_TYPE Add a listener that will fire if UTC time matches a pattern.

122 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.event.async_track_time_interval(hass: HomeAssistant, action: Callable[..., Awaitable[None] | None], interval: timedelta) → CALLBACK_TYPE Add a listener that fires repetitively at every timedelta interval. homeassistant.helpers.event.async_track_utc_time_change(hass: HomeAssistant, action: Callable[..., Awaitable[None] | None], hour: Any | None = None, minute: Any | None = None, second: Any | None = None, local: bool = False) → CALLBACK_TYPE Add a listener that will fire if time matches a pattern. homeassistant.helpers.event.call_later(hass: HomeAssistant, delay: float | timedelta, action: HassJob | Callable[..., Awaitable[None] | None]) → CALLBACK_TYPE Add a listener that is called in . homeassistant.helpers.event.process_state_match(parameter: None | str | Iterable[str]) → Callable[[str | None], bool] Convert parameter to function that matches input against parameter. homeassistant.helpers.event.threaded_listener_factory(async_factory: Callable[[...], Any]) → Callable[[...], Callable[[], None]] Convert an async event helper to a threaded one. homeassistant.helpers.event.track_point_in_time(hass: HomeAssistant, action: Has- sJob | Callable[..., Awaitable[None] | None], point_in_time: datetime) → CALLBACK_TYPE Add a listener that fires once after a specific point in time. homeassistant.helpers.event.track_point_in_utc_time(hass: HomeAssistant, action: HassJob | Callable[..., Awaitable[None] | None], point_in_time: datetime) → CALLBACK_TYPE Add a listener that fires once after a specific point in UTC time. homeassistant.helpers.event.track_same_state(hass: HomeAssistant, period: timedelta, action: Callable[..., Awaitable[None] | None], async_check_same_func: Callable[[str, State | None, State | None], bool], entity_ids: str | Iterable[str] = '*') → CALLBACK_TYPE Track the state of entities for a period and run an action. If async_check_func is None it use the state of orig_value. Without entity_ids we track all state changes. homeassistant.helpers.event.track_state_change(hass: HomeAssistant, entity_ids: str | Iterable[str], action: Callable[[str, State, State], Awaitable[None] | None], from_state: None | str | Iterable[str] = None, to_state: None | str | Iterable[str] = None) → CALLBACK_TYPE Track specific state changes.

8.21. homeassistant.helpers.event 123 Home Assistant Documentation, Release 2021.10.0.dev0

entity_ids, from_state and to_state can be string or list. Use list to match multiple. Returns a function that can be called to remove the listener. If entity_ids are not MATCH_ALL along with from_state and to_state being None, async_track_state_change_event should be used instead as it is slightly faster. Must be run within the event loop. homeassistant.helpers.event.track_sunrise(hass: HomeAssistant, action: Callable[(Ellipsis, None)], offset: timedelta | None = None) → CALLBACK_TYPE Add a listener that will fire a specified offset from sunrise daily. homeassistant.helpers.event.track_sunset(hass: HomeAssistant, action: Callable[(Ellipsis, None)], offset: timedelta | None = None) → CALLBACK_TYPE Add a listener that will fire a specified offset from sunset daily. homeassistant.helpers.event.track_template(hass: HomeAssistant, template: Template, action: Callable[[str, State | None, State | None], Awaitable[None] | None], variables: Templat- eVarsType | None = None) → Callable[[], None] Add a listener that fires when a a template evaluates to ‘true’. Listen for the result of the template becoming true, or a true-like string result, such as ‘On’, ‘Open’, or ‘Yes’. If the template results in an error state when the value changes, this will be logged and not passed through. If the initial check of the template is invalid and results in an exception, the listener will still be registered but will only fire if the template result becomes true without an exception. entity_id ID of the entity that triggered the state change. old_state The old state of the entity that changed. new_state New state of the entity that changed.

hass Home assistant object. template The template to calculate. action Callable to call with results. See above for arguments. variables Variables to pass to the template.

Callable to unregister the listener. homeassistant.helpers.event.track_time_change(hass: HomeAssistant, action: Callable[(Ellipsis, None)], hour: Any | None = None, minute: Any | None = None, second: Any | None = None) → CALLBACK_TYPE Add a listener that will ﬁre if UTC time matches a pattern. homeassistant.helpers.event.track_time_interval(hass: HomeAssistant, action: Callable[..., Awaitable[None] | None], interval: timedelta) → CALL- BACK_TYPE Add a listener that ﬁres repetitively at every timedelta interval.

124 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.event.track_utc_time_change(hass: HomeAssistant, action: Callable[..., Awaitable[None] | None], hour: Any | None = None, minute: Any | None = None, second: Any | None = None, local: bool = False) → CALLBACK_TYPE Add a listener that will ﬁre if time matches a pattern.

8.22 homeassistant.helpers.icon

Icon helper methods. homeassistant.helpers.icon.icon_for_battery_level(battery_level: int | None = None, charging: bool = False) → str Return a battery icon valid identiﬁer. homeassistant.helpers.icon.icon_for_signal_level(signal_level: int | None = None) → str Return a signal icon valid identiﬁer.

8.23 homeassistant.helpers.integration_platform

Helpers to help with integration platforms. async homeassistant.helpers.integration_platform.async_process_integration_platforms(hass: Home- As- sistant, plat- form_name: str, pro- cess_platform: Callable[[HomeAssistant, str, Any], Await- able[None]]) → None Process a speciﬁc platform for all current and future loaded integrations.

8.22. homeassistant.helpers.icon 125 Home Assistant Documentation, Release 2021.10.0.dev0

8.24 homeassistant.helpers.intent

Module to coordinate user intentions. class homeassistant.helpers.intent.Intent(hass: HomeAssistant, platform: str, intent_type: str, slots: _SlotsType, text_input: str | None, context: Context) Bases: object Hold the intent. context create_response() → homeassistant.helpers.intent.IntentResponse Create a response. hass intent_type platform slots text_input exception homeassistant.helpers.intent.IntentError Bases: homeassistant.exceptions.HomeAssistantError Base class for intent related errors. exception homeassistant.helpers.intent.IntentHandleError Bases: homeassistant.helpers.intent.IntentError Error while handling intent. class homeassistant.helpers.intent.IntentHandler Bases: object Intent handler registration. async_can_handle(intent_obj: homeassistant.helpers.intent.Intent) → bool Test if an intent can be handled. async async_handle(intent_obj: homeassistant.helpers.intent.Intent) → homeassistant.helpers.intent.IntentResponse Handle the intent. async_validate_slots(slots: Dict[str, Any]) → Dict[str, Any] Validate slot information. intent_type: str | None = None platforms: Iterable[str] | None = [] slot_schema: vol.Schema | None = None class homeassistant.helpers.intent.IntentResponse(intent: Intent | None = None) Bases: object Response to an intent. as_dict() → dict[str, dict[str, dict[str, Any]]] Return a dictionary representation of an intent response.

126 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

async_set_card(title: str, content: str, card_type: str = 'simple') → None Set speech response. async_set_speech(speech: str, speech_type: str = 'plain', extra_data: Any | None = None) → None Set speech response. exception homeassistant.helpers.intent.IntentUnexpectedError Bases: homeassistant.helpers.intent.IntentError Unexpected error while handling intent. exception homeassistant.helpers.intent.InvalidSlotInfo Bases: homeassistant.helpers.intent.IntentError When the slot data is invalid. class homeassistant.helpers.intent.ServiceIntentHandler(intent_type: str, domain: str, service: str, speech: str) Bases: homeassistant.helpers.intent.IntentHandler Service Intent handler registration. Service speciﬁc intent handler that calls a service by name/entity_id. async async_handle(intent_obj: homeassistant.helpers.intent.Intent) → homeassistant.helpers.intent.IntentResponse Handle the hass intent. slot_schema: vol.Schema | None = {'name': } exception homeassistant.helpers.intent.UnknownIntent Bases: homeassistant.helpers.intent.IntentError When the intent is not registered. async homeassistant.helpers.intent.async_handle(hass: HomeAssistant, platform: str, in- tent_type: str, slots: _SlotsType | None = None, text_input: str | None = None, context: Context | None = None) → In- tentResponse Handle an intent. homeassistant.helpers.intent.async_match_state(hass: HomeAssistant, name: str, states: Iterable[State] | None = None) → State Find a state that matches the name. homeassistant.helpers.intent.async_register(hass: homeassistant.core.HomeAssistant, handler: homeassistant.helpers.intent.IntentHandler) → None Register an intent with Home Assistant. homeassistant.helpers.intent.async_test_feature(state: homeassistant.core.State, feature: int, feature_name: str) → None Test if state supports a feature.

8.24. homeassistant.helpers.intent 127 Home Assistant Documentation, Release 2021.10.0.dev0

8.25 homeassistant.helpers.json

Helpers to help with encoding Home Assistant objects in JSON. class homeassistant.helpers.json.ExtendedJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None) Bases: homeassistant.helpers.json.JSONEncoder JSONEncoder that supports Home Assistant objects and falls back to repr(o). default(o: Any) → Any Convert certain objects. Fall back to repr(o). class homeassistant.helpers.json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None) Bases: json.encoder.JSONEncoder JSONEncoder that supports Home Assistant objects. default(o: Any) → Any Convert Home Assistant objects. Hand other objects to the original method.

8.26 homeassistant.helpers.location

Location helpers for Home Assistant. homeassistant.helpers.location.closest(latitude: ﬂoat, longitude: ﬂoat, states: Iter- able[State]) → State | None Return closest state to point. Async friendly. homeassistant.helpers.location.find_coordinates(hass: HomeAssistant, entity_id: str, re- cursion_history: list | None = None) → str | None Find the gps coordinates of the entity in the form of ‘90.000,180.000’. homeassistant.helpers.location.has_location(state: homeassistant.core.State) → bool Test if state contains a valid location. Async friendly.

128 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

8.27 homeassistant.helpers.logging

Helpers for logging allowing more advanced logging styles to be used. class homeassistant.helpers.logging.KeywordMessage(fmt: Any, args: Any, kwargs: Map- ping[str, Any]) Bases: object Represents a logging message with keyword arguments. Adapted from: https://stackoverﬂow.com/a/24683360/2267718 class homeassistant.helpers.logging.KeywordStyleAdapter(logger: logging.Logger, extra: Mapping[str, Any] | None = None) Bases: logging.LoggerAdapter Represents an adapter wrapping the logger allowing KeywordMessages. log(level: int, msg: Any, *args: Any, **kwargs: Any) → None Log the message provided at the appropriate level. process(msg: Any, kwargs: MutableMapping[str, Any]) → tuple[Any, MutableMapping[str, Any]] Process the keyword args in preparation for logging.

8.28 homeassistant.helpers.network

Network helpers. exception homeassistant.helpers.network.NoURLAvailableError Bases: homeassistant.exceptions.HomeAssistantError An URL to the Home Assistant instance is not available. homeassistant.helpers.network.get_url(hass: homeassistant.core.HomeAssistant, *, re- quire_current_request: bool = False, require_ssl: bool = False, require_standard_port: bool = False, allow_internal: bool = True, allow_external: bool = True, allow_cloud: bool = True, allow_ip: bool = True, prefer_external: bool = False, prefer_cloud: bool = False) → str Get a URL to this instance. homeassistant.helpers.network.is_internal_request(hass: homeassistant.core.HomeAssistant) → bool Test if the current request is internal.

8.27. homeassistant.helpers.logging 129 Home Assistant Documentation, Release 2021.10.0.dev0

8.29 homeassistant.helpers.restore_state

Support for restoring entity states on startup. class homeassistant.helpers.restore_state.RestoreEntity Bases: homeassistant.helpers.entity.Entity Mixin class for restoring previous entity state. async async_get_last_state() → State | None Get the entity state from the previous run. async async_internal_added_to_hass() → None Register this entity as a restorable entity. async async_internal_will_remove_from_hass() → None Run when entity will be removed from hass. entity_description = None class homeassistant.helpers.restore_state.RestoreStateData(hass: homeassistant.core.HomeAssistant) Bases: object Helper class for managing the helper saved data. async async_dump_states() → None Save the current state machine to storage. async static async_get_instance(hass: homeassistant.core.HomeAssistant) → homeassistant.helpers.restore_state.RestoreStateData Get the singleton instance of this data helper. async_get_stored_states() → list[StoredState] Get the set of states which should be stored. This includes the states of all registered entities, as well as the stored states from the previous run, which have not been created as entities on this run, and have not expired. async_restore_entity_added(entity_id: str) → None Store this entity’s state when hass is shutdown. async_restore_entity_removed(entity_id: str) → None Unregister this entity from saving state. async classmethod async_save_persistent_states(hass: homeassistant.core.HomeAssistant) → None Dump states now. async_setup_dump(*args: Any) → None Set up the restore state listeners. class homeassistant.helpers.restore_state.StoredState(state: homeassistant.core.State, last_seen: datetime.datetime) Bases: object Object to represent a stored state. as_dict() → dict[str, Any] Return a dict representation of the stored state.

130 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

classmethod from_dict(json_dict: dict) → homeassistant.helpers.restore_state.StoredState Initialize a stored state from a dict.

8.30 homeassistant.helpers.script

Helpers to execute scripts. class homeassistant.helpers.script.Script(hass: HomeAssistant, sequence: Se- quence[dict[str, Any]], name: str, domain: str, *, running_description: str | None = None, change_listener: Callable[..., Any] | None = None, script_mode: str = 'single', max_runs: int = 10, max_exceeded: str = 'WARNING', logger: logging.Logger | None = None, log_exceptions: bool = True, top_level: bool = True, variables: ScriptVariables | None = None) Bases: object Representation of a script. async async_run(run_variables: _VarsType | None = None, context: Context | None = None, started_action: Callable[..., Any] | None = None) → None Run script. async async_stop(update_state: bool = True, spare: _ScriptRun | None = None) → None Stop running script. property change_listener Return the change_listener. property is_running Return true if script is on. property referenced_areas Return a set of referenced areas. property referenced_devices Return a set of referenced devices. property referenced_entities Return a set of referenced entities. run(variables: _VarsType | None = None, context: Context | None = None) → None Run script. property runs Return the number of current runs. property supports_max Return true if the current mode support max. update_logger(logger: logging.Logger | None = None) → None Update logger. homeassistant.helpers.script.action_trace_append(variables, path) Append a TraceElement to trace[path].

8.30. homeassistant.helpers.script 131 Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.helpers.script.async_validate_action_config(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any]) → Dict[str, Any] Validate config. async homeassistant.helpers.script.async_validate_actions_config(hass: Home- Assistant, actions: list[ConfigType]) → list[ConfigType] Validate a list of actions. homeassistant.helpers.script.breakpoint_clear(hass, key, run_id, node) Clear a breakpoint. homeassistant.helpers.script.breakpoint_clear_all(hass: homeassistant.core.HomeAssistant) → None Clear all breakpoints. homeassistant.helpers.script.breakpoint_list(hass: HomeAssistant) → list[dict[str, Any]] List breakpoints. homeassistant.helpers.script.breakpoint_set(hass, key, run_id, node) Set a breakpoint. homeassistant.helpers.script.debug_continue(hass, key, run_id) Continue execution of a halted script. homeassistant.helpers.script.debug_step(hass, key, run_id) Single step a halted script. homeassistant.helpers.script.debug_stop(hass, key, run_id) Stop execution of a running or halted script. homeassistant.helpers.script.make_script_schema(schema, default_script_mode, extra=0) Make a schema for a component that uses the script helper. homeassistant.helpers.script.trace_action(hass, script_run, stop, variables) Trace action execution.

8.31 homeassistant.helpers.service

Service calling related helpers. class homeassistant.helpers.service.ReloadServiceHelper(service_func: Callable[[homeassistant.core.ServiceCall], collections.abc.Awaitable]) Bases: object Helper for reload services to minimize unnecessary reloads.

132 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

async execute_service(service_call: homeassistant.core.ServiceCall) → None Execute the service. If a previous reload task if currently in progress, wait for it to finish first. Once the previous reload task has finished, one of the waiting tasks will be assigned to execute the reload, the others will wait for the reload to finish. class homeassistant.helpers.service.SelectedEntities(referenced: set[str] = , indirectly_referenced: set[str] = , miss- ing_devices: set[str] = , missing_areas: set[str] = , refer- enced_devices: set[str] = ) Bases: object Class to hold the selected entities. indirectly_referenced = None log_missing(missing_entities: set[str]) → None Log about missing items. missing_areas = None missing_devices = None referenced = None referenced_devices = None class homeassistant.helpers.service.ServiceParams Bases: dict Type for service call parameters. domain = None service = None service_data = None target = None class homeassistant.helpers.service.ServiceTargetSelector(service_call: homeassistant.core.ServiceCall) Bases: object Class to hold a target selector for a service. property has_any_selector Determine if any selectors are present. async homeassistant.helpers.service.async_call_from_config(hass: HomeAssistant, config: ConfigType, blocking: bool = False, variables: TemplateVarsType = None, validate_config: bool = True, context: Context | None = None) → None

8.31. homeassistant.helpers.service 133 Home Assistant Documentation, Release 2021.10.0.dev0

Call a service based on a conﬁg hash. async homeassistant.helpers.service.async_extract_config_entry_ids(hass: homeassis- tant.core.HomeAssistant, ser- vice_call: homeassis- tant.core.ServiceCall, ex- pand_group: bool = True) → set Extract referenced conﬁg entry ids from a service call. async homeassistant.helpers.service.async_extract_entities(hass: HomeAs- sistant, entities: Iterable[Entity], service_call: Service- Call, expand_group: bool = True) → list[Entity] Extract a list of entity objects from a service call. Will convert group entity ids to the entity ids it represents. async homeassistant.helpers.service.async_extract_entity_ids(hass: HomeAssis- tant, service_call: ServiceCall, ex- pand_group: bool = True) → set[str] Extract a set of entity ids from a service call. Will convert group entity ids to the entity ids it represents.

134 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

async homeassistant.helpers.service.async_extract_referenced_entity_ids(hass: homeas- sistant.core.HomeAssistant, ser- vice_call: homeas- sistant.core.ServiceCall, ex- pand_group: bool = True) → homeas- sistant.helpers.service.SelectedEntities Extract referenced entity IDs from a service call. async homeassistant.helpers.service.async_get_all_descriptions(hass: Home- Assistant) → dict[str, dict[str, Any]] Return descriptions (i.e. user documentation) for all service calls. homeassistant.helpers.service.async_prepare_call_from_config(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any], variables: Op- tional[Mapping[str, Any]] = None, val- idate_config: bool = False) → homeassistant.helpers.service.ServiceParams Prepare to call a service based on a config hash. homeassistant.helpers.service.async_register_admin_service(hass: HomeAssistant, domain: str, service: str, service_func: Callable[[ServiceCall], Awaitable | None], schema: vol.Schema = ) → None Register a service that requires admin access.

8.31. homeassistant.helpers.service 135 Home Assistant Documentation, Release 2021.10.0.dev0

homeassistant.helpers.service.async_set_service_schema(hass: HomeAssistant, domain: str, service: str, schema: dict[str, Any]) → None Register a description for a service. homeassistant.helpers.service.call_from_config(hass: homeassistant.core.HomeAssistant, config: Dict[str, Any], blocking: bool = False, variables: Optional[Mapping[str, Any]] = None, validate_config: bool = True) → None Call a service based on a config hash. async homeassistant.helpers.service.entity_service_call(hass: HomeAssis- tant, platforms: Iter- able[EntityPlatform], func: str | Callable[..., Any], call: ServiceCall, required_features: Iter- able[int] | None = None) → None Handle an entity service call. Calls all platforms simultaneously. homeassistant.helpers.service.extract_entity_ids(hass: HomeAssistant, service_call: ServiceCall, expand_group: bool = True) → set[str] Extract a list of entity ids from a service call. Will convert group entity ids to the entity ids it represents. homeassistant.helpers.service.verify_domain_control(hass: homeassistant.core.HomeAssistant, domain: str) → Callable[[Callable[[homeassistant.core.ServiceCall], Any]], Callable[[homeassistant.core.ServiceCall], Any]] Ensure permission to access any entity under domain in service call.

8.32 homeassistant.helpers.signal

Signal handling related helpers. homeassistant.helpers.signal.async_register_signal_handling(hass: homeassistant.core.HomeAssistant) → None Register system signal handler for core.

136 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

8.33 homeassistant.helpers.state

Helpers that help with state related things. class homeassistant.helpers.state.AsyncTrackStates(hass: homeassistant.core.HomeAssistant) Bases: object Record the time when the with-block is entered. Add all states that have changed since the start time to the return list when with-block is exited. Must be run within the event loop. Deprecated. Remove after June 2021. Warning added via get_changed_since. async homeassistant.helpers.state.async_reproduce_state(hass: HomeAssistant, states: State | Iter- able[State], *, context: Context | None = None, re- produce_options: dict[str, Any] | None = None) → None Reproduce a list of states on multiple domains. homeassistant.helpers.state.get_changed_since(states: Iterable[State], utc_point_in_time: dt.datetime) → list[State] Return list of states that have been changed since utc_point_in_time. Deprecated. Remove after June 2021. homeassistant.helpers.state.state_as_number(state: homeassistant.core.State) → ﬂoat Try to coerce our state to a number. Raises ValueError if this is not possible.

8.34 homeassistant.helpers.storage

Helper to help store data. class homeassistant.helpers.storage.Store(hass: HomeAssistant, version: int, key: str, private: bool = False, *, encoder: type[JSONEncoder] | None = None) Bases: object Class to help storing data. async_delay_save(data_func: Callable[[], dict], delay: float = 0) → None Save data with an optional delay. async async_load() → dict | list | None Load data. If the expected version does not match the given version, the migrate function will be invoked with await migrate_func(version, config). Will ensure that when a call comes in while another one is in progress, the second call will wait and return the result of the first call.

8.33. homeassistant.helpers.state 137 Home Assistant Documentation, Release 2021.10.0.dev0

async async_remove() → None Remove all data. async async_save(data: dict | list) → None Save data. property path Return the conﬁg path. async homeassistant.helpers.storage.async_migrator(hass, old_path, store, *, old_conf_load_func=None, old_conf_migrate_func=None) Migrate old data to a store and then load data. async def old_conf_migrate_func(old_data)

8.35 homeassistant.helpers.sun

Helpers for sun events. homeassistant.helpers.sun.get_astral_event_date(hass: HomeAssistant, event: str, date: datetime.date | datetime.datetime | None = None) → datetime.datetime | None Calculate the astral event time for the specified date. homeassistant.helpers.sun.get_astral_event_next(hass: HomeAssistant, event: str, utc_point_in_time: datetime.datetime | None = None, offset: datetime.timedelta | None = None) → datetime.datetime Calculate the next specified solar event. homeassistant.helpers.sun.get_astral_location(hass: HomeAssistant) → tuple[astral.location.Location, astral.Elevation] Get an astral location for the current Home Assistant configuration. homeassistant.helpers.sun.get_location_astral_event_next(location: astral.location.Location, elevation: astral.Elevation, event: str, utc_point_in_time: datetime.datetime | None = None, offset: datetime.timedelta | None = None) → datetime.datetime Calculate the next specified solar event. homeassistant.helpers.sun.is_up(hass: HomeAssistant, utc_point_in_time: datetime.datetime | None = None) → bool Calculate if the sun is currently up.

138 Chapter 8. homeassistant.helpers Home Assistant Documentation, Release 2021.10.0.dev0

8.36 homeassistant.helpers.system_info

Helper to gather system info. async homeassistant.helpers.system_info.async_get_system_info(hass: HomeAssis- tant) → dict[str, Any] Return info about the system.

8.37 homeassistant.helpers.temperature

Temperature helpers for Home Assistant. homeassistant.helpers.temperature.display_temp(hass: HomeAssistant, temperature: float | None, unit: str, precision: float) → float | None Convert temperature into preferred units/precision for display.

8.38 homeassistant.helpers.template

Template helper methods for rendering strings with Home Assistant data. class homeassistant.helpers.template.AllStates(hass: homeassistant.core.HomeAssistant) Bases: object Class to expose all HA states as attributes. class homeassistant.helpers.template.DomainStates(hass: homeassistant.core.HomeAssistant, domain: str) Bases: object Class to expose a speciﬁc HA domain as attributes. class homeassistant.helpers.template.LoggingUndefined(hint: Optional[str] = None, obj: Any = missing, name: Optional[str] = None, exc: Type[jinja2.exceptions.TemplateRuntimeError] = ) Bases: jinja2.runtime.Undefined Log on undeﬁned variables. class homeassistant.helpers.template.RenderInfo(template: homeassistant.helpers.template.Template) Bases: object Holds information about a template render. result() → str Results of the template computation. class homeassistant.helpers.template.ResultWrapper Bases: object Result wrapper class to store render result.

8.36. homeassistant.helpers.system_info 139 Home Assistant Documentation, Release 2021.10.0.dev0

render_result = None class homeassistant.helpers.template.Template(template, hass=None) Bases: object Class to hold a template and manage caching and rendering. async_render(variables: Optional[Mapping[str, Any]] = None, parse_result: bool = True, limited: bool = False, strict: bool = False, **kwargs: Any) → Any Render given template. This method must be run in the event loop. If limited is True, the template is not allowed to access any function or filter depending on hass or the state machine. async_render_to_info(variables: Optional[Mapping[str, Any]] = None, strict: bool = False, **kwargs: Any) → homeassistant.helpers.template.RenderInfo Render the template and collect an entity filter. async async_render_will_timeout(timeout: float, variables: Optional[Mapping[str, Any]] = None, strict: bool = False, **kwargs: Any) → bool Check to see if rendering a template will timeout during render. This is intended to check for expensive templates that will make the system unstable. The template is rendered in the executor to ensure it does not tie up the event loop. This function is not a security control and is only intended to be used as a safety check when testing templates. This method must be run in the event loop. async_render_with_possible_json_value(value, error_value=