From 1744b5fa0a81a64926680f82b52ab3c2c6470628 Mon Sep 17 00:00:00 2001 From: epenet <6771947+epenet@users.noreply.github.com> Date: Mon, 10 Oct 2022 12:38:10 +0200 Subject: [PATCH] Add docstring to Sensor enums (#79983) * Add docstring to Sensor enums * Adjust MONETARY docstring --- homeassistant/components/sensor/__init__.py | 209 ++++++++++++++++---- 1 file changed, 170 insertions(+), 39 deletions(-) diff --git a/homeassistant/components/sensor/__init__.py b/homeassistant/components/sensor/__init__.py index 06071eeddbe..9ebf225c637 100644 --- a/homeassistant/components/sensor/__init__.py +++ b/homeassistant/components/sensor/__init__.py @@ -85,116 +85,243 @@ SCAN_INTERVAL: Final = timedelta(seconds=30) class SensorDeviceClass(StrEnum): """Device class for sensors.""" - # apparent power (VA) APPARENT_POWER = "apparent_power" + """Apparent power. + + Unit of measurement: `VA` + """ - # Air Quality Index AQI = "aqi" + """Air Quality Index. + + Unit of measurement: `None` + """ - # % of battery that is left BATTERY = "battery" + """Percentage of battery that is left. + + Unit of measurement: `%` + """ - # ppm (parts per million) Carbon Monoxide gas concentration CO = "carbon_monoxide" + """Carbon Monoxide gas concentration. + + Unit of measurement: `ppm` (parts per million) + """ - # ppm (parts per million) Carbon Dioxide gas concentration CO2 = "carbon_dioxide" + """Carbon Dioxide gas concentration. + + Unit of measurement: `ppm` (parts per million) + """ - # current (A) CURRENT = "current" + """Current. + + Unit of measurement: `A` + """ - # date (ISO8601) DATE = "date" + """Date. + + Unit of measurement: `None` + + ISO8601 format: https://en.wikipedia.org/wiki/ISO_8601 + """ - # distance (LENGTH_*) DISTANCE = "distance" + """Generic distance. + + Unit of measurement: `LENGTH_*` units + - SI /metric: `mm`, `cm`, `m`, `km` + - USCS / imperial: `in`, `ft`, `yd`, `mi` + """ - # fixed duration (TIME_DAYS, TIME_HOURS, TIME_MINUTES, TIME_SECONDS) DURATION = "duration" + """Fixed duration. + + Unit of measurement: `d`, `h`, `min`, `s` + """ - # energy (Wh, kWh, MWh) ENERGY = "energy" + """Energy. + + Unit of measurement: `Wh`, `kWh`, `MWh` + """ - # frequency (Hz, kHz, MHz, GHz) FREQUENCY = "frequency" + """Frequency. + + Unit of measurement: `Hz`, `kHz`, `MHz`, `GHz` + """ - # gas (m³ or ft³) GAS = "gas" + """Gas. + + Unit of measurement: `m³`, `ft³` + """ - # Relative humidity (%) HUMIDITY = "humidity" + """Relative humidity. + + Unit of measurement: `%` + """ - # current light level (lx/lm) ILLUMINANCE = "illuminance" + """Illuminance. + + Unit of measurement: `lx`, `lm` + """ - # moisture (%) MOISTURE = "moisture" + """Moisture. + + Unit of measurement: `%` + """ - # Amount of money (currency) MONETARY = "monetary" + """Amount of money. + + Unit of measurement: ISO4217 currency code + + See https://en.wikipedia.org/wiki/ISO_4217#Active_codes for active codes + """ - # Amount of NO2 (µg/m³) NITROGEN_DIOXIDE = "nitrogen_dioxide" + """Amount of NO2. + + Unit of measurement: `µg/m³` + """ - # Amount of NO (µg/m³) NITROGEN_MONOXIDE = "nitrogen_monoxide" + """Amount of NO. + + Unit of measurement: `µg/m³` + """ - # Amount of N2O (µg/m³) NITROUS_OXIDE = "nitrous_oxide" + """Amount of N2O. + + Unit of measurement: `µg/m³` + """ - # Amount of O3 (µg/m³) OZONE = "ozone" + """Amount of O3. + + Unit of measurement: `µg/m³` + """ - # Particulate matter <= 0.1 μm (µg/m³) PM1 = "pm1" + """Particulate matter <= 0.1 μm. + + Unit of measurement: `µg/m³` + """ - # Particulate matter <= 10 μm (µg/m³) PM10 = "pm10" + """Particulate matter <= 10 μm. + + Unit of measurement: `µg/m³` + """ - # Particulate matter <= 2.5 μm (µg/m³) PM25 = "pm25" + """Particulate matter <= 2.5 μm. + + Unit of measurement: `µg/m³` + """ - # power factor (%) POWER_FACTOR = "power_factor" + """Power factor. + + Unit of measurement: `%` + """ - # power (W/kW) POWER = "power" + """Power. + + Unit of measurement: `W`, `kW` + """ - # pressure (hPa/mbar) PRESSURE = "pressure" + """Pressure. + + Unit of measurement: + - `mbar`, `cbar`, `bar` + - `Pa`, `hPa`, `kPa` + - `inHg` + - `psi` + """ - # reactive power (var) REACTIVE_POWER = "reactive_power" + """Reactive power. + + Unit of measurement: `var` + """ - # signal strength (dB/dBm) SIGNAL_STRENGTH = "signal_strength" + """Signal strength. + + Unit of measurement: `dB`, `dBm` + """ - # speed (SPEED_*) SPEED = "speed" + """Generic speed. + + Unit of measurement: `SPEED_*` units + - SI /metric: `mm/d`, `mm/h`, `m/s`, `km/h` + - USCS / imperial: `in/d`, `in/h`, `ft/s`, `mph` + - Nautical: `kn` + """ - # Amount of SO2 (µg/m³) SULPHUR_DIOXIDE = "sulphur_dioxide" + """Amount of SO2. + + Unit of measurement: `µg/m³` + """ - # temperature (C/F) TEMPERATURE = "temperature" + """Temperature. + + Unit of measurement: `°C`, `°F` + """ - # timestamp (ISO8601) TIMESTAMP = "timestamp" + """Timestamp. + + Unit of measurement: `None` + + ISO8601 format: https://en.wikipedia.org/wiki/ISO_8601 + """ - # Amount of VOC (µg/m³) VOLATILE_ORGANIC_COMPOUNDS = "volatile_organic_compounds" + """Amount of VOC. + + Unit of measurement: `µg/m³` + """ - # voltage (V) VOLTAGE = "voltage" + """Voltage. + + Unit of measurement: `V` + """ - # volume (VOLUME_*) VOLUME = "volume" + """Generic volume. + + Unit of measurement: `VOLUME_*` units + - SI / metric: `mL`, `L`, `m³` + - USCS / imperial: `fl. oz.`, `gal`, `ft³` (warning: volumes expressed in + USCS/imperial units are currently assumed to be US volumes) + """ # weight/mass (g, kg, mg, µg, oz, lb) WEIGHT = "weight" - """Represent a measurement of an object's mass. + """Generic weight, represents a measurement of an object's mass. Weight is used instead of mass to fit with every day language. + + Unit of measurement: `MASS_*` units + - SI / metric: `µg`, `mg`, `g`, `kg` + - USCS / imperial: `oz`, `lb` """ @@ -208,14 +335,18 @@ DEVICE_CLASSES: Final[list[str]] = [cls.value for cls in SensorDeviceClass] class SensorStateClass(StrEnum): """State class for sensors.""" - # The state represents a measurement in present time MEASUREMENT = "measurement" + """The state represents a measurement in present time.""" - # The state represents a total amount, e.g. net energy consumption TOTAL = "total" + """The state represents a total amount. + + For example: net energy consumption""" - # The state represents a monotonically increasing total, e.g. an amount of consumed gas TOTAL_INCREASING = "total_increasing" + """The state represents a monotonically increasing total. + + For example: an amount of consumed gas""" STATE_CLASSES_SCHEMA: Final = vol.All(vol.Lower, vol.Coerce(SensorStateClass))