Templating changes in 2021.10.0

[123 (Taras)]

---

---

Note

This topic was created prior to the release of 2021.10.0 and was meant to inform the community of important upcoming changes to certain aspects of templating.

After the release of 2021.10.0, petro posted many examples of how to adapt templates to comply with the new requirements.

Updating Templates with the new default values in 2021.10.x

I keep seeing the same question about the new default argument for the templating. This post will cover all possible ways to define default. All the methods that were changed: acos as_timestamp asin atan atan2 cos float log round sin sqrt strptime tan timestamp_custom timestamp_local timestamp_utc Each of them have the exact same default functionality but a different number of arguments. There are multiple ways to use these functions, and this is where all the confusion lies. Understandi…

I recommend reviewing the examples before posting questions.

---

---

I skimmed the pre-release notes and selected several notable templating improvements and modifications.

---

Breaking Change

Several existing functions will handle defaults differently. PR 5643

The following template filters and functions will now log a warning instead of silently returning the input if the input is invalid and no default value is specified:

round, multiply, log, sin, cos, tan, asin, acos, atan, atan2, sqrt, timestamp_custom, timestamp_local, timestamp_utc, as_timestamp, strptime, float

The float filter will now log a warning instead of silently returning 0 if the input is invalid and no default value is specified.

In Home Assistant core 2021.12 the template will fail to render if no default value is specified.

Examples:

{{ "abc" | float }} - Will render as 0, and a warning will be logged
{{ "abc" | float(default=5) }} - Will render as -5, no warning will be logged
{{ float("abc") }} - Will render as “abc”, and a warning will be logged
{{ float("abc", default=5) }} - Will render as -5, no warning will be logged

---

New/Enhanced Functions

is_numeric

New function that indicates if the supplied value is numeric. PR 56705

is_numeric will returns True if the input can be parsed by Python’s float function and its value is not inf or nan, in all other cases returns False. Can be used as a filter.

Examples:

{{ "" | is_numeric}} - will render as False
{{ "1" | is_numeric}} - will render as True
{{ "1.1" | is_numeric}} - will render as True
{{ "nan" | is_numeric}} - will render as False
{{ "inf" | is_numeric}} - will render as False
{{ "½" | is_numeric}} - will render as False
{{ True | is_numeric }} - will render as True
{{ False | is_numeric }} - will render as True
{{ "True" | is_numeric}} - will render as False
{{ "False" | is_numeric}} - will render as False

regex_findall

New function that returns an array of matches. PR 54584

Filter string|regex_findall(find='', ignorecase=False) will find all regex matches of the find expression in string and return the array of matches.

device_id

Existing function that now accepts a device name. PR 55474

device_id(entity_id) returns the device ID for a given entity ID or device name. Can also be used as a filter

[wixoff]

@123

Examples:

{{ "abc" | float }} - Will render as 0, and a warning will be logged
{{ "abc" | float(default=5) }} - Will render as -5, no warning will be logged
{{ float("abc") }} - Will render as “abc”, and a warning will be logged
{{ float("abc", default=5) }} - Will render as -5, no warning will be logged

I have to believe that the “-5” in the example - and I know it’s quoted directly from the PR - is incorrect and it should be simply the positive number 5.

[123 (Taras)]

I agree with you; I quoted the original text without alterations and it’s unlikely it returns -5 instead of 5.

What I did modify were the examples for is_numeric. The proposed function was originally called isnumber and that’s how it appears in the PR’s examples. Beyond that, I didn’t make any other corrections.

[francisp (Francis)]

I asked the question last Thursday, on the advice of tom_l I changed all my

{{ "abc" | float }}

to

{{ "abc" | float(0) }}

Does that work, or do I need

{{ "abc" | float(default=0) }}

Specify default value for | float

If this is a question about the 2021.10 beta it is best asked in the #beta channel on discord. But this is the way: The temperature is {{ my_test_json.temperature | float(0) }} {{ my_test_json.unit }}

[123 (Taras)]

I don’t think the default= is required (I believe it’s just a documentation convention).

For comparison, here’s the documentation for timestamp_custom.

Filter timestamp_custom(format_string, local_time=True) converts an UNIX timestamp to its string representation based on a custom format, the use of a local timezone is default.

If you include the option’s name, the Jinja2 interpreter complains:

[123 (Taras)]

The following note makes me wonder what should be supplied as the default for all of the timestamp-related functions like as_timestamp, strptime, timestamp_local, etc?

In Home Assistant core 2021.12 the template will fail to render if no default value is specified.

Perhaps something like this where now() represents the default value?

{{ 'foo' | timestamp_local(now()) }}

[tom_l]

@123

wonder what should be supplied as the default for all of the timestamp-related functions

I asked exactly that in the beta. Got no response.

[koying (Chris B)]

Even the code tests don’t make sense to me

    # Test handling of default return value
    assert render(hass, "{{ None | timestamp_local(1) }}") == 1
    assert render(hass, "{{ None | timestamp_local(default=1) }}") == 1

What is a datetime of “1”?

In all fairness, before this, the function returned the input in case of errors (i.e. the timestamp) which is quite wrong in the first place…
This is the kind of functions that should just fail if the conversion cannot be done. I don’t think returning a default value makes much sense.

[finity]

@koying

What is a datetime of “1”?

one second after midnight on 1/1/1970?

at least that’s what I would think since it’s a timestamp.

[koying (Chris B)]

Fact is timestamp_local is supposed to return a python datetime, not a timestamp
So a default return value of “1” doesn’t make any sense…

[petro]

I think it makes sense if you want to capture a failure. I.e. set the default to 1 or none and check against it later on in the code. Or don’t bother checking against it and it will be ‘unavailable’.

{{ None | timestamp_local(none) }}

[123 (Taras)]

FWIW, here’s what it currently does (2021.9.7)

[finity]

you’re right. good point.

[koying (Chris B)]

Both are actually valid, so that’s quite a proper test. This is more fun

EDIT: Actually now() ... is not valid, my mistake. It just returns now() as-is.

[petro]

I’m running the dev build and timestamp_local doesn’t have default kwarg, so it’s possible the docs are wrong. It also doesn’t accept arguments.

EDIT: It seems like it will just produce the warning but it does not accept arguments or default kwarg.

EDIT2: My dev build is a week old. That might be it.

[123 (Taras)]

I know it currently does ‘garbage in, garbage out’ (and your eyes are better than mine because magenta text on a dark background is evil).

The examples I posted were meant to confirm finity’s speculation, except the result also includes timezone offset (so that’s why it is before the Unix Epoch).

[petro]

@123

I know it currently does ‘garbage in, garbage out’

This is how strptime/strftime has always worked and timestamp_local is just an extension of that. That’s why I’m skeptical default kwarg or argument is valid.

[petro]

Well, it appears my build is outdated. It’s definitely an option:

home-assistant/core/blob/3e89ebb1cb531c9fe4d9ed78d22b00a764eab4d7/homeassistant/helpers/template.py#L1389

[koying (Chris B)]

Yep. And _SENTINEL is an empty object, FWIW. Just used as a dummy value.

[petro]

So then using None is preferred IMO if you want to have a valid date or unavailable.