Guides

These guides walk through common HaClient workflows. They focus on how to use the client effectively rather than enumerating every parameter — see the API Reference for that.

Getting started

• Async lifecycle and state priming — how HAClient connects, primes its cache, and shuts down cleanly.
• Sync wrapper — when and how to use SyncHAClient from scripts, the REPL, or Jupyter.

Reacting to state

• State and value listeners — the two listener tiers, decorator patterns, and removal.
• Reconnect and disconnect handling — what survives reconnects automatically and what you need to wire up yourself.

Extending the client

• Custom domains and plugins — adding a new domain in-process or via the haclient.domains entry point.
• Service routing (advanced) — when to drop to raw services.call(...) and what prefer="ws" | "rest" | "auto" actually does.

Domain workflows

• Light
• Switch
• Climate
• Cover
• Media Player
• Scene
• Timer
• Sensor

Design philosophy

HaClient is not a thin wrapper over the Home Assistant REST and WebSocket APIs. It deliberately reshapes them into something more consistent and more Pythonic:

• Use the high-level domain methods (light.set_brightness(...), cover.set_position(...), media_player.play()) as the normal path. They normalise domain quirks, validate inputs, and pick the right transport.
• Drop to client.services.call(...) only for services that no domain method covers, or when you need very specific routing.
• Map entity events to domain-specific listener decorators (@light.on_brightness_change, @timer.on_finished) before reaching for the generic on_state_change.