Merge pull request #66 from graphras-com/feat/air-quality-domain

feat(domains): add AirQuality domain (#34)

Author: Faerkeren

src/haclient/domains/__init__.py

@@ -5,6 +5,7 @@
 unavailable; this is the basis for opt-in / opt-out loading.
 """
 
+from haclient.domains.air_quality import AirQuality
 from haclient.domains.binary_sensor import BinarySensor
 from haclient.domains.climate import Climate
 from haclient.domains.cover import Cover
@@ -19,6 +20,7 @@
 from haclient.domains.valve import Valve
 
 __all__ = [
+    "AirQuality",
     "BinarySensor",
     "Climate",
     "Cover",

src/haclient/domains/air_quality.py

@@ -0,0 +1,173 @@
+"""``air_quality`` domain implementation (read-only)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from haclient.core.plugins import DomainSpec, register_domain
+from haclient.entity.base import Entity
+
+
+def _coerce_numeric(value: Any) -> float | int | None:
+    """Coerce an air-quality attribute value to a number.
+
+    Parameters
+    ----------
+    value : Any
+        Raw attribute value from Home Assistant.
+
+    Returns
+    -------
+    float, int, or None
+        ``int`` when the value is an integer literal, ``float`` for any
+        other numeric value (including numeric strings), and ``None``
+        when the value is missing, non-numeric, or one of HA's sentinel
+        unavailability strings.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        # bool is a subclass of int; treat it as not a real measurement.
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return value
+    if isinstance(value, str):
+        if value in ("unknown", "unavailable", ""):
+            return None
+        try:
+            return float(value)
+        except ValueError:
+            return None
+    return None
+
+
+class AirQuality(Entity):
+    """A read-only Home Assistant air quality entity.
+
+    Exposes typed properties for the pollutant metrics the underlying
+    integration chooses to report. Every metric returns ``None`` when
+    the sensor does not provide that reading, so unsupported metrics
+    degrade silently rather than raising. The entity is read-only; the
+    HA ``air_quality`` domain exposes no service actions.
+
+    The Home Assistant ``air_quality`` platform reports its overall Air
+    Quality Index (AQI) as the entity *state* and individual pollutants
+    as attributes. `air_quality_index` therefore prefers an explicit
+    ``air_quality_index`` attribute when present and falls back to the
+    state string. All other metrics are read directly from attributes.
+    """
+
+    domain = "air_quality"
+
+    # -- Listener decorators ------------------------------------------
+
+    def on_aqi_change(self, func: Any) -> Any:
+        """Register a listener for Air Quality Index changes.
+
+        Fires whenever the entity *state* string changes, which mirrors
+        the HA convention of reporting the AQI as the entity state.
+
+        Parameters
+        ----------
+        func : callable
+            Sync or async callable receiving ``(old_state, new_state)``.
+
+        Returns
+        -------
+        callable
+            The same *func*, returned for decorator use.
+        """
+        return self._register_state_value_listener(func)
+
+    def on_pm25_change(self, func: Any) -> Any:
+        """Register a listener for PM2.5 attribute changes.
+
+        Parameters
+        ----------
+        func : callable
+            Callable receiving ``(old_value, new_value)`` for the
+            ``particulate_matter_2_5`` attribute.
+
+        Returns
+        -------
+        callable
+            The same *func*, returned for decorator use.
+        """
+        return self._register_attr_listener("particulate_matter_2_5", func)
+
+    def on_co2_change(self, func: Any) -> Any:
+        """Register a listener for CO2 attribute changes.
+
+        Parameters
+        ----------
+        func : callable
+            Callable receiving ``(old_value, new_value)`` for the
+            ``carbon_dioxide`` attribute.
+
+        Returns
+        -------
+        callable
+            The same *func*, returned for decorator use.
+        """
+        return self._register_attr_listener("carbon_dioxide", func)
+
+    # -- State properties ---------------------------------------------
+
+    @property
+    def air_quality_index(self) -> float | int | None:
+        """Overall Air Quality Index, if reported.
+
+        Returns
+        -------
+        float, int, or None
+            The explicit ``air_quality_index`` attribute when present,
+            otherwise the numeric coercion of the entity state, or
+            ``None`` when neither yields a number.
+        """
+        explicit = _coerce_numeric(self.attributes.get("air_quality_index"))
+        if explicit is not None:
+            return explicit
+        return _coerce_numeric(self.state)
+
+    @property
+    def particulate_matter_2_5(self) -> float | int | None:
+        """PM2.5 reading, typically in µg/m³."""
+        return _coerce_numeric(self.attributes.get("particulate_matter_2_5"))
+
+    @property
+    def particulate_matter_10(self) -> float | int | None:
+        """PM10 reading, typically in µg/m³."""
+        return _coerce_numeric(self.attributes.get("particulate_matter_10"))
+
+    @property
+    def carbon_dioxide(self) -> float | int | None:
+        """CO2 concentration, typically in ppm."""
+        return _coerce_numeric(self.attributes.get("carbon_dioxide"))
+
+    @property
+    def carbon_monoxide(self) -> float | int | None:
+        """CO concentration, typically in ppm."""
+        return _coerce_numeric(self.attributes.get("carbon_monoxide"))
+
+    @property
+    def volatile_organic_compounds(self) -> float | int | None:
+        """Volatile organic compound concentration, if reported."""
+        return _coerce_numeric(self.attributes.get("volatile_organic_compounds"))
+
+    @property
+    def nitrogen_dioxide(self) -> float | int | None:
+        """NO2 concentration, if reported."""
+        return _coerce_numeric(self.attributes.get("nitrogen_dioxide"))
+
+    @property
+    def ozone(self) -> float | int | None:
+        """Ozone concentration, if reported."""
+        return _coerce_numeric(self.attributes.get("ozone"))
+
+
+SPEC: DomainSpec[AirQuality] = register_domain(
+    DomainSpec(name="air_quality", entity_cls=AirQuality)
+)
+"""The `DomainSpec` registered with the shared `DomainRegistry`."""

tests/test_domains.py

@@ -985,3 +985,138 @@ def _mode(old: Any, new: Any) -> None:
     assert turned_off == [("on", "off")]
     assert humidity_events == [(40, 55)]
     assert mode_events == [("auto", "sleep")]
+
+
+# ---------------------------------------------------------------------------
+# Air quality
+# ---------------------------------------------------------------------------
+
+
+async def test_air_quality_full_metrics() -> None:
+    """Every typed metric is read from its underlying attribute."""
+    ha = HAClient.from_url("http://x", token="t", load_plugins=False)
+    try:
+        aq = ha.air_quality("bedroom")
+        aq._apply_state(
+            {
+                "state": "42",
+                "attributes": {
+                    "particulate_matter_2_5": 12.3,
+                    "particulate_matter_10": 20,
+                    "carbon_dioxide": 800,
+                    "carbon_monoxide": 1.5,
+                    "volatile_organic_compounds": 0.4,
+                    "nitrogen_dioxide": 5,
+                    "ozone": 18.0,
+                },
+            }
+        )
+        # AQI falls back to the state when no explicit attribute is set.
+        assert aq.air_quality_index == 42.0
+        assert aq.particulate_matter_2_5 == 12.3
+        assert aq.particulate_matter_10 == 20
+        assert aq.carbon_dioxide == 800
+        assert aq.carbon_monoxide == 1.5
+        assert aq.volatile_organic_compounds == 0.4
+        assert aq.nitrogen_dioxide == 5
+        assert aq.ozone == 18.0
+    finally:
+        await ha.close()
+
+
+async def test_air_quality_degrades_when_metrics_missing() -> None:
+    """Unsupported metrics return ``None`` rather than raising."""
+    ha = HAClient.from_url("http://x", token="t", load_plugins=False)
+    try:
+        aq = ha.air_quality("minimal")
+        aq._apply_state({"state": "unknown", "attributes": {}})
+        assert aq.air_quality_index is None
+        assert aq.particulate_matter_2_5 is None
+        assert aq.particulate_matter_10 is None
+        assert aq.carbon_dioxide is None
+        assert aq.carbon_monoxide is None
+        assert aq.volatile_organic_compounds is None
+        assert aq.nitrogen_dioxide is None
+        assert aq.ozone is None
+    finally:
+        await ha.close()
+
+
+async def test_air_quality_index_prefers_explicit_attribute() -> None:
+    """An explicit ``air_quality_index`` attribute overrides the state."""
+    ha = HAClient.from_url("http://x", token="t", load_plugins=False)
+    try:
+        aq = ha.air_quality("outdoor")
+        aq._apply_state(
+            {
+                "state": "99",
+                "attributes": {"air_quality_index": 55},
+            }
+        )
+        assert aq.air_quality_index == 55
+    finally:
+        await ha.close()
+
+
+async def test_air_quality_coercion_handles_strings_and_bad_values() -> None:
+    """Numeric strings coerce to ``float``; junk values yield ``None``."""
+    ha = HAClient.from_url("http://x", token="t", load_plugins=False)
+    try:
+        aq = ha.air_quality("noisy")
+        aq._apply_state(
+            {
+                "state": "unavailable",
+                "attributes": {
+                    "particulate_matter_2_5": "12.5",
+                    "carbon_dioxide": "not-a-number",
+                    "carbon_monoxide": True,  # bools are not real readings
+                    "ozone": "",
+                    "nitrogen_dioxide": [1, 2, 3],  # unsupported type -> None
+                },
+            }
+        )
+        assert aq.air_quality_index is None
+        assert aq.particulate_matter_2_5 == 12.5
+        assert aq.carbon_dioxide is None
+        assert aq.carbon_monoxide is None
+        assert aq.ozone is None
+        assert aq.nitrogen_dioxide is None
+    finally:
+        await ha.close()
+
+
+async def test_air_quality_listeners(client: HAClient, fake_ha: FakeHA) -> None:
+    """``on_aqi_change`` / ``on_pm25_change`` / ``on_co2_change`` fire as expected."""
+    aq = client.air_quality("bedroom")
+    aqi_events: list[tuple[Any, Any]] = []
+    pm25_events: list[tuple[Any, Any]] = []
+    co2_events: list[tuple[Any, Any]] = []
+
+    @aq.on_aqi_change
+    def _aqi(old: Any, new: Any) -> None:
+        aqi_events.append((old, new))
+
+    @aq.on_pm25_change
+    def _pm25(old: Any, new: Any) -> None:
+        pm25_events.append((old, new))
+
+    @aq.on_co2_change
+    def _co2(old: Any, new: Any) -> None:
+        co2_events.append((old, new))
+
+    await fake_ha.push_state_changed(
+        "air_quality.bedroom",
+        {
+            "state": "55",
+            "attributes": {"particulate_matter_2_5": 14.0, "carbon_dioxide": 950},
+        },
+        {
+            "state": "42",
+            "attributes": {"particulate_matter_2_5": 10.0, "carbon_dioxide": 800},
+        },
+    )
+    await asyncio.sleep(0.05)
+
+    assert aqi_events == [("42", "55")]
+    assert pm25_events == [(10.0, 14.0)]
+    assert co2_events == [(800, 950)]