Repository navigation
Docs: how to read an attribute's old and new values (#433) - #922
Merged
craigbarratt merged 1 commit intoNov 22, 2026
Merged
craigbarratt merged 1 commit into
craigbarratt merged 1 commit into
Conversation
…nts#433) The state trigger docs said value and old_value "include the state attributes too" but not how to use that. Say that var_name is always the entity, that value and old_value are its state, and that an attribute's new and old values are value.attr and old_value.attr. Add a short example that copes with old_value being None (new entity) and a missing attribute. Signed-off-by: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com>
Member
|
Thanks @HoneyBearTech, this is accurate and clears up #433. Merging. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #433
What was broken
The docs for
@state_triggersay thatvalueandold_value"include the state attributes too", but not how to use that. It is easy to guess wrong, for example thatvar_nameis the attribute, or that there is no way to get an attribute's old value:Why
valueandold_valueonly said they "include the state attributes too". It never said how to read an attribute, thatvar_nameis always the entity, or what happens whenold_valueisNoneor an attribute is missing.What I changed
@state_triggersection ofdocs/reference.rst. The paragraph now says:var_nameis always the state variable (entity) whose change caused the trigger, even when the trigger is on one of its attributes;valueandold_valueare the current and old values of that state variable, and an attribute's new and old values arevalue.attrandold_value.attr;old_valueisNonewhen the variable is newly created,valueisNonewhen it is deleted (the existing warning, kept), and an attribute the variable doesn't have raisesAttributeError.getattr(value, "brightness", None)andgetattr(old_value, "brightness", None).Testing
No code changed, so no new committed test. I ran the example's behaviour against pyscript in a throwaway test (not committed) with
@state_trigger("pyscript.light.brightness")and@state_trigger("pyscript.other"):var_nameis the entity,valueandold_valueare both"on", and the new and old brightness are 200 and 100;old_value.brightnessis missing, andgetattr(old_value, "brightness", None)givesNone;old_valueisNone, andgetattr(None, "brightness", None)givesNone;valueisNone.The full test suite, ruff, pylint, mypy, codespell and
sphinx-build -Wpass on Python 3.14.Docs
This is the docs change: one rewritten paragraph and one example in the
@state_triggersection ofdocs/reference.rst. Nothing else changes.Note
"light.kitchen.brightness") doesn't fire when an entity is created without that attribute. That is the existing behaviour and I didn't describe or change it here.docs/reference.rst, a few paragraphs above this one. The two merge cleanly in either order. This PR doesn't touch code, so it doesn't overlap with my other open PRs.