Usage

The Basics…

This library provides four client classes:

  • Client — sync REST API client

  • AsyncClient — async REST API client

  • WebsocketClient — sync WebSocket client

  • AsyncWebsocketClient — async WebSocket client

Once you have your API base URL and Long Lived Access Token from Home Assistant we can start to do stuff. The rest of this guide assumes you have a client saved to a variable as shown below. Most of these examples require some integrations to be setup inside Home Assistant for the examples to actually work. The most commonly used features of this library include triggering services and getting and modifying entity states.

 1import os
 2from homeassistant_api import Client
 3
 4URL = '<API BASE URL>'  # Example: 'http://homeassistant.local:8123/api'
 5TOKEN = '<LONG LIVED ACCESS TOKEN>'
 6
 7# Assigns the Client object to a variable and checks if it's running.
 8client = Client(URL, TOKEN)
 9
10service = client.get_domain("light")  # Gets the light service domain from Home Assistant
11
12service.turn_on(entity_id="light.my_living_room_light")
13# Triggers the light.turn_on service on the entity `light.my_living_room_light`

1from homeassistant_api import WebsocketClient
2
3WS_URL = '<WS API BASE URL>'  # Example: 'ws://homeassistant.local:8123/api/websocket'
4TOKEN = '<LONG LIVED ACCESS TOKEN>'
5
6with WebsocketClient(WS_URL, TOKEN) as ws_client:  # opens a websocket connection to Home Assistant
7    print(ws_client.get_rendered_template("{{ states('sensor.my_sensor') }}"))

 1 from datetime import datetime
 2 from homeassistant_api import Client
 3
 4 # You can also initialize Client before you use it.
 5
 6 client = Client("http://homeassistant.local:8123/api", "mylongtokenpasswordthingyfoobar")
 7
 8 # In order to activate the requests session you need to use the Client context manager like so.
 9 # Using it as a context manager will automatically close the session when you're done with it.
10 # But also will *ping* your Home Assistant instance to make sure it's running.
11 with client:
12     while True:
13         sun = client.get_entity(entity_id="sun.sun")
14         state = sun.get_state()  # Because requests are cached we reduce bandwidth usage :D
15         # Cache expires every 30 seconds by default.
16         if state.state == "below_horizon":
17             difference = datetime.now() - state.last_updated
18             print("Sun set", difference.seconds, "seconds ago.")
19             break

Services

light = client.get_domain("light")

print(light.services)
# {'turn_on': Service(service_id='turn_on', name='Turn on', description='Turn on one or more lights and adjust properties of the light, even when they are turned on already.\n', ...

changed_states = light.toggle(entity_id="light.light_bulb_1")

climate = ws_client.get_domain("climate")

print(climate.services)
# {'set_temperature': Service(service_id='set_temperature', name='Set temperature', description='Set the target temperature for a climate entity.\n', ...

changed_states = climate.set_temperature(entity_id="climate.my_thermostat", temperature=72)

Entities

entity_groups = client.get_entities()
# {'person': <Group person>, 'zone': <Group zone>, ...}

door = client.get_entity(entity_id='cover.garage_door')
# <Entity entity_id="cover.garage_door" state="<State "closed">">

states = client.get_states()
# [<State "above_horizon" entity_id="sun.sun">, <State "zoning" entity_id="zone.home">,...]

state = client.get_state('sun.sun')
# <State "above_horizon" entity_id="sun.sun">

new_state = client.set_state(
    State(state='my ToaTallY Whatever vAlUe 12t87932', entity_id='my_favorite_colors.number_one')
)
# <State "my ToaTallY Whatever vAlUe 12t87932" entity_id="my_favorite_colors.number_one">

# Alternatively you can update state from the entity class itself.
# Modify the entity's local state object, then push it to Home Assistant.
door.state.state = 'My new state'
door.state.attributes.update({'open_height': '5ft'})
door.update_state()
# <State "My new state" entity_id="cover.garage_door">

# All of these methods work with the WebsocketClient as well.

Using AsyncClient

All four client classes share the same method names. The async clients (AsyncClient and AsyncWebsocketClient) simply use async def methods that you await.

Async Services

import asyncio
from homeassistant_api import AsyncClient

async def main():
    async with AsyncClient(url, token) as client:
        domains = await client.get_domains()
        print(domains)
        # {'homeassistant': <AsyncDomain homeassistant>, 'notify': <AsyncDomain notify>}

        cover = await client.get_domain("cover")

        changed_states = await cover.close_cover(entity_id='cover.garage_door')
        # (<State "closing" entity_id="cover.garage_door">,)

asyncio.run(main())

Async Entities

entity_groups = await client.get_entities()
# {'person': <AsyncGroup person>, 'zone': <AsyncGroup zone>, ...}

door = await client.get_entity(entity_id='cover.garage_door')
# <AsyncEntity entity_id="cover.garage_door" state="<State "closed">">

states = await client.get_states()
# (<State "above_horizon" entity_id="sun.sun">, <State "zoning" entity_id="zone.home">,...)

state = await client.get_state('sun.sun')
# <State "above_horizon" entity_id="sun.sun">

new_state = await client.set_state(
    State(
        state='my ToaTallY Whatever vAlUe 12t87932',
        entity_id='my_favorite_colors.number_one'
    )
)
# <State "my ToaTallY Whatever vAlUe 12t87932" entity_id="my_favorite_colors.number_one">

# Alternatively you can update state from the entity class itself.
door.state.state = 'My new state'
door.state.attributes.update({'open_height': '5ft'})
await door.update_state()
# <State "My new state" entity_id="cover.garage_door">

Async WebSocket

The AsyncWebsocketClient works the same way:

import asyncio
from homeassistant_api import AsyncWebsocketClient

async def main():
    async with AsyncWebsocketClient(ws_url, token) as ws_client:
        template = await ws_client.get_rendered_template("{{ states('sensor.my_sensor') }}")
        print(template)

asyncio.run(main())

Using Events (Listening and Firing)

from homeassistant_api import WebsocketClient

WS_URL = '<WS API BASE URL>'  # Example: 'ws://homeassistant.local:8123/api/websocket'
TOKEN = '<LONG LIVED ACCESS TOKEN>'

with WebsocketClient(WS_URL, TOKEN) as ws_client:
    with ws_client.listen_events() as events:
        for event in events:
            print(event)

    # Or if you want to listen for a specific event type until dinner time.
    with ws_client.listen_events('state_changed') as events:
        for event in events:
            print(event)
            if event.data.entity_id == 'myalarmclock.dinner_time' and event.data.new_state.state == 'now':
                break

    # Or if you want to listen for just 10 events.
    with ws_client.listen_events("my_event") as events:
        for _, event in zip(range(10), events):
            print(event)

    # Alternatively for just one event.
    with ws_client.listen_events("my_event") as events:
        event = next(events)
        print(event)

    # Now to fire an event.
    ws_client.fire_event("my_event", my_arg="my_value")

Listening for Triggers

from homeassistant_api import WebsocketClient

with WebsocketClient(WS_URL, TOKEN) as ws_client:
    with ws_client.listen_trigger() as triggers:  # see WebsocketClient.listen_trigger for more info.
        for trigger in triggers:
            print(trigger)

    # Another more specific example, listening for event triggers.
    with ws_client.listen_trigger("event", event_type="my_event") as triggers:
        ws_client.fire_event("my_event", my_arg="my_value")

        for trigger in triggers:
            print(trigger.variables.my_arg)  # This is the value of my_arg from the event fired above.

    # Another one, listening for time triggers.
    future = ws_client.get_rendered_template(
        "{{ (now() + timedelta(seconds=1)).strftime('%H:%M:%S') }}"
    )
    with ws_client.listen_trigger("time", at=future) as triggers:  # `at` can be HH:MM or HH:MM:SS
        print(next(triggers))

What’s Next?

Browse below to learn more about what you can do with homeassistant_api.