Skip to content

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

Merged
Faerkeren merged 1 commit into
mainfrom
feat/air-quality-domain
May 26, 2026
Merged

feat(domains): add AirQuality domain (#34)#66
Faerkeren merged 1 commit into
mainfrom
feat/air-quality-domain

Conversation

@Faerkeren

Copy link
Copy Markdown
Contributor

Closes #34.

Issue validity

Valid feature request. Air quality entities are a distinct HA domain with multiple co-reported pollutant metrics that do not fit the single-value Sensor abstraction. Without a domain helper users must hand-parse attributes with no type safety or change listeners — inconsistent with the typed experience of Sensor, Climate, etc.

Fix

Adds `src/haclient/domains/air_quality.py`:

  • `AirQuality` read-only `Entity` subclass registered as the `air_quality` domain.
  • Typed metric properties: `air_quality_index`, `particulate_matter_2_5`, `particulate_matter_10`, `carbon_dioxide`, `carbon_monoxide`, `volatile_organic_compounds`, `nitrogen_dioxide`, `ozone`.
  • Graceful degradation: every metric returns `None` when the underlying sensor doesn't report it. A shared numeric coercion helper accepts `int`/`float`/numeric strings and rejects bools, empty strings, `unknown`/`unavailable`, and unsupported types.
  • `air_quality_index` prefers an explicit `air_quality_index` attribute when present, otherwise falls back to the entity state (which is what HA's `air_quality` platform sets.
  • Listener decorators per the issue spec: on_aqi_change, on_pm25_change, on_co2_change.
  • Registered & exported from haclient.domains.__init__, automatically reachable as ha.air_quality("name").

Tests added (tests/test_domains.py)

  • test_air_quality_full_metrics — every metric reads its attribute.
  • test_air_quality_degrades_when_metrics_missing — every metric returns None on an empty sensor.
  • test_air_quality_index_prefers_explicit_attribute — attribute overrides state.
  • test_air_quality_coercion_handles_strings_and_bad_values — numeric strings coerce, junk/bool/list yield None.
  • test_air_quality_listeners — all three decorators fire correctly.

Validation

  • ruff check src tests — clean
  • ruff format --check src tests — clean
  • mypy src (strict) — clean
  • pytest tests/ --cov=haclient --cov-report=term-missing --cov-fail-under=95 — 265 passed, total coverage 96.62% (new module 100%).
    EOF
    )

Adds a read-only AirQuality domain wrapping HA's air_quality entities
with typed pollutant metric properties (AQI, PM2.5, PM10, CO2, CO, VOC,
NO2, ozone). All metrics return None when the underlying sensor does
not report them, so unsupported metrics degrade silently. Provides
on_aqi_change / on_pm25_change / on_co2_change listener decorators.
@Faerkeren Faerkeren merged commit c64eaa3 into main May 26, 2026
12 checks passed
@Faerkeren Faerkeren deleted the feat/air-quality-domain branch May 26, 2026 18:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Add Air Quality domain support

1 participant