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

Set up the logging.

This method must be run in the event loop.

homeassistant.bootstrap.async_from_config_dict(config: typing.Dict[str, typing.Any], hass: homeassistant.core.HomeAssistant, config_dir: typing.Union[str, NoneType] = None, enable_log: bool = True, verbose: bool = False, skip_pip: bool = False, log_rotate_days: typing.Any = None) → typing.Union[homeassistant.core.HomeAssistant, NoneType][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: typing.Any = None)[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, loop: asyncio.events.AbstractEventLoop) → str[source]

Add local library to Python Path.

This function is a coroutine.

homeassistant.bootstrap.from_config_dict(config: typing.Dict[str, typing.Any], hass: typing.Union[homeassistant.core.HomeAssistant, NoneType] = None, config_dir: typing.Union[str, NoneType] = None, enable_log: bool = True, verbose: bool = False, skip_pip: bool = False, log_rotate_days: typing.Any = None) → typing.Union[homeassistant.core.HomeAssistant, NoneType][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: typing.Union[homeassistant.core.HomeAssistant, NoneType] = None, verbose: bool = False, skip_pip: bool = True, log_rotate_days: typing.Any = None)[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.

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

Add local library to Python Path.

config module

Module to help with parsing and generating configuration files.

homeassistant.config.async_check_ha_config_file(hass)[source]

Check if Home Assistant configuration file is valid.

This method is a coroutine.

homeassistant.config.async_hass_config_yaml(hass)[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, domain, config, hass)[source]

Generate log exception for configuration validation.

This method must be run in the event loop.

homeassistant.config.async_notify_setup_error(hass, component, link=False)[source]

Print a persistent notification.

This method must be run in the event loop.

homeassistant.config.async_process_component_config(hass, config, domain)[source]

Check component configuration and return processed configuration.

Raise a vol.Invalid exception on error.

This method must be run in the event loop.

homeassistant.config.async_process_ha_core_config(hass, config)[source]

Process the [homeassistant] section from the configuration.

This method is a coroutine.

homeassistant.config.create_default_config(config_dir, detect_location=True)[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) → 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)[source]

Look in given directory for supported configuration files.

Async friendly.

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

Parse a YAML configuration file.

This method needs to run in an executor.

homeassistant.config.merge_packages_config(config, packages)[source]

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

homeassistant.config.process_ha_config_upgrade(hass)[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()[source]

Create a dictionary representation of this dict.

Async friendly.

distance(lat: float, lon: float) → 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)[source]

Generate path to the file within the configuration directory.

Async friendly.

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, data=None, origin=<EventOrigin.local: 'LOCAL'>, time_fired=None)[source]

Bases: object

Representation of an event within the bus.

as_dict()[source]

Create a dict representation of this Event.

Async friendly.

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

Bases: object

Allow the firing of and listening for events.

async_fire(event_type: str, event_data=None, origin=<EventOrigin.local: 'LOCAL'>, wait=False)[source]

Fire an event.

This method must be run in the event loop.

async_listen(event_type, listener)[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, listener)[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()[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=None, origin=<EventOrigin.local: 'LOCAL'>)[source]

Fire an event.

listen(event_type, listener)[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, listener)[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=None)[source]

Bases: object

Root object of the Home Assistant home automation.

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

Add job to the executor pool.

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

async_add_job(target: typing.Callable[..., NoneType], *args: typing.Any) → None[source]

Add a job from within the eventloop.

This method must be run in the event loop.

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

async_block_till_done()[source]

Block till all pending work is done.

async_run_job(target: typing.Callable[..., NoneType], *args: typing.Any) → 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()[source]

Finalize startup from inside the event loop.

This method is a coroutine.

async_stop(exit_code=0) → None[source]

Stop Home Assistant and shuts down all threads.

This method is a coroutine.

async_stop_track_tasks()[source]

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

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

Start home assistant.

stop() → None[source]

Stop Home Assistant and shuts down all threads.

class homeassistant.core.Service(func, description, fields, schema)[source]

Bases: object

Representation of a callable service.

as_dict()[source]

Return dictionary representation of this service.

description
fields
func
is_callback
is_coroutinefunction
schema
class homeassistant.core.ServiceCall(domain, service, data=None, call_id=None)[source]

Bases: object

Representation of a call to a service.

call_id
data
domain
service
class homeassistant.core.ServiceRegistry(hass)[source]

Bases: object

Offer the services over the eventbus.

async_call(domain, service, service_data=None, blocking=False)[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 succesfully 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, service, service_func, description=None, schema=None)[source]

Register a service.

Description is a dict containing key ‘description’ to describe the service and a key ‘fields’ to describe the fields.

Schema is called to coerce and validate the service data.

This method must be run in the event loop.

async_remove(domain, service)[source]

Remove a registered service from service handler.

This method must be run in the event loop.

async_services()[source]

Return dictionary with per domain a list of available services.

This method must be run in the event loop.

call(domain, service, service_data=None, blocking=False)[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 succesfully 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, service)[source]

Test if specified service exists.

Async friendly.

register(domain, service, service_func, description=None, schema=None)[source]

Register a service.

Description is a dict containing key ‘description’ to describe the service and a key ‘fields’ to describe the fields.

Schema is called to coerce and validate the service data.

remove(domain, service)[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, state, attributes=None, last_changed=None, last_updated=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.

as_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
domain

Domain of this state.

entity_id
classmethod from_dict(json_dict)[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, loop)[source]

Bases: object

Helper class that tracks the state of different entities.

all()[source]

Create a list of all states.

async_all()[source]

Create a list of all states.

This method must be run in the event loop.

async_entity_ids(domain_filter=None)[source]

List of entity ids that are being tracked.

This method must be run in the event loop.

async_remove(entity_id)[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, new_state, attributes=None, force_update=False)[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=None)[source]

List of entity ids that are being tracked.

get(entity_id)[source]

Retrieve state of entity_id or None if not found.

Async friendly.

is_state(entity_id, state)[source]

Test if entity exists and is specified state.

Async friendly.

is_state_attr(entity_id, name, value)[source]

Test if entity exists and has a state attribute set to value.

Async friendly.

remove(entity_id)[source]

Remove the state of an entity.

Returns boolean to indicate if an entity was removed.

set(entity_id, new_state, attributes=None, force_update=False)[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(loop, context)[source]

Handle all exception inside the core loop.

homeassistant.core.callback(func: typing.Callable[..., NoneType]) → typing.Callable[..., NoneType][source]

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

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

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

homeassistant.core.split_entity_id(entity_id: str) → typing.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.

exceptions module

The exceptions used by Home Assistant.

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

Bases: homeassistant.exceptions.HomeAssistantError

Error during template rendering.

loader module

Provides 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 are loaded by calling get_component(‘switch’) from your code. If you want to retrieve a platform that is part of a component, you should call get_component(‘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.ComponentWrapper(hass, component)[source]

Bases: object

Class to wrap a component and auto fill in hass argument.

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

Bases: object

Helper to load components.

homeassistant.loader.bind_hass(func)[source]

Decorator to indicate that first argument is hass.

homeassistant.loader.get_component(comp_name) → typing.Union[module, NoneType][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(domain: str, platform: str) → typing.Union[module, NoneType][source]

Try to load specified platform.

Async friendly.

homeassistant.loader.load_order_component(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.prepare()[source]

Prepare the loading of components.

This method needs to run in an executor.

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

Set a component in the cache.

Async friendly.

remote module

Support for an interface to work with a remote instance of Home Assistant.

If a connection error occurs while communicating with the API a HomeAssistantError will be raised.

For more details about the Python API, please refer to the documentation at https://home-assistant.io/developers/python_api/

class homeassistant.remote.API(host: str, api_password: typing.Union[str, NoneType] = None, port: typing.Union[int, NoneType] = 8123, use_ssl: bool = False) → None[source]

Bases: object

Object to pass around Home Assistant API location and credentials.

validate_api(force_validate: bool = False) → bool[source]

Test if we can communicate with the API.

class homeassistant.remote.APIStatus[source]

Bases: enum.Enum

Representation of an API status.

CANNOT_CONNECT = 'cannot_connect'
INVALID_PASSWORD = 'invalid_password'
OK = 'ok'
UNKNOWN = 'unknown'
class homeassistant.remote.JSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: json.encoder.JSONEncoder

JSONEncoder that supports Home Assistant objects.

default(o)[source]

Convert Home Assistant objects.

Hand other objects to the original method.

homeassistant.remote.call_service(api, domain, service, service_data=None, timeout=5)[source]

Call a service at the remote API.

homeassistant.remote.fire_event(api, event_type, data=None)[source]

Fire an event at remote API.

homeassistant.remote.get_config(api)[source]

Return configuration.

homeassistant.remote.get_event_listeners(api)[source]

List of events that is being listened for.

homeassistant.remote.get_services(api)[source]

Return a list of dicts.

Each dict has a string “domain” and a list of strings “services”.

homeassistant.remote.get_state(api, entity_id)[source]

Query given API for state of entity_id.

homeassistant.remote.get_states(api)[source]

Query given API for all states.

homeassistant.remote.is_state(api, entity_id, state)[source]

Query API to see if entity_id is specified state.

homeassistant.remote.remove_state(api, entity_id)[source]

Call API to remove state for entity_id.

Return True if entity is gone (removed/never existed).

homeassistant.remote.set_state(api, entity_id, new_state, attributes=None, force_update=False)[source]

Tell API to update state for entity_id.

Return True if success.

homeassistant.remote.validate_api(api)[source]

Make a call to validate API.

Module contents

Init file for Home Assistant.