Skip to content

Climate

climate

climate domain implementation.

SPEC module-attribute 

SPEC: DomainSpec[Climate] = register_domain(DomainSpec(name='climate', entity_cls=Climate))

The DomainSpec registered with the shared DomainRegistry.

Climate

Bases: Entity

A Home Assistant climate (thermostat / HVAC) entity.

The public API uses set_hvac_mode for all mode changes rather than exposing raw turn_on / turn_off services.

Source code in src/haclient/domains/climate.py 
 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
class Climate(Entity):
    """A Home Assistant climate (thermostat / HVAC) entity.

    The public API uses ``set_hvac_mode`` for all mode changes rather
    than exposing raw ``turn_on`` / ``turn_off`` services.
    """

    domain = "climate"

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

    def on_hvac_mode_change(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for HVAC mode changes.

        Parameters
        ----------
        func : callable
            Sync or async callable invoked with ``(old_state, new_state)``
            HVAC mode strings (e.g. ``("cool", "heat")``).

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

    def on_temperature_change(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for current temperature changes.

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

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

    def on_target_temperature_change(self, func: ValueChangeHandler) -> ValueChangeHandler:
        """Register a listener for target temperature changes.

        Parameters
        ----------
        func : callable
            Callable invoked with ``(old_value, new_value)`` whenever
            the ``temperature`` (target temperature) attribute changes.

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

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

    @property
    def current_temperature(self) -> float | None:
        """Current measured temperature, if reported."""
        value = self.attributes.get("current_temperature")
        return float(value) if isinstance(value, (int, float)) else None

    @property
    def target_temperature(self) -> float | None:
        """Current target temperature set-point."""
        value = self.attributes.get("temperature")
        return float(value) if isinstance(value, (int, float)) else None

    @property
    def hvac_mode(self) -> str:
        """Active HVAC mode (same as ``state``)."""
        return self.state

    @property
    def hvac_modes(self) -> list[str]:
        """Supported HVAC modes reported by Home Assistant."""
        modes = self.attributes.get("hvac_modes")
        return list(modes) if isinstance(modes, list) else []

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

    async def set_temperature(
        self,
        temperature: float,
        *,
        hvac_mode: str | None = None,
        **extra: Any,
    ) -> None:
        """Set the target temperature, optionally changing HVAC mode.

        Parameters
        ----------
        temperature : float
            New target temperature, in the units configured on the
            entity.
        hvac_mode : str or None, optional
            HVAC mode to switch to alongside the temperature change.
        **extra : Any
            Additional fields forwarded verbatim to Home Assistant
            (e.g. ``target_temp_high``, ``target_temp_low``).
        """
        data: dict[str, Any] = {"temperature": float(temperature), **extra}
        if hvac_mode is not None:
            data["hvac_mode"] = hvac_mode
        await self._call_service("set_temperature", data)

    async def set_hvac_mode(self, hvac_mode: str) -> None:
        """Change the HVAC mode (e.g. ``"heat"``, ``"cool"``, ``"off"``).

        Parameters
        ----------
        hvac_mode : str
            One of the modes reported by `hvac_modes`.
        """
        await self._call_service("set_hvac_mode", {"hvac_mode": hvac_mode})

    async def set_fan_mode(self, fan_mode: str) -> None:
        """Set the fan mode.

        Parameters
        ----------
        fan_mode : str
            Fan mode supported by the device (e.g. ``"auto"``,
            ``"low"``, ``"high"``).
        """
        await self._call_service("set_fan_mode", {"fan_mode": fan_mode})

current_temperature property 

current_temperature: float | None

Current measured temperature, if reported.

target_temperature property 

target_temperature: float | None

Current target temperature set-point.

hvac_mode property 

hvac_mode: str

Active HVAC mode (same as state).

hvac_modes property 

hvac_modes: list[str]

Supported HVAC modes reported by Home Assistant.

on_hvac_mode_change 

on_hvac_mode_change(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for HVAC mode changes.

Parameters:

Name Type Description Default
func callable

Sync or async callable invoked with (old_state, new_state) HVAC mode strings (e.g. ("cool", "heat")).

 required

Returns:

Type Description
callable

The same func, returned for decorator use.
Source code in src/haclient/domains/climate.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def on_hvac_mode_change(self, func: ValueChangeHandler) -> ValueChangeHandler:
    """Register a listener for HVAC mode changes.

    Parameters
    ----------
    func : callable
        Sync or async callable invoked with ``(old_state, new_state)``
        HVAC mode strings (e.g. ``("cool", "heat")``).

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

on_temperature_change 

on_temperature_change(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for current temperature changes.

Parameters:

Name Type Description Default
func callable

Callable invoked with (old_value, new_value) whenever the current_temperature attribute changes.

 required

Returns:

Type Description
callable

The same func, returned for decorator use.
Source code in src/haclient/domains/climate.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def on_temperature_change(self, func: ValueChangeHandler) -> ValueChangeHandler:
    """Register a listener for current temperature changes.

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

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

on_target_temperature_change 

on_target_temperature_change(func: ValueChangeHandler) -> ValueChangeHandler

Register a listener for target temperature changes.

Parameters:

Name Type Description Default
func callable

Callable invoked with (old_value, new_value) whenever the temperature (target temperature) attribute changes.

 required

Returns:

Type Description
callable

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

    Parameters
    ----------
    func : callable
        Callable invoked with ``(old_value, new_value)`` whenever
        the ``temperature`` (target temperature) attribute changes.

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

set_temperature async 

set_temperature(temperature: float, *, hvac_mode: str | None = None, **extra: Any) -> None

Set the target temperature, optionally changing HVAC mode.

Parameters:

Name Type Description Default
temperature float

New target temperature, in the units configured on the entity.

 required
hvac_mode str or None

HVAC mode to switch to alongside the temperature change.

 None
**extra Any

Additional fields forwarded verbatim to Home Assistant (e.g. target_temp_high, target_temp_low).

 {}
Source code in src/haclient/domains/climate.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
async def set_temperature(
    self,
    temperature: float,
    *,
    hvac_mode: str | None = None,
    **extra: Any,
) -> None:
    """Set the target temperature, optionally changing HVAC mode.

    Parameters
    ----------
    temperature : float
        New target temperature, in the units configured on the
        entity.
    hvac_mode : str or None, optional
        HVAC mode to switch to alongside the temperature change.
    **extra : Any
        Additional fields forwarded verbatim to Home Assistant
        (e.g. ``target_temp_high``, ``target_temp_low``).
    """
    data: dict[str, Any] = {"temperature": float(temperature), **extra}
    if hvac_mode is not None:
        data["hvac_mode"] = hvac_mode
    await self._call_service("set_temperature", data)

set_hvac_mode async 

set_hvac_mode(hvac_mode: str) -> None

Change the HVAC mode (e.g. "heat", "cool", "off").

Parameters:

Name Type Description Default
hvac_mode str

One of the modes reported by hvac_modes.

 required
Source code in src/haclient/domains/climate.py 
122
123
124
125
126
127
128
129
130
async def set_hvac_mode(self, hvac_mode: str) -> None:
    """Change the HVAC mode (e.g. ``"heat"``, ``"cool"``, ``"off"``).

    Parameters
    ----------
    hvac_mode : str
        One of the modes reported by `hvac_modes`.
    """
    await self._call_service("set_hvac_mode", {"hvac_mode": hvac_mode})

set_fan_mode async 

set_fan_mode(fan_mode: str) -> None

Set the fan mode.

Parameters:

Name Type Description Default
fan_mode str

Fan mode supported by the device (e.g. "auto", "low", "high").

 required
Source code in src/haclient/domains/climate.py 
132
133
134
135
136
137
138
139
140
141
async def set_fan_mode(self, fan_mode: str) -> None:
    """Set the fan mode.

    Parameters
    ----------
    fan_mode : str
        Fan mode supported by the device (e.g. ``"auto"``,
        ``"low"``, ``"high"``).
    """
    await self._call_service("set_fan_mode", {"fan_mode": fan_mode})