homeassistant package

Submodules

bootstrap module

Provide methods to bootstrap a Home Assistant instance.

homeassistant.bootstrap.async_enable_logging(hass: homeassistant.core.HomeAssistant, verbose: bool = False, log_rotate_days: Optional[int] = None, log_file: Optional[str] = None, log_no_color: bool = False) → None[source]

Set up the logging.

This method must be run in the event loop.

homeassistant.bootstrap.async_from_config_dict(config: Dict[str, Any], hass: homeassistant.core.HomeAssistant, config_dir: Optional[str] = None, enable_log: bool = True, verbose: bool = False, skip_pip: bool = False, log_rotate_days: Any = None, log_file: Any = None, log_no_color: bool = False) → Optional[homeassistant.core.HomeAssistant][source]

Try to configure Home Assistant from a configuration dictionary.

Dynamically loads required components and its dependencies. This method is a coroutine.

homeassistant.bootstrap.async_from_config_file(config_path: str, hass: homeassistant.core.HomeAssistant, verbose: bool = False, skip_pip: bool = True, log_rotate_days: Any = None, log_file: Any = None, log_no_color: bool = False) → Optional[homeassistant.core.HomeAssistant][source]

Read the configuration file and try to start all the functionality.

Will add functionality to ‘hass’ parameter. This method is a coroutine.

homeassistant.bootstrap.async_mount_local_lib_path(config_dir: str) → str[source]

Add local library to Python Path.

This function is a coroutine.

homeassistant.bootstrap.from_config_dict(config: Dict[str, Any], hass: Optional[homeassistant.core.HomeAssistant] = None, config_dir: Optional[str] = None, enable_log: bool = True, verbose: bool = False, skip_pip: bool = False, log_rotate_days: Any = None, log_file: Any = None, log_no_color: bool = False) → Optional[homeassistant.core.HomeAssistant][source]

Try to configure Home Assistant from a configuration dictionary.

Dynamically loads required components and its dependencies.

homeassistant.bootstrap.from_config_file(config_path: str, hass: Optional[homeassistant.core.HomeAssistant] = None, verbose: bool = False, skip_pip: bool = True, log_rotate_days: Any = None, log_file: Any = None, log_no_color: bool = False) → Optional[homeassistant.core.HomeAssistant][source]

Read the configuration file and try to start all the functionality.

Will add functionality to ‘hass’ parameter if given, instantiates a new Home Assistant object if ‘hass’ is not given.

config module

Module to help with parsing and generating configuration files.

homeassistant.config.async_check_ha_config_file(hass: homeassistant.core.HomeAssistant) → Optional[str][source]

Check if Home Assistant configuration file is valid.

This method is a coroutine.

homeassistant.config.async_hass_config_yaml(hass: homeassistant.core.HomeAssistant) → Dict[source]

Load YAML from a Home Assistant configuration file.

This function allow a component inside the asyncio loop to reload its configuration by itself.

This method is a coroutine.

homeassistant.config.async_log_exception(ex: voluptuous.error.Invalid, domain: str, config: Dict, hass: homeassistant.core.HomeAssistant) → None[source]

Log an error for configuration validation.

This method must be run in the event loop.

homeassistant.config.async_notify_setup_error(hass: homeassistant.core.HomeAssistant, component: str, display_link: bool = False) → None[source]

Print a persistent notification.

This method must be run in the event loop.

homeassistant.config.async_process_component_config(hass: homeassistant.core.HomeAssistant, config: Dict, domain: str) → Optional[Dict][source]

Check component configuration and return processed configuration.

Returns None on error.

This method must be run in the event loop.

homeassistant.config.async_process_ha_core_config(hass: homeassistant.core.HomeAssistant, config: Dict, has_api_password: bool = False, has_trusted_networks: bool = False) → None[source]

Process the [homeassistant] section from the configuration.

This method is a coroutine.

homeassistant.config.create_default_config(config_dir: str, detect_location: bool = True) → Optional[str][source]

Create a default configuration file in given configuration directory.

Return path to new config file if success, None if failed. This method needs to run in an executor.

homeassistant.config.ensure_config_exists(config_dir: str, detect_location: bool = True) → Optional[str][source]

Ensure a configuration file exists in given configuration directory.

Creating a default one if needed. Return path to the configuration file.

homeassistant.config.find_config_file(config_dir: Optional[str]) → Optional[str][source]

Look in given directory for supported configuration files.

homeassistant.config.get_default_config_dir() → str[source]

Put together the default configuration directory based on the OS.

homeassistant.config.load_yaml_config_file(config_path: str) → Dict[Any, Any][source]

Parse a YAML configuration file.

This method needs to run in an executor.

homeassistant.config.merge_packages_config(hass: homeassistant.core.HomeAssistant, config: Dict, packages: Dict, _log_pkg_error: Callable = <function _log_pkg_error>) → Dict[source]

Merge packages into the top-level configuration. Mutate config.

homeassistant.config.process_ha_config_upgrade(hass: homeassistant.core.HomeAssistant) → None[source]

Upgrade configuration if necessary.

This method needs to run in an executor.

const module

Constants used by Home Assistant components.

core module

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[source]

Bases: object

Configuration settings for Home Assistant.

as_dict() → Dict[source]

Create a dictionary representation of this dict.

Async friendly.

distance(lat: float, lon: float) → Optional[float][source]

Calculate distance from Home Assistant.

Async friendly.

is_allowed_path(path: str) → bool[source]

Check if the path is valid for access from outside.

path(*path) → str[source]

Generate path to the file within the configuration directory.

Async friendly.

class homeassistant.core.Context(user_id: str = None, id: str = NOTHING)[source]

Bases: object

The context that triggered something.

as_dict() → dict[source]

Return a dictionary representation of the context.

id
user_id
class homeassistant.core.CoreState[source]

Bases: enum.Enum

Represent the current state of Home Assistant.

not_running = 'NOT_RUNNING'
running = 'RUNNING'
starting = 'STARTING'
stopping = 'STOPPING'
class homeassistant.core.Event(event_type: str, data: Optional[Dict] = None, origin: homeassistant.core.EventOrigin = <EventOrigin.local: 'LOCAL'>, time_fired: Optional[int] = None, context: Optional[homeassistant.core.Context] = None)[source]

Bases: object

Representation of an event within the bus.

as_dict() → Dict[source]

Create a dict representation of this Event.

Async friendly.

context
data
event_type
origin
time_fired
class homeassistant.core.EventBus(hass: homeassistant.core.HomeAssistant)[source]

Bases: object

Allow the firing of and listening for events.

async_fire(event_type: str, event_data: Optional[Dict] = None, origin: homeassistant.core.EventOrigin = <EventOrigin.local: 'LOCAL'>, context: Optional[homeassistant.core.Context] = None) → None[source]

Fire an event.

This method must be run in the event loop.

async_listen(event_type: str, listener: Callable) → Callable[None][source]

Listen for all events or events of a specific type.

To listen to all events specify the constant MATCH_ALL as event_type.

This method must be run in the event loop.

async_listen_once(event_type: str, listener: Callable) → Callable[None][source]

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][source]

Return dictionary with events and the number of listeners.

This method must be run in the event loop.

fire(event_type: str, event_data: Optional[Dict] = None, origin: homeassistant.core.EventOrigin = <EventOrigin.local: 'LOCAL'>, context: Optional[homeassistant.core.Context] = None) → None[source]

Fire an event.

listen(event_type: str, listener: Callable) → Callable[None][source]

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) → Callable[None][source]

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.

listeners

Return dictionary with events and the number of listeners.

class homeassistant.core.EventOrigin[source]

Bases: enum.Enum

Represent the origin of an event.

local = 'LOCAL'
remote = 'REMOTE'
class homeassistant.core.HomeAssistant(loop: Optional[asyncio.events.AbstractEventLoop] = None)[source]

Bases: object

Root object of the Home Assistant home automation.

add_job(target: Callable[..., None], *args) → None[source]

Add job to the executor pool.

target: target to call. args: parameters for method to call.

async_add_executor_job(target: Callable[..., T], *args) → Awaitable[T][source]

Add an executor job from within the event loop.

async_add_job(target: Callable[..., Any], *args) → Optional[_asyncio.Future][source]

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_block_till_done() → None[source]

Block till all pending work is done.

async_create_task(target: Coroutine) → _asyncio.Task[source]

Create a task from within the eventloop.

This method must be run in the event loop.

target: target to call.

async_run(*, attach_signals: bool = True) → int[source]

Home Assistant main entry point.

Start Home Assistant and block until stopped.

This method is a coroutine.

async_run_job(target: Callable[..., None], *args) → None[source]

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_start() → None[source]

Finalize startup from inside the event loop.

This method is a coroutine.

async_stop(exit_code: int = 0, *, force: bool = False) → None[source]

Stop Home Assistant and shuts down all threads.

The “force” flag commands async_stop to proceed regardless of Home Assistan’t current state. You should not set this flag unless you’re testing.

This method is a coroutine.

async_stop_track_tasks() → None[source]

Stop track tasks so you can’t wait for all tasks to be done.

async_track_tasks() → None[source]

Track tasks so you can wait for all tasks to be done.

block_till_done() → None[source]

Block till all pending work is done.

is_running

Return if Home Assistant is running.

start() → int[source]

Start home assistant.

Note: This function is only used for testing. For regular use, use “await hass.run()”.

stop() → None[source]

Stop Home Assistant and shuts down all threads.

class homeassistant.core.Service(func: Callable, schema: Optional[voluptuous.schema_builder.Schema], context: Optional[homeassistant.core.Context] = None)[source]

Bases: object

Representation of a callable service.

func
is_callback
is_coroutinefunction
schema
class homeassistant.core.ServiceCall(domain: str, service: str, data: Optional[Dict] = None, context: Optional[homeassistant.core.Context] = None)[source]

Bases: object

Representation of a call to a service.

context
data
domain
service
class homeassistant.core.ServiceRegistry(hass: homeassistant.core.HomeAssistant)[source]

Bases: object

Offer the services over the eventbus.

async_call(domain: str, service: str, service_data: Optional[Dict] = None, blocking: bool = False, context: Optional[homeassistant.core.Context] = None) → Optional[bool][source]

Call a service.

Specify blocking=True to wait till service is executed. Waits a maximum of SERVICE_CALL_LIMIT.

If blocking = True, will return boolean if service executed successfully within SERVICE_CALL_LIMIT.

This method will fire an event to call the service. This event will be picked up by this ServiceRegistry and any other ServiceRegistry that is listening on the EventBus.

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.

async_register(domain: str, service: str, service_func: Callable, schema: Optional[voluptuous.schema_builder.Schema] = None) → None[source]

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[source]

Remove a registered service from service handler.

This method must be run in the event loop.

async_services() → Dict[str, Dict[str, homeassistant.core.Service]][source]

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: Optional[Dict] = None, blocking: bool = False, context: Optional[homeassistant.core.Context] = None) → Optional[bool][source]

Call a service.

Specify blocking=True to wait till service is executed. Waits a maximum of SERVICE_CALL_LIMIT.

If blocking = True, will return boolean if service executed successfully within SERVICE_CALL_LIMIT.

This method will fire an event to call the service. This event will be picked up by this ServiceRegistry and any other ServiceRegistry that is listening on the EventBus.

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.

has_service(domain: str, service: str) → bool[source]

Test if specified service exists.

Async friendly.

register(domain: str, service: str, service_func: Callable, schema: Optional[voluptuous.schema_builder.Schema] = None) → None[source]

Register a service.

Schema is called to coerce and validate the service data.

remove(domain: str, service: str) → None[source]

Remove a registered service from service handler.

services

Return dictionary with per domain a list of available services.

class homeassistant.core.State(entity_id: str, state: Any, attributes: Optional[Dict] = None, last_changed: Optional[datetime.datetime] = None, last_updated: Optional[datetime.datetime] = None, context: Optional[homeassistant.core.Context] = None)[source]

Bases: object

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

as_dict() → Dict[source]

Return a dict representation of the State.

Async friendly.

To be used for JSON serialization. Ensures: state == State.from_dict(state.as_dict())

attributes
context
domain

Domain of this state.

entity_id
classmethod from_dict(json_dict: Dict) → Any[source]

Initialize a state from a dict.

Async friendly.

Ensures: state == State.from_json_dict(state.to_json_dict())

last_changed
last_updated
name

Name of this state.

object_id

Object id of this state.

state
class homeassistant.core.StateMachine(bus: homeassistant.core.EventBus, loop: asyncio.events.AbstractEventLoop)[source]

Bases: object

Helper class that tracks the state of different entities.

all() → List[homeassistant.core.State][source]

Create a list of all states.

async_all() → List[homeassistant.core.State][source]

Create a list of all states.

This method must be run in the event loop.

async_entity_ids(domain_filter: Optional[str] = None) → List[str][source]

List of entity ids that are being tracked.

This method must be run in the event loop.

async_remove(entity_id: str) → bool[source]

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_set(entity_id: str, new_state: Any, attributes: Optional[Dict] = None, force_update: bool = False, context: Optional[homeassistant.core.Context] = None) → None[source]

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: Optional[str] = None) → List[str][source]

List of entity ids that are being tracked.

get(entity_id: str) → Optional[homeassistant.core.State][source]

Retrieve state of entity_id or None if not found.

Async friendly.

is_state(entity_id: str, state: homeassistant.core.State) → bool[source]

Test if entity exists and is specified state.

Async friendly.

remove(entity_id: str) → bool[source]

Remove the state of an entity.

Returns boolean to indicate if an entity was removed.

set(entity_id: str, new_state: Any, attributes: Optional[Dict] = None, force_update: bool = False, context: Optional[homeassistant.core.Context] = None) → None[source]

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.async_loop_exception_handler(_: Any, context: Dict) → None[source]

Handle all exception inside the core loop.

homeassistant.core.callback(func: CALLABLE_T) → CALLABLE_T[source]

Annotation to mark method as safe to call from within the event loop.

homeassistant.core.is_callback(func: Callable[..., Any]) → bool[source]

Check if function is safe to be called in the event loop.

homeassistant.core.split_entity_id(entity_id: str) → List[str][source]

Split a state entity_id into domain, object_id.

homeassistant.core.valid_entity_id(entity_id: str) → bool[source]

Test if an entity ID is a valid format.

homeassistant.core.valid_state(state: str) → bool[source]

Test if a state is valid.

exceptions module

The exceptions used by Home Assistant.

exception homeassistant.exceptions.ConfigEntryNotReady[source]

Bases: homeassistant.exceptions.HomeAssistantError

Error to indicate that config entry is not ready.

exception homeassistant.exceptions.HomeAssistantError[source]

Bases: Exception

General Home Assistant exception occurred.

exception homeassistant.exceptions.InvalidEntityFormatError[source]

Bases: homeassistant.exceptions.HomeAssistantError

When an invalid formatted entity is encountered.

exception homeassistant.exceptions.InvalidStateError[source]

Bases: homeassistant.exceptions.HomeAssistantError

When an invalid state is encountered.

exception homeassistant.exceptions.NoEntitySpecifiedError[source]

Bases: homeassistant.exceptions.HomeAssistantError

When no entity is specified.

exception homeassistant.exceptions.PlatformNotReady[source]

Bases: homeassistant.exceptions.HomeAssistantError

Error to indicate that platform is not ready.

exception homeassistant.exceptions.TemplateError(exception: jinja2.exceptions.TemplateError)[source]

Bases: homeassistant.exceptions.HomeAssistantError

Error during template rendering.

loader module

The methods for loading Home Assistant components.

This module has quite some complex parts. I have tried to add as much documentation as possible to keep it understandable.

Components can be accessed via hass.components.switch from your code. If you want to retrieve a platform that is part of a component, you should call get_component(hass, ‘switch.your_platform’). In both cases the config directory is checked to see if it contains a user provided version. If not available it will check the built-in components and platforms.

class homeassistant.loader.Components(hass)[source]

Bases: object

Helper to load components.

class homeassistant.loader.Helpers(hass)[source]

Bases: object

Helper to load helpers.

class homeassistant.loader.ModuleWrapper(hass, module: module)[source]

Bases: object

Class to wrap a Python module and auto fill in hass argument.

homeassistant.loader.bind_hass(func: CALLABLE_T) → CALLABLE_T[source]

Decorate function to indicate that first argument is hass.

homeassistant.loader.get_component(hass, comp_or_platform: str) → Optional[module][source]

Try to load specified component.

Looks in config dir first, then built-in components. Only returns it if also found to be valid. Async friendly.

homeassistant.loader.get_platform(hass, domain: str, platform: str) → Optional[module][source]

Try to load specified platform.

Async friendly.

homeassistant.loader.load_order_component(hass, comp_name: str) → homeassistant.util.OrderedSet[source]

Return an OrderedSet of components in the correct order of loading.

Raises HomeAssistantError if a circular dependency is detected. Returns an empty list if component could not be loaded.

Async friendly.

homeassistant.loader.set_component(hass, comp_name: str, component: Optional[module]) → None[source]

Set a component in the cache.

Async friendly.

Module contents

Init file for Home Assistant.