Skip to content

Configuration

config

Configuration objects for HAClient.

The connection settings and URL handling are captured in ConnectionConfig. This isolates configuration parsing from the rest of the package and keeps HAClient.__init__ boring.

ServicePolicy module-attribute 

ServicePolicy = Literal['ws', 'rest', 'auto']

How ServiceCaller should choose between WebSocket and REST.

  • "ws" — always use the WebSocket. Fails if the WS is not connected.
  • "rest" — always use REST.
  • "auto" — prefer WebSocket when connected, otherwise fall back to REST.

ConnectionConfig dataclass

Immutable bundle of settings consumed by infrastructure adapters.

Attributes:

Name Type Description
base_url str

Home Assistant base URL (without trailing slash).
token str

Long-lived access token.
ws_url str

Fully-qualified WebSocket URL.
reconnect bool

Whether the WebSocket should reconnect automatically.
ping_interval float

Seconds between WebSocket keepalive pings (0 disables them).
request_timeout float

Default timeout for individual REST and WS requests.
verify_ssl bool

Verify TLS certificates.
service_policy ServicePolicy

Default routing policy used by ServiceCaller.
Source code in src/haclient/config.py 
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
@dataclass(frozen=True)
class ConnectionConfig:
    """Immutable bundle of settings consumed by infrastructure adapters.

    Attributes
    ----------
    base_url : str
        Home Assistant base URL (without trailing slash).
    token : str
        Long-lived access token.
    ws_url : str
        Fully-qualified WebSocket URL.
    reconnect : bool
        Whether the WebSocket should reconnect automatically.
    ping_interval : float
        Seconds between WebSocket keepalive pings (``0`` disables them).
    request_timeout : float
        Default timeout for individual REST and WS requests.
    verify_ssl : bool
        Verify TLS certificates.
    service_policy : ServicePolicy
        Default routing policy used by `ServiceCaller`.
    """

    base_url: str
    token: str
    ws_url: str
    reconnect: bool = True
    ping_interval: float = 30.0
    request_timeout: float = 30.0
    verify_ssl: bool = True
    service_policy: ServicePolicy = "auto"

    @classmethod
    def from_url(
        cls,
        base_url: str,
        token: str,
        *,
        ws_url: str | None = None,
        reconnect: bool = True,
        ping_interval: float = 30.0,
        request_timeout: float = 30.0,
        verify_ssl: bool = True,
        service_policy: ServicePolicy = "auto",
    ) -> ConnectionConfig:
        """Build a `ConnectionConfig` from a base URL.

        Parameters
        ----------
        base_url : str
            Home Assistant base URL (e.g. ``http://localhost:8123``).
        token : str
            Long-lived access token.
        ws_url : str or None, optional
            Explicit WebSocket URL. Derived from *base_url* when omitted.
        reconnect : bool, optional
            Whether the WebSocket should reconnect automatically.
        ping_interval : float, optional
            Seconds between keepalive pings.
        request_timeout : float, optional
            Default timeout for WebSocket / REST operations.
        verify_ssl : bool, optional
            Verify TLS certificates.
        service_policy : ServicePolicy, optional
            How service calls choose between WebSocket and REST.

        Returns
        -------
        ConnectionConfig
            The fully-resolved configuration object.
        """
        normalised = base_url.rstrip("/")
        return cls(
            base_url=normalised,
            token=token,
            ws_url=ws_url or derive_ws_url(normalised),
            reconnect=reconnect,
            ping_interval=ping_interval,
            request_timeout=request_timeout,
            verify_ssl=verify_ssl,
            service_policy=service_policy,
        )

from_url classmethod 

from_url(base_url: str, token: str, *, ws_url: str | None = None, reconnect: bool = True, ping_interval: float = 30.0, request_timeout: float = 30.0, verify_ssl: bool = True, service_policy: ServicePolicy = 'auto') -> ConnectionConfig

Build a ConnectionConfig from a base URL.

Parameters:

Name Type Description Default
base_url str

Home Assistant base URL (e.g. http://localhost:8123).

 required
token str

Long-lived access token.

 required
ws_url str or None

Explicit WebSocket URL. Derived from base_url when omitted.

 None
reconnect bool

Whether the WebSocket should reconnect automatically.

 True
ping_interval float

Seconds between keepalive pings.

 30.0
request_timeout float

Default timeout for WebSocket / REST operations.

 30.0
verify_ssl bool

Verify TLS certificates.

 True
service_policy ServicePolicy

How service calls choose between WebSocket and REST.

 'auto'

Returns:

Type Description
ConnectionConfig

The fully-resolved configuration object.
Source code in src/haclient/config.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
@classmethod
def from_url(
    cls,
    base_url: str,
    token: str,
    *,
    ws_url: str | None = None,
    reconnect: bool = True,
    ping_interval: float = 30.0,
    request_timeout: float = 30.0,
    verify_ssl: bool = True,
    service_policy: ServicePolicy = "auto",
) -> ConnectionConfig:
    """Build a `ConnectionConfig` from a base URL.

    Parameters
    ----------
    base_url : str
        Home Assistant base URL (e.g. ``http://localhost:8123``).
    token : str
        Long-lived access token.
    ws_url : str or None, optional
        Explicit WebSocket URL. Derived from *base_url* when omitted.
    reconnect : bool, optional
        Whether the WebSocket should reconnect automatically.
    ping_interval : float, optional
        Seconds between keepalive pings.
    request_timeout : float, optional
        Default timeout for WebSocket / REST operations.
    verify_ssl : bool, optional
        Verify TLS certificates.
    service_policy : ServicePolicy, optional
        How service calls choose between WebSocket and REST.

    Returns
    -------
    ConnectionConfig
        The fully-resolved configuration object.
    """
    normalised = base_url.rstrip("/")
    return cls(
        base_url=normalised,
        token=token,
        ws_url=ws_url or derive_ws_url(normalised),
        reconnect=reconnect,
        ping_interval=ping_interval,
        request_timeout=request_timeout,
        verify_ssl=verify_ssl,
        service_policy=service_policy,
    )

derive_ws_url 

derive_ws_url(base_url: str) -> str

Derive the Home Assistant WebSocket URL from a base HTTP URL.

Parameters:

Name Type Description Default
base_url str

Base URL such as http://homeassistant.local:8123 (with or without a trailing slash, optionally with a path prefix).

 required

Returns:

Type Description
str

The fully-qualified WebSocket URL ending with /api/websocket.
Source code in src/haclient/config.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def derive_ws_url(base_url: str) -> str:
    """Derive the Home Assistant WebSocket URL from a base HTTP URL.

    Parameters
    ----------
    base_url : str
        Base URL such as ``http://homeassistant.local:8123`` (with or
        without a trailing slash, optionally with a path prefix).

    Returns
    -------
    str
        The fully-qualified WebSocket URL ending with ``/api/websocket``.
    """
    parsed = urlparse(base_url)
    scheme_map = {"http": "ws", "https": "wss", "ws": "ws", "wss": "wss"}
    scheme = scheme_map.get(parsed.scheme, "ws")
    path = parsed.path.rstrip("/") + "/api/websocket"
    return urlunparse((scheme, parsed.netloc, path, "", "", ""))