Add Relative_time and today_at updates (#25986)

Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Petro31 2023-04-05 03:59:49 -04:00 committed by GitHub
parent 0456f07ed5
commit 94a793f922
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -564,7 +564,7 @@ For example, if you wanted to select a field from `trigger` in an automation bas
### Time ### Time
`now()` and `utcnow()` are not supported in [limited templates](#limited-templates). `now()`, `relative_time()`, `today_at()`, and `utcnow()` are not supported in [limited templates](#limited-templates).
- `now()` returns a datetime object that represents the current time in your time zone. - `now()` returns a datetime object that represents the current time in your time zone.
- You can also use: `now().second`, `now().minute`, `now().hour`, `now().day`, `now().month`, `now().year`, `now().weekday()` and `now().isoweekday()` and other [`datetime`](https://docs.python.org/3.8/library/datetime.html#datetime.datetime) attributes and functions. - You can also use: `now().second`, `now().minute`, `now().hour`, `now().day`, `now().month`, `now().year`, `now().weekday()` and `now().isoweekday()` and other [`datetime`](https://docs.python.org/3.8/library/datetime.html#datetime.datetime) attributes and functions.
@ -574,9 +574,11 @@ For example, if you wanted to select a field from `trigger` in an automation bas
- Using `utcnow()` will cause templates to be refreshed at the start of every new minute. - Using `utcnow()` will cause templates to be refreshed at the start of every new minute.
- `today_at(value)` converts a string containing a military time format to a datetime object with today's date in your time zone. - `today_at(value)` converts a string containing a military time format to a datetime object with today's date in your time zone.
- Using `today_at()` will cause templates to be refreshed at the start of every new minute.
{% raw %} {% raw %}
```yaml ```text
# Is the current time past 10:15? # Is the current time past 10:15?
{{ now() > today_at("10:15") }} {{ now() > today_at("10:15") }}
``` ```
@ -588,11 +590,12 @@ For example, if you wanted to select a field from `trigger` in an automation bas
- `as_local()` converts datetime object to local time. This function can also be used as a filter. - `as_local()` converts datetime object to local time. This function can also be used as a filter.
- `strptime(string, format, default)` parses a string based on a [format](https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior) and returns a datetime object. If that fails, it returns the `default` value or, if omitted, raises an error. - `strptime(string, format, default)` parses a string based on a [format](https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior) and returns a datetime object. If that fails, it returns the `default` value or, if omitted, raises an error.
- `relative_time` converts datetime object to its human-friendly "age" string. The age can be in second, minute, hour, day, month or year (but only the biggest unit is considered, e.g., if it's 2 days and 3 hours, "2 days" will be returned). Note that it only works for dates _in the past_. - `relative_time` converts datetime object to its human-friendly "age" string. The age can be in second, minute, hour, day, month or year (but only the biggest unit is considered, e.g., if it's 2 days and 3 hours, "2 days" will be returned). Note that it only works for dates _in the past_.
- Using `relative_time()` will cause templates to be refreshed at the start of every new minute.
- `timedelta` returns a timedelta object and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks. - `timedelta` returns a timedelta object and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks.
{% raw %} {% raw %}
```yaml ```text
# 77 minutes before current time. # 77 minutes before current time.
{{ now() - timedelta( hours = 1, minutes = 17 ) }} {{ now() - timedelta( hours = 1, minutes = 17 ) }}
``` ```
@ -603,7 +606,7 @@ For example, if you wanted to select a field from `trigger` in an automation bas
{% raw %} {% raw %}
```yaml ```text
# Renders to "00:10:00" # Renders to "00:10:00"
{{ as_timedelta("PT10M") }} {{ as_timedelta("PT10M") }}
``` ```
@ -642,7 +645,7 @@ To fix it, enforce the ISO conversion via `isoformat()`:
{% raw %} {% raw %}
```yaml ```text
{{ 120 | timestamp_local }} {{ 120 | timestamp_local }}
``` ```
@ -856,10 +859,8 @@ Some examples:
``` ```
This more complex example uses the `contains` filter to match the current month with a list. In this case, it's used to generate a list of light theme to give to the `Input select: Set options` service. This more complex example uses the `contains` filter to match the current month with a list. In this case, it's used to generate a list of light theme to give to the `Input select: Set options` service.
{% endraw %} {% endraw %}
### Numeric functions and filters ### Numeric functions and filters
Some of these functions can also be used in a [filter](https://jinja.palletsprojects.com/en/latest/templates/#id11). This means they can act as a normal function like this `sqrt(2)`, or as part of a filter like this `2|sqrt`. Some of these functions can also be used in a [filter](https://jinja.palletsprojects.com/en/latest/templates/#id11). This means they can act as a normal function like this `sqrt(2)`, or as part of a filter like this `2|sqrt`.
@ -961,7 +962,7 @@ The other part of templating is processing incoming data. It allows you to modif
It depends per integration or platform, but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions: It depends per integration or platform, but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions:
| Variable | Description | | Variable | Description |
|--------------|------------------------------------| | ------------ | ---------------------------------- |
| `value` | The incoming value. | | `value` | The incoming value. |
| `value_json` | The incoming value parsed as JSON. | | `value_json` | The incoming value parsed as JSON. |
@ -979,7 +980,7 @@ The template for `on` would be:
{% raw %} {% raw %}
```yaml ```yaml
'{{value_json.on}}' "{{value_json.on}}"
``` ```
{% endraw %} {% endraw %}
@ -1078,7 +1079,7 @@ With given payload:
{ "state": "ON", "temperature": 21.902 } { "state": "ON", "temperature": 21.902 }
``` ```
Template {% raw %}```{{ value_json.temperature | round(1) }}```{% endraw %} renders to `21.9`. Template {% raw %}`{{ value_json.temperature | round(1) }}`{% endraw %} renders to `21.9`.
Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used as variables in the template. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item. Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used as variables in the template. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item.
@ -1092,7 +1093,7 @@ For service calls command templates are defined to format the outgoing MQTT payl
Example command template: Example command template:
With given value `21.9` template {% raw %}```{"temperature": {{ value }} }```{% endraw %} renders to: With given value `21.9` template {% raw %}`{"temperature": {{ value }} }`{% endraw %} renders to:
```json ```json
{ {
@ -1116,7 +1117,7 @@ The default priority of operators is that the filter (`|`) has priority over eve
{% raw %} {% raw %}
```yaml ```text
{{ states('sensor.temperature') | float / 10 | round(2) }} {{ states('sensor.temperature') | float / 10 | round(2) }}
``` ```