ha-async-patterns

Async Python Patterns in Home Assistant

Home Assistant runs on a single-threaded asyncio event loop. All I/O must be non-blocking. Blocking the loop freezes automations, the UI, and entity updates.

Pattern 1: Async Libraries (Preferred)

import aiohttp

async def async_get_data(self) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(f"http://{self._host}/api") as response:
            response.raise_for_status()
            return await response.json()

Pattern 2: Wrapping Sync Libraries

When no async library exists:

import requests

async def async_get_data(self) -> dict:
    return await self.hass.async_add_executor_job(self._sync_get_data)

def _sync_get_data(self) -> dict:
    response = requests.get(f"http://{self._host}/api", timeout=10)
    response.raise_for_status()
    return response.json()

With arguments:

# Positional args after callable (forwarded positionally — async_add_executor_job
# cannot pass keyword args, so options like timeout/headers need functools.partial)
result = await hass.async_add_executor_job(requests.get, url)

# Keyword args with functools.partial
from functools import partial
result = await hass.async_add_executor_job(
    partial(requests.get, url, timeout=10, headers=headers)
)

Pattern 3: Callbacks vs Coroutines

from homeassistant.core import callback

# @callback = sync, runs on event loop, NO I/O allowed
@callback
def _handle_coordinator_update(self) -> None:
    self._attr_native_value = self.coordinator.data.get("value")
    self.async_write_ha_state()

# async = coroutine, CAN do I/O
async def async_turn_on(self, **kwargs) -> None:
    await self.coordinator.client.async_set_state(True)
    await self.coordinator.async_request_refresh()

Pattern 4: Timeouts

import asyncio

from homeassistant.helpers.update_coordinator import UpdateFailed

async def async_get_data(self) -> dict:
    try:
        async with asyncio.timeout(10):
            return await self.client.async_get_data()
    except TimeoutError:
        raise UpdateFailed("Request timed out")