Compare commits

...
Author SHA1 Message Date
J. Nick Koston a66012ff0d Pin SensorKind's fields so a new one cannot skip the merge 2026-11-17 01:30:17 -06:00
J. Nick Koston f773b68c26 Make SensorKind a slots class; building a NamedTuple slowed the sensor import 2026-11-17 01:05:13 -06:00
J. Nick Koston 22b56c555e Merge remote-tracking branch 'upstream/dev' into sensor-schema-kinds 2026-11-17 00:48:10 -06:00
J. Nick Koston bb67f2b358 Merge remote-tracking branch 'origin/dev' into HEAD 2026-11-14 08:37:30 -06:00
J. Nick Koston d22696f6ca Merge remote-tracking branch 'origin/dev' into sensor-schema-kinds 2026-11-04 18:34:59 -06:00
J. Nick Koston bec2cafdba Merge remote-tracking branch 'origin/dev' into sensor-schema-kinds 2026-11-02 20:25:29 -06:00
J. Nick Koston 45a4a4429f [sensor] Group presets by quantity, rename DISTANCE_M to LENGTH_M, simplify tests 2026-10-31 13:41:08 -10:00
J. Nick Koston 448a9acb8e [sensor] Add presets for the remaining common measurements 2026-10-31 13:34:34 -10:00
J. Nick Koston ef19c2cc45 Merge remote-tracking branch 'upstream/dev' into sensor-schema-kinds 2026-10-31 13:29:10 -10:00
J. Nick Koston 84de79dddc [sensor] Apply the decimals override before merging the kind 2026-10-31 13:23:40 -10:00
J. Nick Koston 3377b39790 [sensor] Give presets a default accuracy_decimals 2026-10-31 13:17:42 -10:00
J. Nick Koston 28b30480a8 Merge remote-tracking branch 'origin/dev' into HEAD 2026-10-31 13:12:16 -10:00
J. Nick Koston 171799c188 [sensor] Give the PM25 preset the chemical-weapon icon 2026-10-31 12:56:56 -10:00
J. Nick Koston 30ed0b88f9 [sensor] Build the given values as a SensorKind 2026-10-31 12:35:16 -10:00
J. Nick Koston bd21a3d808 [sensor] Simplify kind presets and pin them in tests 2026-10-31 12:24:36 -10:00
J. Nick Koston b261faf041 [sensor] Add measurement presets for sensor_schema 2026-10-31 12:15:32 -10:00
2 changed files with 379 additions and 0 deletions

No files matched your search

+151
View File
@@ -112,6 +112,36 @@ from esphome.const import (
DEVICE_CLASS_WIND_DIRECTION,
DEVICE_CLASS_WIND_SPEED,
ENTITY_CATEGORY_CONFIG,
ICON_CHEMICAL_WEAPON,
ICON_TIMER,
STATE_CLASS_MEASUREMENT,
STATE_CLASS_TOTAL_INCREASING,
UNIT_AMPERE,
UNIT_CELSIUS,
UNIT_DECIBEL_MILLIWATT,
UNIT_DEGREES,
UNIT_HECTOPASCAL,
UNIT_HERTZ,
UNIT_HOUR,
UNIT_KILOVOLT_AMPS,
UNIT_KILOVOLT_AMPS_REACTIVE,
UNIT_KILOVOLT_AMPS_REACTIVE_HOURS,
UNIT_KILOWATT,
UNIT_KILOWATT_HOURS,
UNIT_LUX,
UNIT_METER,
UNIT_MICROGRAMS_PER_CUBIC_METER,
UNIT_MILLIMETER,
UNIT_MINUTE,
UNIT_OHM,
UNIT_PARTS_PER_MILLION,
UNIT_PERCENT,
UNIT_SECOND,
UNIT_VOLT,
UNIT_VOLT_AMPS,
UNIT_VOLT_AMPS_REACTIVE,
UNIT_WATT,
UNIT_WATT_HOURS,
)
from esphome.core import (
CORE,
@@ -392,9 +422,119 @@ _SENSOR_SCHEMA.add_extra(entity_duplicate_validator("sensor"))
_SENSOR_SCHEMA.add_extra(lazy_load_validator("zigbee", "validate_sensor"))
class SensorKind:
"""Values `sensor_schema(kind=...)` sets; unset fields are left to the caller.
`state_class` is always set (measurement by default). `accuracy_decimals` is only a
default, as sensors differ; the caller's value wins. Passing any other field the kind
sets is an error. A plain class, not a NamedTuple, which costs more to import.
"""
__slots__ = (
"unit_of_measurement",
"device_class",
"state_class",
"icon",
"accuracy_decimals",
)
def __init__(
self,
unit_of_measurement: str = cv.UNDEFINED,
device_class: str = cv.UNDEFINED,
state_class: str = STATE_CLASS_MEASUREMENT,
icon: str = cv.UNDEFINED,
accuracy_decimals: int = cv.UNDEFINED,
) -> None:
self.unit_of_measurement = unit_of_measurement
self.device_class = device_class
self.state_class = state_class
self.icon = icon
self.accuracy_decimals = accuracy_decimals
TEMPERATURE = SensorKind(UNIT_CELSIUS, DEVICE_CLASS_TEMPERATURE, accuracy_decimals=1)
HUMIDITY = SensorKind(UNIT_PERCENT, DEVICE_CLASS_HUMIDITY, accuracy_decimals=1)
BATTERY = SensorKind(UNIT_PERCENT, DEVICE_CLASS_BATTERY, accuracy_decimals=0)
PRESSURE = SensorKind(UNIT_HECTOPASCAL, DEVICE_CLASS_PRESSURE, accuracy_decimals=1)
ILLUMINANCE = SensorKind(UNIT_LUX, DEVICE_CLASS_ILLUMINANCE, accuracy_decimals=0)
CARBON_DIOXIDE = SensorKind(
UNIT_PARTS_PER_MILLION, DEVICE_CLASS_CARBON_DIOXIDE, accuracy_decimals=0
)
MASS_CONCENTRATION = SensorKind(UNIT_MICROGRAMS_PER_CUBIC_METER, accuracy_decimals=0)
def _particulate(device_class: str) -> SensorKind:
return SensorKind(
UNIT_MICROGRAMS_PER_CUBIC_METER,
device_class,
icon=ICON_CHEMICAL_WEAPON,
accuracy_decimals=0,
)
PM1 = _particulate(DEVICE_CLASS_PM1)
PM25 = _particulate(DEVICE_CLASS_PM25)
PM10 = _particulate(DEVICE_CLASS_PM10)
SIGNAL_STRENGTH = SensorKind(
UNIT_DECIBEL_MILLIWATT, DEVICE_CLASS_SIGNAL_STRENGTH, accuracy_decimals=0
)
VOLTAGE = SensorKind(UNIT_VOLT, DEVICE_CLASS_VOLTAGE)
CURRENT = SensorKind(UNIT_AMPERE, DEVICE_CLASS_CURRENT)
FREQUENCY = SensorKind(UNIT_HERTZ, DEVICE_CLASS_FREQUENCY)
POWER = SensorKind(UNIT_WATT, DEVICE_CLASS_POWER)
POWER_KW = SensorKind(UNIT_KILOWATT, DEVICE_CLASS_POWER, accuracy_decimals=3)
APPARENT_POWER = SensorKind(UNIT_VOLT_AMPS, DEVICE_CLASS_APPARENT_POWER)
APPARENT_POWER_KVA = SensorKind(
UNIT_KILOVOLT_AMPS, DEVICE_CLASS_APPARENT_POWER, accuracy_decimals=3
)
REACTIVE_POWER = SensorKind(UNIT_VOLT_AMPS_REACTIVE, DEVICE_CLASS_REACTIVE_POWER)
REACTIVE_POWER_KVAR = SensorKind(
UNIT_KILOVOLT_AMPS_REACTIVE, DEVICE_CLASS_REACTIVE_POWER, accuracy_decimals=3
)
POWER_FACTOR = SensorKind(device_class=DEVICE_CLASS_POWER_FACTOR)
ENERGY_WH = SensorKind(
UNIT_WATT_HOURS, DEVICE_CLASS_ENERGY, STATE_CLASS_TOTAL_INCREASING
)
ENERGY_KWH = SensorKind(
UNIT_KILOWATT_HOURS,
DEVICE_CLASS_ENERGY,
STATE_CLASS_TOTAL_INCREASING,
accuracy_decimals=3,
)
# No device class, matching the meters that report it today.
REACTIVE_ENERGY_KVARH = SensorKind(
UNIT_KILOVOLT_AMPS_REACTIVE_HOURS,
state_class=STATE_CLASS_TOTAL_INCREASING,
accuracy_decimals=3,
)
DISTANCE_MM = SensorKind(UNIT_MILLIMETER, DEVICE_CLASS_DISTANCE, accuracy_decimals=0)
DURATION_H = SensorKind(
UNIT_HOUR, DEVICE_CLASS_DURATION, icon=ICON_TIMER, accuracy_decimals=0
)
DURATION_MIN = SensorKind(UNIT_MINUTE, DEVICE_CLASS_DURATION, accuracy_decimals=0)
DURATION_S = SensorKind(UNIT_SECOND, DEVICE_CLASS_DURATION, accuracy_decimals=0)
# Generic quantities with no device class.
PERCENT = SensorKind(UNIT_PERCENT, accuracy_decimals=0)
ANGLE = SensorKind(UNIT_DEGREES)
LENGTH_M = SensorKind(UNIT_METER, accuracy_decimals=2)
RESISTANCE = SensorKind(UNIT_OHM, accuracy_decimals=0)
def _kind_value(kind: SensorKind, name: str, value: Any) -> Any:
"""The kind's value for `name`, or the caller's if the kind leaves it unset."""
preset = getattr(kind, name)
if preset is cv.UNDEFINED:
return value
if value is not cv.UNDEFINED:
raise ValueError(f"kind already sets {name}")
return preset
def sensor_schema(
class_: MockObjClass = cv.UNDEFINED,
*,
kind: SensorKind = cv.UNDEFINED,
unit_of_measurement: str = cv.UNDEFINED,
icon: str = cv.UNDEFINED,
accuracy_decimals: int = cv.UNDEFINED,
@@ -403,6 +543,17 @@ def sensor_schema(
entity_category: str = cv.UNDEFINED,
filters: list = cv.UNDEFINED,
) -> cv.Schema:
"""Sensor schema; `kind` presets the unit, device class, state class, icon and decimals."""
if kind is not cv.UNDEFINED:
unit_of_measurement = _kind_value(
kind, "unit_of_measurement", unit_of_measurement
)
device_class = _kind_value(kind, "device_class", device_class)
state_class = _kind_value(kind, "state_class", state_class)
icon = _kind_value(kind, "icon", icon)
if accuracy_decimals is cv.UNDEFINED:
accuracy_decimals = kind.accuracy_decimals
schema = {}
if class_ is not cv.UNDEFINED:
@@ -0,0 +1,228 @@
"""Tests for the sensor_schema kind presets."""
from typing import Any
import pytest
from esphome.components import sensor
import esphome.config_validation as cv
from esphome.const import (
DEVICE_CLASS_APPARENT_POWER,
DEVICE_CLASS_BATTERY,
DEVICE_CLASS_CARBON_DIOXIDE,
DEVICE_CLASS_CURRENT,
DEVICE_CLASS_DISTANCE,
DEVICE_CLASS_DURATION,
DEVICE_CLASS_ENERGY,
DEVICE_CLASS_FREQUENCY,
DEVICE_CLASS_HUMIDITY,
DEVICE_CLASS_ILLUMINANCE,
DEVICE_CLASS_PM1,
DEVICE_CLASS_PM10,
DEVICE_CLASS_PM25,
DEVICE_CLASS_POWER,
DEVICE_CLASS_POWER_FACTOR,
DEVICE_CLASS_PRESSURE,
DEVICE_CLASS_REACTIVE_POWER,
DEVICE_CLASS_SIGNAL_STRENGTH,
DEVICE_CLASS_TEMPERATURE,
DEVICE_CLASS_VOLTAGE,
ENTITY_CATEGORY_DIAGNOSTIC,
ICON_CHEMICAL_WEAPON,
ICON_TIMER,
STATE_CLASS_MEASUREMENT,
STATE_CLASS_TOTAL_INCREASING,
UNIT_AMPERE,
UNIT_CELSIUS,
UNIT_DECIBEL_MILLIWATT,
UNIT_DEGREES,
UNIT_HECTOPASCAL,
UNIT_HERTZ,
UNIT_HOUR,
UNIT_KILOVOLT_AMPS,
UNIT_KILOVOLT_AMPS_REACTIVE,
UNIT_KILOVOLT_AMPS_REACTIVE_HOURS,
UNIT_KILOWATT,
UNIT_KILOWATT_HOURS,
UNIT_LUX,
UNIT_METER,
UNIT_MICROGRAMS_PER_CUBIC_METER,
UNIT_MILLIMETER,
UNIT_MINUTE,
UNIT_OHM,
UNIT_PARTS_PER_MILLION,
UNIT_PERCENT,
UNIT_SECOND,
UNIT_VOLT,
UNIT_VOLT_AMPS,
UNIT_VOLT_AMPS_REACTIVE,
UNIT_WATT,
UNIT_WATT_HOURS,
)
_M = STATE_CLASS_MEASUREMENT
_T = STATE_CLASS_TOTAL_INCREASING
_PM = UNIT_MICROGRAMS_PER_CUBIC_METER
_UNSET = cv.UNDEFINED
# (unit, device class, state class, icon, accuracy decimals) each preset must expand to
EXPECTED = {
"TEMPERATURE": (UNIT_CELSIUS, DEVICE_CLASS_TEMPERATURE, _M, _UNSET, 1),
"HUMIDITY": (UNIT_PERCENT, DEVICE_CLASS_HUMIDITY, _M, _UNSET, 1),
"BATTERY": (UNIT_PERCENT, DEVICE_CLASS_BATTERY, _M, _UNSET, 0),
"PRESSURE": (UNIT_HECTOPASCAL, DEVICE_CLASS_PRESSURE, _M, _UNSET, 1),
"ILLUMINANCE": (UNIT_LUX, DEVICE_CLASS_ILLUMINANCE, _M, _UNSET, 0),
"CARBON_DIOXIDE": (
UNIT_PARTS_PER_MILLION,
DEVICE_CLASS_CARBON_DIOXIDE,
_M,
_UNSET,
0,
),
"PM1": (_PM, DEVICE_CLASS_PM1, _M, ICON_CHEMICAL_WEAPON, 0),
"PM25": (_PM, DEVICE_CLASS_PM25, _M, ICON_CHEMICAL_WEAPON, 0),
"PM10": (_PM, DEVICE_CLASS_PM10, _M, ICON_CHEMICAL_WEAPON, 0),
"SIGNAL_STRENGTH": (
UNIT_DECIBEL_MILLIWATT,
DEVICE_CLASS_SIGNAL_STRENGTH,
_M,
_UNSET,
0,
),
"VOLTAGE": (UNIT_VOLT, DEVICE_CLASS_VOLTAGE, _M, _UNSET, _UNSET),
"CURRENT": (UNIT_AMPERE, DEVICE_CLASS_CURRENT, _M, _UNSET, _UNSET),
"POWER": (UNIT_WATT, DEVICE_CLASS_POWER, _M, _UNSET, _UNSET),
"APPARENT_POWER": (
UNIT_VOLT_AMPS,
DEVICE_CLASS_APPARENT_POWER,
_M,
_UNSET,
_UNSET,
),
"REACTIVE_POWER": (
UNIT_VOLT_AMPS_REACTIVE,
DEVICE_CLASS_REACTIVE_POWER,
_M,
_UNSET,
_UNSET,
),
"FREQUENCY": (UNIT_HERTZ, DEVICE_CLASS_FREQUENCY, _M, _UNSET, _UNSET),
"ENERGY_KWH": (UNIT_KILOWATT_HOURS, DEVICE_CLASS_ENERGY, _T, _UNSET, 3),
"ENERGY_WH": (UNIT_WATT_HOURS, DEVICE_CLASS_ENERGY, _T, _UNSET, _UNSET),
"POWER_KW": (UNIT_KILOWATT, DEVICE_CLASS_POWER, _M, _UNSET, 3),
"APPARENT_POWER_KVA": (
UNIT_KILOVOLT_AMPS,
DEVICE_CLASS_APPARENT_POWER,
_M,
_UNSET,
3,
),
"REACTIVE_POWER_KVAR": (
UNIT_KILOVOLT_AMPS_REACTIVE,
DEVICE_CLASS_REACTIVE_POWER,
_M,
_UNSET,
3,
),
"REACTIVE_ENERGY_KVARH": (UNIT_KILOVOLT_AMPS_REACTIVE_HOURS, _UNSET, _T, _UNSET, 3),
"POWER_FACTOR": (_UNSET, DEVICE_CLASS_POWER_FACTOR, _M, _UNSET, _UNSET),
"PERCENT": (UNIT_PERCENT, _UNSET, _M, _UNSET, 0),
"ANGLE": (UNIT_DEGREES, _UNSET, _M, _UNSET, _UNSET),
"MASS_CONCENTRATION": (_PM, _UNSET, _M, _UNSET, 0),
"LENGTH_M": (UNIT_METER, _UNSET, _M, _UNSET, 2),
"DISTANCE_MM": (UNIT_MILLIMETER, DEVICE_CLASS_DISTANCE, _M, _UNSET, 0),
"RESISTANCE": (UNIT_OHM, _UNSET, _M, _UNSET, 0),
"DURATION_H": (UNIT_HOUR, DEVICE_CLASS_DURATION, _M, ICON_TIMER, 0),
"DURATION_MIN": (UNIT_MINUTE, DEVICE_CLASS_DURATION, _M, _UNSET, 0),
"DURATION_S": (UNIT_SECOND, DEVICE_CLASS_DURATION, _M, _UNSET, 0),
}
def _keys(schema: cv.Schema) -> list[tuple[Any, ...]]:
"""Key type, name and validator of every schema entry, in order."""
return [
(type(key), str(key), validator) for key, validator in schema.schema.items()
]
def _defaults(schema: cv.Schema) -> dict[str, Any]:
return {
str(key): key.default()
for key in schema.schema
if isinstance(key, cv.Optional) and key.default is not cv.UNDEFINED
}
def test_sensor_schema_merges_every_field() -> None:
"""A new SensorKind field must also be merged in sensor_schema() and pinned in EXPECTED."""
assert sensor.SensorKind.__slots__ == (
"unit_of_measurement",
"device_class",
"state_class",
"icon",
"accuracy_decimals",
)
def test_every_preset_is_pinned() -> None:
kinds = {
name
for name, value in vars(sensor).items()
if isinstance(value, sensor.SensorKind)
}
assert kinds == EXPECTED.keys()
@pytest.mark.parametrize("name", sorted(EXPECTED))
def test_kind_matches_hand_written(name: str) -> None:
unit, device_class, state_class, icon, decimals = EXPECTED[name]
by_kind = sensor.sensor_schema(kind=getattr(sensor, name))
by_hand = sensor.sensor_schema(
unit_of_measurement=unit,
icon=icon,
accuracy_decimals=decimals,
device_class=device_class,
state_class=state_class,
)
assert _keys(by_kind) == _keys(by_hand)
assert _defaults(by_kind) == _defaults(by_hand)
@pytest.mark.parametrize("kind", [sensor.TEMPERATURE, sensor.VOLTAGE])
def test_accuracy_decimals_can_be_overridden(kind: sensor.SensorKind) -> None:
schema = sensor.sensor_schema(kind=kind, accuracy_decimals=3)
assert _defaults(schema)["accuracy_decimals"] == 3
def test_extra_arguments_pass_through() -> None:
extra = {
"accuracy_decimals": 2,
"icon": "mdi:thermometer",
"entity_category": ENTITY_CATEGORY_DIAGNOSTIC,
"filters": [{"offset": 1.0}],
}
by_kind = sensor.sensor_schema(kind=sensor.TEMPERATURE, **extra)
by_hand = sensor.sensor_schema(
unit_of_measurement=UNIT_CELSIUS,
device_class=DEVICE_CLASS_TEMPERATURE,
state_class=STATE_CLASS_MEASUREMENT,
**extra,
)
assert _keys(by_kind) == _keys(by_hand)
assert _defaults(by_kind) == _defaults(by_hand)
@pytest.mark.parametrize(
("kind", "key"),
[
(sensor.TEMPERATURE, "unit_of_measurement"),
(sensor.TEMPERATURE, "device_class"),
(sensor.TEMPERATURE, "state_class"),
(sensor.PM10, "icon"),
],
)
def test_kind_with_explicit_value_is_rejected(
kind: sensor.SensorKind, key: str
) -> None:
with pytest.raises(ValueError, match=f"kind already sets {key}"):
sensor.sensor_schema(kind=kind, **{key: "x"})