Three modes for weather (#1616)

* Three modes for weather

* Tiny tweak

* new methods

* Review comments

* Change text

* Mods from rebase

* Update docs/core/entity/weather.md

* Apply suggestions from code review

---------

Co-authored-by: Franck Nijhof <frenck@frenck.nl>
Co-authored-by: Erik Montnemery <erik@montnemery.com>
This commit is contained in:
G Johansson 2023-08-07 13:17:42 +02:00 committed by GitHub
parent 207e786ce1
commit 6bf695dde5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -31,7 +31,6 @@ Properties should always only return information from memory and not do I/O (lik
| native_wind_speed_unit | string | `None` | The wind speed unit;m/s, km/h, mi/h, ft/s or kn. Required if native_wind_speed is set.
| native_precipitation_unit | string | `None` | The precipitation unit; mm or in.
| wind_bearing | float or string | `None` | The current wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction.
| forecast | array | `None` | Daily or Hourly forecast data.
### Unit Conversion
@ -41,30 +40,6 @@ To the user, properties will be presented according to the unit system. This is
For each weather entity, the user also has the option to override the presentation units, i.e., the units used in the state objects.
### Forecast
Forecast data should either be daily or hourly.
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| datetime | string | **Required** | UTC Date time in RFC 3339 format.
| native_temperature | float | **Required** | The higher temperature in °C or °F
| native_apparent_temperature | float | `None` | The apparent (feels-like) temperature in °C or °F
| condition | string | `None` | The weather condition at this point.
| native_templow | float | `None` | The lower daily Temperature in °C or °F
| native_dew_point | float | `None` | The dew point temperature in °C or °F
| native_precipitation | float | `None` | The precipitation amount in mm or in.
| precipitation_probability | int | `None` | The probability of precipitation in %.
| humidity | float | `None` | The humidity in %.
| cloud_coverage | int | `None` | The cloud coverage in %.
| uv_index | float | `None` | The UV index.
| native_pressure | float | `None` | The air pressure in hPa, mbar, inHg or mmHg.
| wind_bearing | float or string | `None` | The wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction.
| native_wind_gust_speed | int | `None` | The wind gust speed in m/s, km/h, mi/h, ft/s or kn.
| native_wind_speed | int | `None` | The wind speed in m/s, km/h, mi/h, ft/s or kn.
Forecast data needs to follow the same unit of measurement as defined for properties where applicable.
### Recommended values for state and condition
These weather conditions are included in our translation files and also show the corresponding icon.
@ -88,3 +63,78 @@ These weather conditions are included in our translation files and also show the
| windy-variant | Wind and clouds
This means that the `weather` platforms don't need to support languages.
## Supported Features
Supported features are defined by using values in the `WeatherEntityFeature` enum
and are combined using the bitwise or (`|`) operator.
| Value | Description |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| `FORECAST_DAILY` | The device supports a daily forecast. |
| `FORECAST_HOURLY` | The device supports an hourly forecast. |
| `FORECAST_TWICE_DAILY` | The device supports a twice-daily forecast. |
## Weather forecasts
A weather platform can optionally provide weather forecasts. Support for weather forecasts is indicated by setting the correct [supported feature](#supported-features). Weather forecasts are not part of the entity's state, they're instead made available by a separate API. Consumers, e.g. frontend, can subscribe to weather forecast updates.
### Forecast data
Forecast data can be daily, hourly or twice_daily. An integration can provide any or all of them.
The integration should implement one or several of the async methods `async_forecast_daily`, `async_forecast_hourly` and `async_forecast_twice_daily` documented below to fetch the forecast data.
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| datetime | string | **Required** | UTC Date time in RFC 3339 format.
| native_temperature | float | **Required** | The higher temperature in °C or °F
| native_apparent_temperature | float | `None` | The apparent (feels-like) temperature in °C or °F
| condition | string | `None` | The weather condition at this point.
| native_templow | float | `None` | The lower daily Temperature in °C or °F
| native_dew_point | float | `None` | The dew point temperature in °C or °F
| native_precipitation | float | `None` | The precipitation amount in mm or in.
| precipitation_probability | int | `None` | The probability of precipitation in %.
| humidity | float | `None` | The humidity in %.
| cloud_coverage | int | `None` | The cloud coverage in %.
| uv_index | float | `None` | The UV index.
| native_pressure | float | `None` | The air pressure in hPa, mbar, inHg or mmHg.
| wind_bearing | float or string | `None` | The wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction.
| native_wind_gust_speed | int | `None` | The wind gust speed in m/s, km/h, mi/h, ft/s or kn.
| native_wind_speed | int | `None` | The wind speed in m/s, km/h, mi/h, ft/s or kn.
| is_daytime | bool | `None` | This is mandatory in forecast data returned by `async_forecast_twice_daily` to indicate day or night.
Forecast data needs to follow the same unit of measurement as defined for properties where applicable.
### Methods to get weather forecast(s)
These method are called to fetch forecasts from the api.
```python
class MyWeatherEntity(WeatherEntity):
"""Represent a Weather entity."""
async def async_forecast_daily(self) -> list[Forecast] | None:
"""Return the daily forecast in native units.
Only implement this method if `WeatherEntityFeature.FORECAST_DAILY` is set
"""
async def async_forecast_twice_daily(self) -> list[Forecast] | None:
"""Return the twice daily forecast in native units.
Only implement this method if `WeatherEntityFeature.FORECAST_TWICE_DAILY` is set
"""
async def async_forecast_hourly(self) -> list[Forecast] | None:
"""Return the hourly forecast in native units.
Only implement this method if `WeatherEntityFeature.FORECAST_HOURLY` is set
"""
```
### Updating weather forecast(s)
It is strongly recommended that fetched weather forecasts are cached by the weather entity to avoid unnecessary API accesses.
When an updated weather forecast is available, the weather forecast cache should be invalidated and the method `WeatherEntity.async_update_listeners` should be awaited to trigger a push of the updated weather forecast to any active subscriber. If there are active listeners, `WeatherEntity.async_update_listeners` will call the corresponding `async_forecast_xxx` methods. If there are no active listeners, `WeatherEntity.async_update_listeners` will not call any ot the `async_forecast_xxx` methods.