updated docs for #82

Author: craigbarratt

docs/new_features.rst

@@ -18,29 +18,33 @@ The new features since 0.32 in master include:
 
 - Pyscript state variables (entity_ids) can be persisted across pyscript reloads and HASS restarts,
   from @swazrgb and @dlashua (#48).
-- The ``hass`` object is available in all pyscript global contexts if the ``hass_is_global`` configuration parameter
-  is true (default false). This allows access to HASS internals that might not be otherwise exposed by pyscript.
-  Use with caution (#51).
-- Improvements to UI config flow, including allowing parameters to be updated, and the UI reload now works the same
-  as the ``pyscript.reload`` service call, submitted by @raman325 (#53)
+- ``@state_trigger`` now supports triggering on an attribute change with ``"domain.entity.attr"`` and
+  any attribute change with ``"domain.entity.*"``, submitted by @dlashua (#82)
 - State variables now support virtual attributes ``last_changed`` and ``last_updated`` for the UTC time when state
   values or any attribute was last changed.
+- State variable values (eg, from ``domain.entity`` or ``state.get()``) now include attributes that can be accessed
+  after they are assigned to another, normal, variable.
 - ``@state_trigger`` and ``task.wait_until`` now have an optional ``state_hold`` duration in seconds that requires
   the state trigger to remain true for that period of time. The trigger occurs after that time elapses. If the state
   trigger changes to false before the time expires, the process of waiting for a new trigger starts over.
 - ``@time_active`` now has an optional ``hold_off`` duration in seconds, which ignores a new trigger if the last
   one happened within that time.  Can be used for rate limiting or debouncing. Also, ``@time_active`` can now take
   zero time range arguments, in case you want to just specify ``hold_off``.
+- The ``hass`` object is available in all pyscript global contexts if the ``hass_is_global`` configuration parameter
+  is true (default false). This allows access to HASS internals that might not be otherwise exposed by pyscript.
+  Use with caution (#51).
+- Improvements to UI config flow, including allowing parameters to be updated, and the UI reload now works the same
+  as the ``pyscript.reload`` service call, submitted by @raman325 (#53)
 - Added inbound ``context`` variable to trigger functions and support optional ``context`` setting on state,
   event firing and service calls. Proposal and PR by @dlashua (#50, #60).
-- Logbook now supported using ``context`` and informational message based on trigger type. Proposal and PR by
-  @dlashua (#50, #62).
+- Logbook now supported using ``context`` and informational message based on trigger type. Proposal and PR
+  by @dlashua (#50, #62).
 - Required Python packages can be specified in ``requirements.txt`` files at the top-level pyscript
   directory, and each module's or app's directory. Those files are read and any missing packages are
   installed on HASS startup and pyscript reload. If a specific version of a package is needed, it must be
   pinned using the format 'package_name==version'. Contributed by @raman325 (#66, #68, #69, #70, #78).
-- State variable attributes can be set by direct assignment, eg: ``DOMAIN.name.attr = value``. A
-  equivalent new function ``state.setattr()`` allows a specific attribute to be set.
+- State variable attributes can be set by direct assignment, eg: ``DOMAIN.name.attr = value``.
+  An equivalent new function ``state.setattr()`` allows a specific attribute to be set.
 - The reload service now takes an optional parameter ``global_ctx`` that specifies just that
   global context is reloaded, eg: ``global_ctx="file.my_scripts"``.  Proposed by @dlashua (#63).
 - The ``state.get_attr()`` function has been renamed ``state.getattr()``. The old function is
@@ -56,12 +60,14 @@ The new features since 0.32 in master include:
   down.
 - Service calls now accept ``blocking`` and ``limit`` parameters. The default behavior for a service call is
   to run it in the background, but using ``blocking=True`` will force a task to wait up to ``limit`` seconds
-  for the service call to finish executing before continuing. Contributed by @raman325 (#85)
+  for the service call to finish executing before continuing. Contributed by @raman325 (#85).
 
 The bug fixes since 0.32 in master include:
 
+- The ``@state_trigger`` expression is only evaluated when at least one of specific state variable
+  or attribute values mentioned in the expression have changed; fixed by @dlashua (#82).
 - Jupyter autocomplete now works on multiline code blocks.
 - Improved error message reporting for syntax errors inside f-strings.
-- Fixed incorrect global context update on calling module that, in turn, does a callback (#58)
-- `task.wait_until` no longer silently ignores unrecognized keyword arguments (#80)
-- `task.wait_until` incorrectly ignored the keyword optional state_check_now argument (#81)
+- Fixed incorrect global context update on calling module that, in turn, does a callback (#58).
+- `task.wait_until` no longer silently ignores unrecognized keyword arguments (#80).
+- `task.wait_until` incorrectly ignored the keyword optional state_check_now argument (#81).

docs/reference.rst

@@ -111,8 +111,8 @@ State variables can be accessed in any Python code simply by name. State variabl
 ``entity_id``) are of the form ``DOMAIN.name``, where ``DOMAIN`` is typically the name of the
 component that sets that variable. You can set a state variable by assigning to it.
 
-State variables only have string values, so you will need to convert them to ``int`` or ``float`` if
-you need their numeric value.
+State variables only have string values, so you will need to convert them to ``int`` or ``float``
+if you need their numeric value.
 
 State variables have attributes that can be accessed by adding the name of the attribute, as in
 ``DOMAIN.name.attr``. The attribute names and their meaning depend on the component that sets them,
@@ -133,8 +133,20 @@ component has a state variable name that collides with one of its services, you
 
 Accessing state variables that don't exist will throw a ``NameError`` exception, and accessing
 an attribute that doesn't exist will throw a ``AttributeError`` exception. One exception (!)
-to this that in a ``@state_trigger`` expression, undefined state variables will evaluate to
-``None`` instead of throwing an exception.
+to this that in a ``@state_trigger`` expression, undefined state variables and attributes will
+evaluate to ``None`` instead of throwing an exception.
+
+You can assign a state variable (or the return value of ``state.get()``) to a normal Python variable,
+and that variable will capture the value and attributes of the state variable at the time of the
+assignment. So, for example, after this assignment:
+
+.. code:: python
+
+   test1_state = binary_sensor.test1
+
+the variable ``test1_state`` captures both the value and attributes of ``binary_sensor.test1``.
+Later, if ``binary_sensor.test1`` changes, ``test1_state`` continues to represent the previous
+value and attributes at the time of the assignment.
 
 State variables also support virtual methods that are service calls with that ``entity_id``.
 For any state variable ``DOMAIN.ENTITY``, any services registered by ``DOMAIN``, eg:
@@ -249,10 +261,12 @@ function.
 
 ``@state_trigger`` takes one or more string arguments that contain any expression based on one or
 more state variables, and evaluates to ``True`` or ``False`` (or non-zero or zero). Whenever the
-state variables mentioned in the expression change, the expression is evaluated and the trigger
-occurs if it evaluates to ``True`` (or non-zero). For each state variable, eg: ``domain.name``,
-the prior value is also available to the expression as ``domain.name.old`` in case you want to
-condition the trigger on the prior value too.
+state variables or attributes values mentioned in the expression change, the expression is evaluated
+and the trigger occurs if it evaluates to ``True`` (or non-zero). For each state variable,
+eg: ``domain.name``, the prior value is also available to the expression as ``domain.name.old``
+in case you want to condition the trigger on the prior value too. Attribute values can be used
+in the expression too, using the forms ``domain.name.attr`` and ``domain.name.old.attr`` for
+the new and old attribute values respectively.
 
 Multiple ``str_expr`` arguments are logically "or"ed together, so the trigger occurs if any of the
 expressions evaluate to ``True``. Any argument can alternatively be a list or set of strings, and
@@ -297,24 +311,36 @@ You can also use state variable attributes in the trigger expression, with an id
 form ``DOMAIN.name.attr``. Attributes maintain their original type, so there is no need to cast
 then to another type.
 
-You can specify a state trigger on any change with a string that is just the state variable name:
+You can specify a state trigger on any change with a string that can take three forms:
+``"domain.entity"``
+  triggers on any change to the state variable value
+``"domain.entity.attr"``
+  triggers on any change to the state variable attribute ``attr`` value
+``"domain.entity.*"``
+  triggers on any change to any state variable attribute (but not its value)
+
+For example:
 
 .. code:: python
 
    @state_trigger("domain.light_level")
 
-If you use this form, there's no point in also specifying ``state_hold`` since the expression
-is always ``True`` whenever the state variable changes - there is no way for it to evaluate
-to ``False`` and to re-start the trigger process. If you do specify ``state_hold`` in this
-case it will simply delay the trigger by the specified time.
+will trigger any time the value of ``domain.light_level`` changes (not its attributes), which
+includes the cases when that variable is first created (ie, the ``old_value`` is ``None``)
+and when it is deleted (ie, the ``value`` is ``None``).
+
+If you use the "any change" form, there's no point in also specifying ``state_hold`` since the
+expression is always ``True`` whenever the state variable changes - there is no way for it to
+evaluate to ``False`` and to re-start the trigger process. If you do specify ``state_hold`` in
+this case it will simply delay the trigger by the specified time.
 
 The trigger can include arguments with any mixture of string expressions (that are evaluated
-when any of the underlying state variables change) and string state variable names (that trigger
-whenever that variable changes).
+when any of the underlying state variables change) and string state variable or attribute
+names (that trigger whenever that variable or attribute changes).
 
-Note that if a state variable is set to the same value, HASS doesn’t generate a state change event,
-so the ``@state_trigger`` condition will not be checked. It is only evaluated each time a state
-variable changes to a new value.
+Note that if a state variable and attributes are set to the same value, HASS doesn’t generate a
+state change event, so the ``@state_trigger`` condition will not be checked. It is only evaluated
+each time a state variable or any of its attributes change to a new value.
 
 When the trigger occurs and the function is executed (meaning any active checks passed too), keyword
 arguments are passed to the function so it can tell which state variable caused it to succeed and
@@ -329,6 +355,11 @@ run, in cases where the trigger condition involves multiple variables. These are
        "old_value": old_value
    }
 
+The ``value`` and ``old_value`` represent the current and old values of the state variable
+``var_name`` whose change caused the trigger. Those variables include the state attributes too.
+If the trigger occurs when the state variable is newly created, ``old_value`` will be ``None``,
+and if the trigger occurs when a state variable is deleted, ``value`` will be ``None``.
+
 If your function needs to know any of these values, you can list the keyword arguments you need,
 with defaults:
 
@@ -1304,6 +1335,9 @@ You can use ``hass`` to compute sunrise and sunset times using the same method H
    sunset = location.sunset(datetime.datetime.today()).replace(tzinfo=None)
    print(f"today sunrise = {sunrise}, sunset = {sunset}")
 
+(Note that the ``sun.sun`` attributes already provide times for the next sunrise and sunset, so
+this example is a bit contrived.)
+
 Here's another method that uses the installed version of ``astral`` directly, rather than the HASS
 helper function.  It's a bit more cryptic since it's a very old version of ``astral``, but you can
 see how the HASS configuration values are used: