Add docs for as_function and apply #38730
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe documentation for Home Assistant templating has been updated to include expanded information on Jinja extensions and advanced macro usage. The updates describe the addition of the "Expression Statement" extension ( Changes
Sequence Diagram(s)sequenceDiagram
participant Template as Jinja Template
participant Macro as Macro with returns argument
participant as_function as as_function Filter
participant apply as apply Function
participant User as Template User
User->>Template: Define macro with returns argument
Template->>Macro: Call macro with returns=callback
Macro->>returns: Invoke returns with value (e.g., dict, number)
User->>as_function: Convert macro to callable function
as_function->>Macro: Provide returns callback
Macro-->>as_function: Return native value via returns
User->>apply: Use apply to invoke macro/function with parameters
apply->>Macro: Call macro/function with arguments
Macro-->>apply: Return result (native type)
apply-->>User: Provide result in template context
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
⏰ Context from checks skipped due to timeout of 90000ms (3)
🔇 Additional comments (6)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
source/_docs/configuration/templating.markdown (1)
106-114: Macro example is clear and functional
Themacro_is_switchsnippet correctly demonstrates usingdo returns(...)and converting to a callable viaas_function.
Consider switching the code-fence language fromtexttojinjafor syntax highlighting.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_docs/configuration/templating.markdown(3 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (3)
source/_docs/configuration/templating.markdown (3)
67-67: Addition of Expression Statement extension looks good
Including thedo(Expression Statement) extension is correct for enabling side-effect statements in macros.
102-104: Great explanation of non-string macro returns
The description of passing areturnsargument and converting a macro withas_functionis accurate and clear.
118-119: Good summary of exporting utility functions
The closing remark effectively reinforces that you can return native types instead of only rendering strings.
| ### Working with macros | ||
|
|
||
| Home Assistant provides two additional functions that make macros much more powerful. | ||
|
|
||
| - `apply` is both a filter and a test that allows you to use any callable (macros or functions) wherever | ||
| you can use other filters and tests. `apply` also passes along any additional parameters to the function. | ||
| For example, if you had a function called `double`, you could call | ||
| `{{ [1, 2, 3, 4] | map('apply', double) | list }}`, which would render as `[2, 4, 6, 8]`. | ||
| Alternatively, if you had a function called `is_multiple_of`, you could call | ||
| `{{ [1, 2, 3, 4] | select('apply', is_multiple_of, 2) | list }}`, which would render as `[2, 4]`. | ||
| - `as_function` is a filter that takes a macro that has a named parameter called `returns`. The macro can | ||
| then call `{%- do returns(return_value) -%}`. After passing this macro into `as_function`, the resulting | ||
| function returns your return value directly, preserving the underlying data type rather than rendering | ||
| a string. You can return dictionaries, numbers, `True`/`False` (allowing you to write your own tests when | ||
| used with `apply`), or any other value your code might produce. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Consolidate duplicate macro documentation
The bottom "Working with macros" section overlaps the earlier explanation under "Reusing templates". To avoid confusion, consolidate into one location—ideally under this dedicated section—and remove or relocate the earlier snippet.
Example diff to remove the earlier block (lines 102–120):
--- a/source/_docs/configuration/templating.markdown
+++ b/source/_docs/configuration/templating.markdown
@@ -102,19 +102,6 @@
-Home Assistant also allows you to write macros with non-string return values by
-taking a named argument called `returns` and calling it with a return value. Once created,
-pass the macro into the `as_function` filter to use the returned value:
-
-```text
-{%- macro macro_is_switch(entity_name, returns) -%}
- {%- do returns(entity_name.startswith('switch.')) -%}
-{%- endmacro -%}
-{%- set is_switch = macro_is_switch | as_function -%}
-{{ "It's a switch!" if is_switch("switch.my_switch") else "Not a switch!" }}
-```
-
-In this way, you can export utility functions that return scalar or complex values rather than
-just macros that render to strings.
-Then reference this content solely in the "Working with macros" section below.
<!-- This is an auto-generated comment by CodeRabbit -->
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
source/_docs/configuration/templating.markdown (2)
102-120: Remove duplicatedas_functionexample
This snippet under Reusing templates duplicates the detailed documentation introduced later in the "Working with macros" section. To avoid confusion, consolidate into a single location (preferably the dedicated "Working with macros" section) as suggested in a previous review.
100-101:⚠️ Potential issueFix raw block closing tag
The current closing tag{$ endraw }}is invalid and will break the build. It should be:- {$ endraw }} + {% endraw %}
🧹 Nitpick comments (2)
source/_docs/configuration/templating.markdown (2)
67-67: Consistent Jinja extension version links
You’ve added the Expression Statement extension (do), which is great. To keep link styles consistent, consider using the same version path for both extensions. For example, change the Loop Controls link to/en/latest/extensions/#loop-controlsor update the Expression Statement link to/en/3.0.x/extensions/#expression-statement.
1378-1396: Documentapplyandas_functionfilters
This new section clearly explains theapplyandas_functionfeatures. Consider adding a minimal code block example withjinjasyntax highlighting for theapplyuse case, for instance:{{ [1,2,3] | map('apply', double) | list }}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_docs/configuration/templating.markdown(4 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (1)
source/_docs/configuration/templating.markdown (1)
83-83: Explicitjinjasyntax highlighting
Adding thejinjalanguage tag to the code block improves readability in rendered docs.
Proposed change
Adds documentation for
as_functionandapplyas described here: home-assistant/core#142033 home-assistant/core#144227Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
applyandas_functionfunctions, demonstrating advanced template processing techniques.