added watch kwarg to @state_trigger, allowing state.get() inside the trigger expression; see #165

Author: craigbarratt

custom_components/pyscript/eval.py

@@ -373,6 +373,7 @@ async def trigger_init(self):
                 "state_hold": {int, float},
                 "state_check_now": {bool, int},
                 "state_hold_false": {int, float},
+                "watch": {set, list},
             },
         }
 

custom_components/pyscript/state.py

@@ -89,6 +89,7 @@ async def get_service_params(cls):
     async def notify_add(cls, var_names, queue):
         """Register to notify state variables changes to be sent to queue."""
 
+        added = False
         for var_name in var_names if isinstance(var_names, set) else {var_names}:
             parts = var_name.split(".")
             if len(parts) != 2 and len(parts) != 3:
@@ -97,6 +98,8 @@ async def notify_add(cls, var_names, queue):
             if state_var_name not in cls.notify:
                 cls.notify[state_var_name] = {}
             cls.notify[state_var_name][queue] = var_names
+            added = True
+        return added
 
     @classmethod
     def notify_del(cls, var_names, queue):

custom_components/pyscript/trigger.py

@@ -777,6 +777,7 @@ def __init__(
         self.state_hold = self.state_trigger_kwargs.get("state_hold", None)
         self.state_hold_false = self.state_trigger_kwargs.get("state_hold_false", None)
         self.state_check_now = self.state_trigger_kwargs.get("state_check_now", False)
+        self.state_user_watch = self.state_trigger_kwargs.get("watch", None)
         self.time_trigger = trig_cfg.get("time_trigger", {}).get("args", None)
         self.time_trigger_kwargs = trig_cfg.get("time_trigger", {}).get("kwargs", {})
         self.event_trigger = trig_cfg.get("event_trigger", {}).get("args", None)
@@ -921,12 +922,23 @@ async def trigger_watch(self):
 
             if self.state_trigger is not None:
                 self.state_trig_ident = set()
-                if self.state_trig_eval:
-                    self.state_trig_ident = await self.state_trig_eval.get_names()
-                self.state_trig_ident.update(self.state_trig_ident_any)
+                if self.state_user_watch:
+                    if isinstance(self.state_user_watch, list):
+                        self.state_trig_ident = set(self.state_user_watch)
+                    else:
+                        self.state_trig_ident = self.state_user_watch
+                else:
+                    if self.state_trig_eval:
+                        self.state_trig_ident = await self.state_trig_eval.get_names()
+                    self.state_trig_ident.update(self.state_trig_ident_any)
                 _LOGGER.debug("trigger %s: watching vars %s", self.name, self.state_trig_ident)
-                if len(self.state_trig_ident) > 0:
-                    await State.notify_add(self.state_trig_ident, self.notify_q)
+                if len(self.state_trig_ident) == 0 or not await State.notify_add(
+                    self.state_trig_ident, self.notify_q
+                ):
+                    _LOGGER.error(
+                        "trigger %s: @state_trigger is not watching any variables; will never trigger",
+                        self.name,
+                    )
 
             if self.active_expr:
                 self.state_active_ident = await self.active_expr.get_names()

docs/new_features.rst

@@ -39,8 +39,11 @@ The new features since 1.2.1 in master include:
   arguments. The default continues to be ``pyscript.FUNC_NAME``.
 - Added ``@pyscript_executor`` decorator, which does same thing as ``@pyscript_compile`` and additionally wraps
   the resulting function with a call to ``task.executor``.  See #71.
+- Added ``watch`` keyword argument to ``@state_trigger``, which allows the list or set of state variables that
+  are monitored to be specified. Normally that list is extracted from the ``@state_trigger`` expression.
 - Errors in trigger-related decorators (eg, wrong arguments, unregonized decorator type) raise exceptions rather
   than logging an error.
+- Types of keyword arguments to trigger decorators are now checked and exceptions raised if incorrect.
 - Added error checking for ``@pyscript_compile`` and ``@pyscript_executor`` to enforce there are no args or kwargs.
 
 Breaking changes since 1.2.1 include:

docs/reference.rst

@@ -400,6 +400,16 @@ Optional arguments are:
   to the function.  That could save several lines of code in the function determining which trigger
   occurred.
 
+``watch=None``
+  Specifies a list or set of string state variable names (entity names) that are monitored for
+  this trigger.  When (and only when) any variable in this set changes, the trigger expression
+  is evaluated. Normally this set of names is automatically extracted from the ``@state_trigger``
+  expression, but there could be cases where it doesn't capture all the names (eg, if you have to
+  use ``state.get()`` inside the trigger expression). You could also use ``watch`` to specify a
+  subset of the names in the trigger expression, which has the effect of rendering those other
+  variables as only conditions in the trigger expression that won't cause a trigger themselves,
+  since the expression won't be evaluated when they change.
+
 Here's a summary of the trigger behavior with these parameter settings:
 
 =================== ==================== ================= ========================

tests/test_decorator_errors.py

@@ -136,6 +136,10 @@ def func_wrapup():
     seq_num += 1
     pyscript.done = seq_num
 
+@state_trigger("z")
+def func8():
+    pass
+
 """,
     )
     seq_num = 0
@@ -165,6 +169,10 @@ def func_wrapup():
         in caplog.text
     )
     assert "SyntaxError: invalid syntax (file.hello.func3 @state_active(), line 1)" in caplog.text
+    assert (
+        "trigger file.hello.func8: @state_trigger is not watching any variables; will never trigger"
+        in caplog.text
+    )
     assert (
         """Exception in <file.hello.func5 @state_trigger()> line 1:
     1 / int(pyscript.var1)
@@ -392,3 +400,41 @@ def func7():
         "TypeError: function 'func7' defined in file.hello: decorator @task_unique invalid keyword argument 'arg'"
         in caplog.text
     )
+
+
+async def test_decorator_kwargs3(hass, caplog):
+    """Test invalid keyword arguments type generates an error."""
+
+    await setup_script(
+        hass,
+        None,
+        dt(2020, 7, 1, 11, 59, 59, 999999),
+        """
+@state_trigger("abc.xyz", kwargs=10)
+def func7():
+    pass
+""",
+    )
+    assert (
+        "TypeError: function 'func7' defined in file.hello: decorator @state_trigger keyword 'kwargs' should be type dict"
+        in caplog.text
+    )
+
+
+async def test_decorator_kwargs4(hass, caplog):
+    """Test invalid keyword arguments type generates an error."""
+
+    await setup_script(
+        hass,
+        None,
+        dt(2020, 7, 1, 11, 59, 59, 999999),
+        """
+@state_trigger("abc.xyz", watch=10)
+def func7():
+    pass
+""",
+    )
+    assert (
+        "TypeError: function 'func7' defined in file.hello: decorator @state_trigger keyword 'watch' should be type list or set"
+        in caplog.text
+    )

tests/test_function.py

@@ -346,15 +346,15 @@ def func6a(var_name=None, value=None):
     log.info(f"func6a var = {var_name}, value = {value}")
     pyscript.done = [seq_num, var_name, value.attr1]
 
-@state_trigger("pyscript.f6bvar1.attr3")
+@state_trigger("pyscript.f6bvar1.attr3", watch=["pyscript.f6bvar1.attr3"])
 def func6b(var_name=None, value=None):
     global seq_num
 
     seq_num += 1
     log.info(f"func6b var = {var_name}, value = {value}")
     pyscript.done = [seq_num, var_name, value, pyscript.f6bvar1.attr3]
 
-@state_trigger("pyscript.f6cvar1.*")
+@state_trigger("pyscript.f6cvar1.*", watch=["pyscript.f6cvar1.*"])
 def func6c(var_name=None, value=None):
     global seq_num
 
@@ -380,7 +380,7 @@ def func7(var_name=None, value=None, old_value=None):
     secs = (pyscript.f7var1.last_updated - pyscript.f7var1.last_changed).total_seconds()
     pyscript.done = [seq_num, var_name, value, old_value, secs]
 
-@state_trigger("pyscript.f8var1 == '2'", state_check_now=True)
+@state_trigger("state.get('pyscript.f8var1') == '2'", state_check_now=True, watch={"pyscript.f8var1"})
 @time_active(hold_off=10000)
 def func8(var_name=None, value=None):
     global seq_num
@@ -397,7 +397,7 @@ def func8b(var_name=None, value=None):
     log.info(f"func8b var = {var_name}, value = {value}")
     pyscript.done = [seq_num, var_name, value]
 
-@state_trigger("pyscript.f9var1 == '2' and pyscript.f9var1.old == None")
+@state_trigger("pyscript.f9var1 == '2' and pyscript.f9var1.old == None", watch=["pyscript.f9var1"])
 @state_active("pyscript.no_such_variable is None")
 def func9(var_name=None, value=None, old_value=None):
     global seq_num