Skip to content

Switch

switch

switch domain implementation.

SPEC module-attribute 

SPEC: DomainSpec[Switch] = register_domain(DomainSpec(name='switch', entity_cls=Switch))

The DomainSpec registered with the shared DomainRegistry.

Switch

Bases: Entity

A Home Assistant switch entity.

Switches are binary devices that can be turned on or off. The public API uses on() / off() / toggle() as intent-specific names rather than the raw HA turn_on / turn_off service names.

Source code in src/haclient/domains/switch.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 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
class Switch(Entity):
    """A Home Assistant switch entity.

    Switches are binary devices that can be turned on or off. The public
    API uses ``on()`` / ``off()`` / ``toggle()`` as intent-specific names
    rather than the raw HA ``turn_on`` / ``turn_off`` service names.
    """

    domain = "switch"

    # -- Listener decorators ------------------------------------------

    def on_turn_on(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for when the switch turns on.

        Parameters
        ----------
        func : callable
            Sync or async callable invoked with ``(old_state, new_state)``
            on every transition into the ``on`` state.

        Returns
        -------
        callable
            The same *func*, returned for decorator use.
        """
        return self._register_state_transition_listener("on", func)

    def on_turn_off(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for when the switch turns off.

        Parameters
        ----------
        func : callable
            Sync or async callable invoked with ``(old_state, new_state)``
            on every transition into the ``off`` state.

        Returns
        -------
        callable
            The same *func*, returned for decorator use.
        """
        return self._register_state_transition_listener("off", func)

    # -- State properties ---------------------------------------------

    @property
    def is_on(self) -> bool:
        """Whether the switch is currently on.

        Returns
        -------
        bool
            ``True`` when the cached entity ``state`` is exactly
            ``"on"``; ``False`` for ``"off"`` and any unknown,
            unavailable, or transitional value.
        """
        return self.state == "on"

    # -- Actions ------------------------------------------------------

    async def on(self) -> None:
        """Activate the switch.

        Invokes the ``switch.turn_on`` Home Assistant service via the
        configured routing policy (REST or WebSocket).

        Raises
        ------
        CommandError
            If Home Assistant rejects the service call (WebSocket path).
        HTTPError
            If the REST call returns a non-2xx response (REST path).
        TimeoutError
            If the call exceeds the configured request timeout.
        ConnectionClosedError
            If the WebSocket disconnects mid-call.
        """
        await self._call_service("turn_on")

    async def off(self) -> None:
        """Deactivate the switch.

        Invokes the ``switch.turn_off`` Home Assistant service.

        Raises
        ------
        CommandError
            If Home Assistant rejects the service call.
        HTTPError
            If the REST call returns a non-2xx response.
        TimeoutError
            If the call exceeds the configured request timeout.
        ConnectionClosedError
            If the WebSocket disconnects mid-call.
        """
        await self._call_service("turn_off")

    async def toggle(self) -> None:
        """Toggle the switch state.

        Invokes the ``switch.toggle`` Home Assistant service.

        Raises
        ------
        CommandError
            If Home Assistant rejects the service call.
        HTTPError
            If the REST call returns a non-2xx response.
        TimeoutError
            If the call exceeds the configured request timeout.
        ConnectionClosedError
            If the WebSocket disconnects mid-call.
        """
        await self._call_service("toggle")

is_on property 

is_on: bool

Whether the switch is currently on.

Returns:

Type Description
bool

True when the cached entity state is exactly "on"; False for "off" and any unknown, unavailable, or transitional value.

on_turn_on 

on_turn_on(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for when the switch turns on.

Parameters:

Name Type Description Default
func callable

Sync or async callable invoked with (old_state, new_state) on every transition into the on state.

 required

Returns:

Type Description
callable

The same func, returned for decorator use.
Source code in src/haclient/domains/switch.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
def on_turn_on(self, func: ValueChangeHandler) -> ValueChangeHandler:
    """Register a listener for when the switch turns on.

    Parameters
    ----------
    func : callable
        Sync or async callable invoked with ``(old_state, new_state)``
        on every transition into the ``on`` state.

    Returns
    -------
    callable
        The same *func*, returned for decorator use.
    """
    return self._register_state_transition_listener("on", func)

on_turn_off 

on_turn_off(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for when the switch turns off.

Parameters:

Name Type Description Default
func callable

Sync or async callable invoked with (old_state, new_state) on every transition into the off state.

 required

Returns:

Type Description
callable

The same func, returned for decorator use.
Source code in src/haclient/domains/switch.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def on_turn_off(self, func: ValueChangeHandler) -> ValueChangeHandler:
    """Register a listener for when the switch turns off.

    Parameters
    ----------
    func : callable
        Sync or async callable invoked with ``(old_state, new_state)``
        on every transition into the ``off`` state.

    Returns
    -------
    callable
        The same *func*, returned for decorator use.
    """
    return self._register_state_transition_listener("off", func)

on async 

on() -> None

Activate the switch.

Invokes the switch.turn_on Home Assistant service via the configured routing policy (REST or WebSocket).

Raises:

Type Description
CommandError

If Home Assistant rejects the service call (WebSocket path).
HTTPError

If the REST call returns a non-2xx response (REST path).
TimeoutError

If the call exceeds the configured request timeout.
ConnectionClosedError

If the WebSocket disconnects mid-call.
Source code in src/haclient/domains/switch.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
async def on(self) -> None:
    """Activate the switch.

    Invokes the ``switch.turn_on`` Home Assistant service via the
    configured routing policy (REST or WebSocket).

    Raises
    ------
    CommandError
        If Home Assistant rejects the service call (WebSocket path).
    HTTPError
        If the REST call returns a non-2xx response (REST path).
    TimeoutError
        If the call exceeds the configured request timeout.
    ConnectionClosedError
        If the WebSocket disconnects mid-call.
    """
    await self._call_service("turn_on")

off async 

off() -> None

Deactivate the switch.

Invokes the switch.turn_off Home Assistant service.

Raises:

Type Description
CommandError

If Home Assistant rejects the service call.
HTTPError

If the REST call returns a non-2xx response.
TimeoutError

If the call exceeds the configured request timeout.
ConnectionClosedError

If the WebSocket disconnects mid-call.
Source code in src/haclient/domains/switch.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
async def off(self) -> None:
    """Deactivate the switch.

    Invokes the ``switch.turn_off`` Home Assistant service.

    Raises
    ------
    CommandError
        If Home Assistant rejects the service call.
    HTTPError
        If the REST call returns a non-2xx response.
    TimeoutError
        If the call exceeds the configured request timeout.
    ConnectionClosedError
        If the WebSocket disconnects mid-call.
    """
    await self._call_service("turn_off")

toggle async 

toggle() -> None

Toggle the switch state.

Invokes the switch.toggle Home Assistant service.

Raises:

Type Description
CommandError

If Home Assistant rejects the service call.
HTTPError

If the REST call returns a non-2xx response.
TimeoutError

If the call exceeds the configured request timeout.
ConnectionClosedError

If the WebSocket disconnects mid-call.
Source code in src/haclient/domains/switch.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
async def toggle(self) -> None:
    """Toggle the switch state.

    Invokes the ``switch.toggle`` Home Assistant service.

    Raises
    ------
    CommandError
        If Home Assistant rejects the service call.
    HTTPError
        If the REST call returns a non-2xx response.
    TimeoutError
        If the call exceeds the configured request timeout.
    ConnectionClosedError
        If the WebSocket disconnects mid-call.
    """
    await self._call_service("toggle")