Skip to content

HaClient Mission Statement

Jump to bottom
Faerkeren edited this page Apr 26, 2026 · 1 revision

Mission Statement

HaClient is a high-level Python client library for Home Assistant.

It is built on top of the official Home Assistant REST and WebSocket APIs. Because these APIs do not provide versioning guarantees, compatibility must be treated as a best-effort concern. HaClient is responsible for detecting capability differences and handling them gracefully without breaking user code.

The purpose of HaClient is to provide a clean, intuitive, and predictable abstraction over the complexity and inconsistencies of the Home Assistant API.

HaClient does not aim to mirror the API—it aims to improve it.

All implementation must prioritize usability, consistency, and alignment with how users expect Home Assistant entities to behave.

Where the Home Assistant API is well-designed, HaClient should follow it closely. Where the API is inconsistent or unintuitive, HaClient must correct it through better abstractions.

Design Principles

  • Consistency over API fidelity A consistent interface is more important than strict adherence to the underlying API.
  • Capability-driven behavior Features must be dynamically adapted based on what the Home Assistant instance supports.
  • Explicit over implicit Actions should be clearly expressed as methods or properties, not hidden behind generic service calls.
  • Graceful degradation Missing or unsupported features must not cause failures; they should degrade predictably.
  • Pythonic interface The library must feel natural to Python developers, not like a wrapped HTTP API.

⸻

Intuitive Examples

These domains are already conceptually clean and should map closely to their Home Assistant counterparts:

  • Light
  • Lock
  • Media Player
  • Scene
  • Sensor
  • Switch

Unintuitive Areas

Unintuitive Example 1: Domain Inconsistencies

Some domains (e.g. number, select, text) expose behavior that does not align with their conceptual purpose or differs in structure compared to similar entities.

HaClient must normalize these into predictable interfaces.

Unintuitive Example 2: Overloaded Service Calls

The Home Assistant API uses turn_on for multiple responsibilities:

  • Turning on a device
  • Adjusting brightness
  • Changing color or temperature

While this is flexible, it is not intuitive.

HaClient must separate these concerns into explicit operations:

  • light.on()
  • light.set_brightness()
  • light.set_color()
  • light.set_temperature()

The underlying service call remains the same, but the interface must reflect intent.

Scope of Responsibility

HaClient is responsible for:

  • Mapping entities to strongly-typed Python objects
  • Abstracting service calls into meaningful methods
  • Normalizing inconsistent domain behaviors
  • Handling transport (REST/WebSocket) transparently
  • Managing state updates and subscriptions
  • Detecting and adapting to feature availability

HaClient is not responsible for:

  • Replacing Home Assistant logic
  • Hiding all complexity at the cost of control
  • Enforcing a rigid model where flexibility is required

Priority of Implementation

Priority 1 (Core Domains)

These domains define the baseline usability of the library:

  • Light
  • Lock
  • Media Player
  • Scene
  • Sensor
  • Switch
  • Valve
  • Weather
  • Button
  • Climate
  • Cover
  • Date/Time
  • Binary Sensor

Priority 2 (Extended Control)

  • Air Quality
  • Number
  • Vacuum
  • Event
  • Fan

Priority 3 (Long Tail / Specialized Domains)

  • AI Task
  • Alarm Control Panel
  • Assist Satellite
  • Calendar
  • Camera
  • Conversation
  • Date
  • Device Tracker
  • Geolocation
  • Humidifier
  • Image
  • Image Processing
  • Infrared
  • Lawn Mower
  • Notifications
  • Remote
  • Select
  • Siren
  • Speech-to-Text (STT)
  • Tags
  • Text
  • Time
  • To-do List
  • Text-to-Speech (TTS)
  • Update
  • Wake-word Detection
  • Water Heater

Clone this wiki locally