Skip to content

Docs: how to read an attribute's old and new values (#433) - #922

Merged
craigbarratt merged 1 commit into
custom-components:masterfrom
HoneyBearTech:docs-attribute-old-value-433
Nov 22, 2026
Merged

craigbarratt merged 1 commit into
custom-components:masterfrom
HoneyBearTech:docs-attribute-old-value-433

Conversation

@HoneyBearTech

Copy link
Copy Markdown
Contributor

Closes #433

What was broken
The docs for @state_trigger say that value and old_value "include the state attributes too", but not how to use that. It is easy to guess wrong, for example that var_name is the attribute, or that there is no way to get an attribute's old value:

@state_trigger("light.kitchen.brightness")
def brightness_changed(var_name=None, value=None, old_value=None):
    value.brightness       # the new brightness: works, but the docs don't say so
    old_value.brightness   # the old brightness: works, but the docs don't say so
                           # (and it raises on a new entity, or one without the attribute)

Why

  • The paragraph describing value and old_value only said they "include the state attributes too". It never said how to read an attribute, that var_name is always the entity, or what happens when old_value is None or an attribute is missing.

What I changed

  • Docs only, in the @state_trigger section of docs/reference.rst. The paragraph now says:
    • var_name is always the state variable (entity) whose change caused the trigger, even when the trigger is on one of its attributes;
    • value and old_value are the current and old values of that state variable, and an attribute's new and old values are value.attr and old_value.attr;
    • old_value is None when the variable is newly created, value is None when it is deleted (the existing warning, kept), and an attribute the variable doesn't have raises AttributeError.
  • A short example that copes with all of that, using getattr(value, "brightness", None) and getattr(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"):

  • an update that changes only an attribute (brightness 100 to 200): var_name is the entity, value and old_value are both "on", and the new and old brightness are 200 and 100;
  • an attribute added to an entity that didn't have it: old_value.brightness is missing, and getattr(old_value, "brightness", None) gives None;
  • entity creation (entity-name trigger): old_value is None, and getattr(None, "brightness", None) gives None;
  • deletion: value is None.

The full test suite, ruff, pylint, mypy, codespell and sphinx-build -W pass on Python 3.14.

Docs
This is the docs change: one rewritten paragraph and one example in the @state_trigger section of docs/reference.rst. Nothing else changes.

Note

  • A trigger on a bare attribute ("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.
  • My open PR for Is it possible to use multiline strings in state trigger decorators? #617 (trigger expressions with leading blanks) adds a paragraph in the same section of 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.

…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>
@craigbarratt

Copy link
Copy Markdown
Member

Thanks @HoneyBearTech, this is accurate and clears up #433. Merging.

@craigbarratt
craigbarratt merged commit 608413f into custom-components:master Nov 22, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

How to get the 'old' value of an attribute?

2 participants