Add documentation on conditions#2885
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughDocumentation-only update to ChangesDocumentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/automations.md (2)
168-172: Strengthen instructional phrasing by fronting the goal.Line 170 uses passive voice and defers the goal. Restructure to front the action for clarity and directness, consistent with documentation guidelines.
Apply this diff to improve the instructional phrasing:
-To register the conditions `async_get_conditions` should be implemented in the `condition` platform for that integration. +Implement `async_get_conditions` in the `condition` platform to register conditions.
181-187: Optional: Make schema explanation more direct.While clear, line 183 could be more authoritative by fronting the goal rather than describing frontend behavior.
Apply this diff for a more direct tone:
-The frontend uses the `conditions.yaml` file to know the structure of the conditions. -This file is similar to `triggers.yaml` and `services.yaml`. +Define the condition structure in `conditions.yaml` for the frontend, similar to `triggers.yaml` and `services.yaml`.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
docs/automations.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
docs/automations.md
🔇 Additional comments (3)
docs/automations.md (3)
88-88: Good phrasing adjustment.The change from "example above" to "the following example" correctly describes the position of the code that immediately follows.
99-107: Clear and well-structured introduction to conditions.The section frontloads the implementation goal and correctly references the trigger class pattern for consistency.
188-198: YAML example is well-structured and accurate.The schema correctly represents the Python condition implementation and follows the expected structure for condition definitions.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/automations.md (1)
127-131: Voluptuous schema syntax is correct.The
vol.In()validator now correctly accepts a single iterable argument. This resolves the prior critical issue flagged in previous reviews.
🧹 Nitpick comments (1)
docs/automations.md (1)
168-171: Align condition registration wording with trigger registration for consistency.The conditions section should use the same direct imperative style as the parallel triggers section. Currently, line 170 uses passive construction ("should be implemented") while the triggers section uses active voice ("Implement").
Apply this diff to match the triggers section pattern:
-To register the conditions `async_get_conditions` should be implemented in the `condition` platform for that integration. +Implement `async_get_conditions` in the `condition` platform to register all the integration's conditions.As per coding guidelines, documentation should use a direct and authoritative tone with frontloaded goals.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
docs/automations.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
docs/automations.md
🔇 Additional comments (2)
docs/automations.md (2)
111-166: Condition class example is well-structured.The code implementation properly demonstrates the required methods (
async_validate_configandasync_get_checker), includes appropriate type hints, and provides clear comments explaining the logic. The schema definition is correct.
181-198: Condition schema documentation and example are clear.The explanation of
conditions.yamland its relationship to related files provides helpful context. The YAML example correctly demonstrates thedoor_statecondition schema structure with appropriate field definitions and selectors.
|
|
||
| ## Conditions | ||
|
|
||
| Conditions are checks that must be met in order for an automation to trigger. Implement them in the `condition` platform (`condition.py`) of your integration by creating and registering condition classes. |
There was a problem hiding this comment.
I would be more specific with the language here. The automation triggers when its trigger is triggered, then the automation checks any conditions, and if they are met or if there are no conditions, the automation action will be done.
| ## Conditions | ||
|
|
||
| When an automation is triggered, it may have conditions that have to be met for the action to be executed. | ||
| Conditions are created in the `condition` platform (`condition.py`) of your integration by creating and registering condition classes. |
There was a problem hiding this comment.
| Conditions are created in the `condition` platform (`condition.py`) of your integration by creating and registering condition classes. | |
| Conditions are defined in the `condition` platform (`condition.py`) of your integration by creating and registering condition classes. |
| self._state = config.options[CONF_STATE] | ||
|
|
||
| @override | ||
| async def async_get_checker(self) -> ConditionChecker: |
| # In reality this would be more configurable | ||
| # but for the sake of example it's simplified. | ||
| return self._hass.states.get("binary_sensor.front_door") == self._state | ||
|
|
There was a problem hiding this comment.
| # In reality this would be more configurable | |
| # but for the sake of example it's simplified. | |
| return self._hass.states.get("binary_sensor.front_door") == self._state | |
| # Do your condition checks here | |
| return get_example_state() == self._state | |
| ) | ||
| from homeassistant.helpers.typing import ConfigType, TemplateVarsType | ||
|
|
||
| STATE_CONDITION_SCHEMA = vol.Schema( |
There was a problem hiding this comment.
condition-specific fields should be in the CONF_OPTIONS object, right?
| ConditionChecker, | ||
| ConditionCheckParams, | ||
| ConditionConfig, | ||
| trace_condition_function, |
There was a problem hiding this comment.
| trace_condition_function, |
|
|
||
| ### Condition schema | ||
|
|
||
| The frontend uses the `conditions.yaml` file to know the structure of the conditions. |
There was a problem hiding this comment.
it is also used by core, not just for frontend
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
4 participants
Proposed change
Add documentation on conditions
Type of change
Checklist
Additional information
Summary by CodeRabbit