<!--
You are amazing! Thanks for contributing to our project!
Please, DO N…OT DELETE ANY TEXT from this template! (unless instructed).
-->
## Breaking change
<!--
If your PR contains a breaking change for existing users, it is important
to tell them what breaks, how to make it work again and why we did this.
This piece of text is published with the release notes, so it helps if you
write it towards our users, not us.
Note: Remove this section if this PR is NOT a breaking change.
-->
Template results are now rendered to native Python types.
Previously, a template would always result in a string (text). This made it hard to use things like lists, or numbers as a result of a template. For example, returning a list of entities or a RGB/HS/XY color.
This change may impact your existing templates, as templates now can return other types; For example, string, float, integer, boolean, lists or dictionaries.
The following templates can be impacted by this:
- Entities with templated attributes. Attributes keep their native Python type, thus if the attribute is used/processed in a template again later, the type might be different.
- Templates working with lists or mappings (dictionaries). Previously, such collection would be returned as a text, for example `[1, 2, 3, 4, 5]`. We've seen examples where such results are decoded using text processing again (e.g., by splitting the result on a `,` to get the separate values). The additional processing is no longer needed, as the returned value will be a collection now.
- Note: The entity state in Home Assistant is always a text (string). Even with native types being supported in Templates now, if a results is stored as a entity state, they will be converted to an string.
If the new templates cause you to much problems at the time (e.g., you need time to migrate), you can enable the old behavior again by setting the following core configuration:
```yaml
homeassistant:
legacy_templates: true
```
Please note, this is a transitional option, which will be removed in the future.
## Proposed change
<!--
Describe the big picture of your changes here to communicate to the
maintainers why we should accept this pull request. If it fixes a bug
or resolves a feature request, be sure to link to that issue in the
additional information section.
-->
This has been discussed so many times in the past. Today I decided to just go, try and see.
This PR add support for native Python types as a template result. This means, template results are parsed to their native Python counterparts, instead of the current situation: "always a string".
Inspiration for this comes from Jinja2 itself, the `NativeEnvironment`:
- <https://jinja.palletsprojects.com/en/2.11.x/nativetypes/>
- <https://github.com/pallets/jinja/blob/master/src/jinja2/nativetypes.py>
The template result is passed into [`ast.literal_eval`](https://docs.python.org/3/library/ast.html#ast.literal_eval) to safely evaluate it into a Python native type.
Actual code change: d698c92
All the rest if to adjust to that change.
A core configuration option has been added to restore the old behavior.
```yaml
homeassistant:
legacy_templates: true
```
This helps users running into issues of having a way out of it and complete the migration on their own in a later tempo.
## Notes
⚠️ This is a big big big change, one that we might not even merge maybe? This is a really big/hard approach, with possibly high impact. However, considering the changes needed to make all tests pass, I actually think it ain't as bad as I originally expected.
This PR should get a couple of reviews.
## Examples
Example test sensor:
```yaml
- platform: template
sensors:
native_types:
friendly_name: Native Types
unit_of_measurement: items
icon_template: >-
{% if states('sensor.unavailable_entities') | int == 0 %}
mdi:check-circle
{% else %}
mdi:alert-circle
{% endif %}
value_template: >-
{% if states('sensor.uptime_in_uren') | float > 0.05 | float %}
{{states|selectattr('state', 'in', ['unavailable','unknown','none'])
|reject('in', expand('group.entity_exclude'))
|reject('eq', states.group.entity_exclude)
|list|length}}
{% else %}
0
{% endif %}
attribute_templates:
entities: >-
{{states|selectattr('state', 'in', ['unavailable','unknown','none'])
|reject('in', expand('group.entity_exclude'))
|reject('eq' , states.group.entity_exclude)
|map(attribute='entity_id')|list}}
float: >-
{{ 1.0 }}
int: >-
{{ 10 }}
bool: >-
{{ true }}
list: >-
{{ [1, 2, 3, 4, 5] }}
dict: >-
{{ {'a':1,'b':1, 'c':1} }}
complex: >-
{{ [{'a':1,'b':1, 'c':1}, 1, true, 1.0] }}
string: >-
{{ "Native stringy thingy" }}
none: >-
{{ None }}
```
Example template for testing in developer tools:
```
{{ states.sensor.native_types.attributes.string | to_json }}
{{ states.sensor.native_types.attributes.bool | to_json }}
{{ states.sensor.native_types.attributes.float | to_json }}
{{ states.sensor.native_types.attributes.int | to_json }}
{{ states.sensor.native_types.attributes.list | to_json }}
{{ states.sensor.native_types.attributes.dict | to_json }}
->{{ states.sensor.native_types.attributes.none }}<-
{{ states.sensor.native_types.attributes.complex | to_json }}
Native? = {{ states.sensor.native_types.attributes.complex[2] }}
Native? = {{
states.sensor.native_types.attributes.complex[0]['a']
+ states.sensor.native_types.attributes.complex[3]
}}
More advanced template result:
{{ states.sensor.native_types.attributes.entities }}
```
![image](https://user-images.githubusercontent.com/195327/95029897-f2589d00-06ab-11eb-85f1-5f912d616807.png)
## Type of change
<!--
What type of change does your PR introduce to Home Assistant?
NOTE: Please, check only 1! box!
If your PR requires multiple boxes to be checked, you'll most likely need to
split it into multiple PRs. This makes things easier and faster to code review.
-->
- [ ] Dependency upgrade
- [ ] Bugfix (non-breaking change which fixes an issue)
- [ ] New integration (thank you!)
- [ ] New feature (which adds functionality to an existing integration)
- [x] Breaking change (fix/feature causing existing functionality to break)
- [ ] Code quality improvements to existing code or addition of tests
## Additional information
<!--
Details are important, and help maintainers processing your PR.
Please be sure to fill out additional details, if applicable.
-->
- This PR fixes or closes issue: fixes #
- This PR is related to issue:
- Link to documentation pull request: https://github.com/home-assistant/home-assistant.io/pull/14999
## Checklist
<!--
Put an `x` in the boxes that apply. You can also fill these out after
creating the PR. If you're unsure about any of them, don't hesitate to ask.
We're here to help! This is simply a reminder of what we are going to look
for before merging your code.
-->
- [x] The code change is tested and works locally.
- [x] Local tests pass. **Your PR cannot be merged unless tests pass**
- [x] There is no commented out code in this PR.
- [x] I have followed the [development checklist][dev-checklist]
- [x] The code has been formatted using Black (`black --fast homeassistant tests`)
- [ ] Tests have been added to verify that the new code works.
If user exposed functionality or configuration variables are added/changed:
- [ ] Documentation added/updated for [www.home-assistant.io][docs-repository]
If the code communicates with devices, web services, or third-party tools:
- [ ] The [manifest file][manifest-docs] has all fields filled out correctly.
Updated and included derived files by running: `python3 -m script.hassfest`.
- [ ] New or updated dependencies have been added to `requirements_all.txt`.
Updated by running `python3 -m script.gen_requirements_all`.
- [ ] Untested files have been added to `.coveragerc`.
The integration reached or maintains the following [Integration Quality Scale][quality-scale]:
<!--
The Integration Quality Scale scores an integration on the code quality
and user experience. Each level of the quality scale consists of a list
of requirements. We highly recommend getting your integration scored!
-->
- [x] No score or internal
- [ ] 🥈 Silver
- [ ] 🥇 Gold
- [ ] 🏆 Platinum
<!--
This project is very active and we have a high turnover of pull requests.
Unfortunately, the number of incoming pull requests is higher than what our
reviewers can review and merge so there is a long backlog of pull requests
waiting for review. You can help here!
By reviewing another pull request, you will help raise the code quality of
that pull request and the final review will be faster. This way the general
pace of pull request reviews will go up and your wait time will go down.
When picking a pull request to review, try to choose one that hasn't yet
been reviewed.
Thanks for helping out!
-->
To help with the load of incoming pull requests:
- [x] I have reviewed two other [open pull requests][prs] in this repository.
[prs]: https://github.com/home-assistant/core/pulls?q=is%3Aopen+is%3Apr+-author%3A%40me+-draft%3Atrue+-label%3Awaiting-for-upstream+sort%3Acreated-asc+-review%3Aapproved
<!--
Thank you for contributing <3
Below, some useful links you could explore:
-->
[dev-checklist]: https://developers.home-assistant.io/docs/en/development_checklist.html
[manifest-docs]: https://developers.home-assistant.io/docs/en/creating_integration_manifest.html
[quality-scale]: https://developers.home-assistant.io/docs/en/next/integration_quality_scale_index.html
[docs-repository]: https://github.com/home-assistant/home-assistant.io