Skip to content

Cover

cover

cover domain implementation.

SPEC module-attribute 

SPEC: DomainSpec[Cover] = register_domain(DomainSpec(name='cover', entity_cls=Cover))

The DomainSpec registered with the shared DomainRegistry.

Cover

Bases: Entity

A Home Assistant cover (blind/garage/shade) entity.

Uses intent-specific names (open, close, stop, set_position) rather than raw HA service names.

Source code in src/haclient/domains/cover.py 
 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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
class Cover(Entity):
    """A Home Assistant cover (blind/garage/shade) entity.

    Uses intent-specific names (``open``, ``close``, ``stop``,
    ``set_position``) rather than raw HA service names.
    """

    domain = "cover"

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

    def on_open(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for when the cover opens.

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

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

    def on_close(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for when the cover closes.

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

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

    def on_position_change(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for position changes.

        Parameters
        ----------
        func : callable
            Callable invoked with ``(old_value, new_value)`` whenever
            the ``current_position`` attribute (0-100) changes.

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

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

    @property
    def is_open(self) -> bool:
        """Whether the cover is currently open."""
        return self.state == "open"

    @property
    def is_closed(self) -> bool:
        """Whether the cover is currently closed."""
        return self.state == "closed"

    @property
    def current_position(self) -> int | None:
        """Current position (0--100) or ``None`` if unsupported."""
        value = self.attributes.get("current_position")
        return int(value) if isinstance(value, (int, float)) else None

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

    async def open(self) -> None:
        """Open the cover fully.

        Invokes the ``cover.open_cover`` 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("open_cover")

    async def close(self) -> None:
        """Close the cover fully.

        Invokes the ``cover.close_cover`` 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("close_cover")

    async def stop(self) -> None:
        """Stop movement of the cover.

        Invokes the ``cover.stop_cover`` 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("stop_cover")

    async def set_position(self, position: int) -> None:
        """Set the cover position (0 = closed, 100 = open).

        Parameters
        ----------
        position : int
            Target position in the range 0--100. ``0`` is fully
            closed; ``100`` is fully open.

        Raises
        ------
        ValueError
            If *position* is outside the 0--100 range.
        """
        await self._call_service(
            "set_cover_position",
            {"position": validate_range(position, 0, 100, "position")},
        )

    async def toggle(self) -> None:
        """Toggle open/close state.

        Invokes the ``cover.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_open property 

is_open: bool

Whether the cover is currently open.

is_closed property 

is_closed: bool

Whether the cover is currently closed.

current_position property 

current_position: int | None

Current position (0--100) or None if unsupported.

on_open 

on_open(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for when the cover opens.

Parameters:

Name Type Description Default
func callable

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

 required

Returns:

Type Description
callable

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

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

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

on_close 

on_close(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for when the cover closes.

Parameters:

Name Type Description Default
func callable

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

 required

Returns:

Type Description
callable

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

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

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

on_position_change 

on_position_change(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for position changes.

Parameters:

Name Type Description Default
func callable

Callable invoked with (old_value, new_value) whenever the current_position attribute (0-100) changes.

 required

Returns:

Type Description
callable

The same func, returned for decorator use.
Source code in src/haclient/domains/cover.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def on_position_change(self, func: ValueChangeHandler) -> ValueChangeHandler:
    """Register a listener for position changes.

    Parameters
    ----------
    func : callable
        Callable invoked with ``(old_value, new_value)`` whenever
        the ``current_position`` attribute (0-100) changes.

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

open async 

open() -> None

Open the cover fully.

Invokes the cover.open_cover 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/cover.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
async def open(self) -> None:
    """Open the cover fully.

    Invokes the ``cover.open_cover`` 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("open_cover")

close async 

close() -> None

Close the cover fully.

Invokes the cover.close_cover 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/cover.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
async def close(self) -> None:
    """Close the cover fully.

    Invokes the ``cover.close_cover`` 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("close_cover")

stop async 

stop() -> None

Stop movement of the cover.

Invokes the cover.stop_cover 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/cover.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
async def stop(self) -> None:
    """Stop movement of the cover.

    Invokes the ``cover.stop_cover`` 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("stop_cover")

set_position async 

set_position(position: int) -> None

Set the cover position (0 = closed, 100 = open).

Parameters:

Name Type Description Default
position int

Target position in the range 0--100. 0 is fully closed; 100 is fully open.

 required

Raises:

Type Description
ValueError

If position is outside the 0--100 range.
Source code in src/haclient/domains/cover.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
async def set_position(self, position: int) -> None:
    """Set the cover position (0 = closed, 100 = open).

    Parameters
    ----------
    position : int
        Target position in the range 0--100. ``0`` is fully
        closed; ``100`` is fully open.

    Raises
    ------
    ValueError
        If *position* is outside the 0--100 range.
    """
    await self._call_service(
        "set_cover_position",
        {"position": validate_range(position, 0, 100, "position")},
    )

toggle async 

toggle() -> None

Toggle open/close state.

Invokes the cover.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/cover.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
async def toggle(self) -> None:
    """Toggle open/close state.

    Invokes the ``cover.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")