adds optional argument state_check_now=False to @state_trigger; resolves #65

Author: craigbarratt

custom_components/pyscript/eval.py

@@ -455,7 +455,7 @@ async def do_service_call(func, ast_ctx, data):
         kwarg_check = {
             "task_unique": {"kill_me"},
             "time_active": {"hold_off"},
-            "state_trigger": {"state_hold"},
+            "state_trigger": {"state_hold", "state_check_now"},
         }
         for dec_name in trig_args:
             if dec_name not in kwarg_check and "kwargs" in trig_args[dec_name]:

custom_components/pyscript/trigger.py

@@ -535,7 +535,9 @@ def __init__(
         self.global_ctx = global_ctx
         self.trig_cfg = trig_cfg
         self.state_trigger = trig_cfg.get("state_trigger", {}).get("args", None)
-        self.state_hold_dur = trig_cfg.get("state_trigger", {}).get("kwargs", {}).get("state_hold", None)
+        self.state_trigger_kwargs = trig_cfg.get("state_trigger", {}).get("kwargs", {})
+        self.state_hold_dur = self.state_trigger_kwargs.get("state_hold", None)
+        self.state_check_now = self.state_trigger_kwargs.get("state_check_now", False)
         self.time_trigger = trig_cfg.get("time_trigger", {}).get("args", None)
         self.event_trigger = trig_cfg.get("event_trigger", {}).get("args", None)
         self.state_active = trig_cfg.get("state_active", {}).get("args", None)
@@ -677,8 +679,20 @@ async def trigger_watch(self):
                     #
                     # first time only - skip waiting for other triggers
                     #
+                    notify_type = "startup"
                     notify_info = {"trigger_type": "time", "trigger_time": None}
                     self.run_on_startup = False
+                elif self.state_check_now:
+                    #
+                    # first time only - skip wait and check state trigger
+                    #
+                    notify_type = "state"
+                    if self.state_trig_ident:
+                        notify_vars = State.notify_var_get(self.state_trig_ident, {})
+                    else:
+                        notify_vars = {}
+                    notify_info = [notify_vars, {"trigger_type": notify_type}]
+                    self.state_check_now = False
                 else:
                     if self.time_trigger:
                         now = dt_now()
@@ -725,7 +739,7 @@ async def trigger_watch(self):
                 elif notify_type == "state":
                     new_vars, func_args = notify_info
 
-                    if func_args["var_name"] not in self.state_trig_ident_any:
+                    if "var_name" not in func_args or func_args["var_name"] not in self.state_trig_ident_any:
                         if self.state_trig_eval:
                             trig_ok = await self.state_trig_eval.eval(new_vars)
                             exc = self.state_trig_eval.get_exception_long()

docs/reference.rst

@@ -206,7 +206,7 @@ function.
 
 .. code:: python
 
-    @state_trigger(str_expr, ..., state_hold=None)
+    @state_trigger(str_expr, ..., state_hold=None, state_check_now=False)
 
 ``@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
@@ -215,12 +215,21 @@ occurs if it evaluates to ``True`` (or non-zero). For each state variable, eg: `
 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.
 
-The optional ``state_hold`` is a numeric duration is seconds. If specified, the state trigger
-delays executing the trigger function for this amount of time. If the state trigger expression
-changes to ``False`` during that time, the trigger is canceled and a wait for a new trigger
-begins. If the state trigger expression changes, but is still ``True`` then the ``state_hold``
-time is not restarted - the trigger will still occur that number of seconds after the first
-state trigger.
+Optional arguments are:
+
+``state_hold=None``
+  A numeric duration in seconds that delays executing the trigger function for this amount of time.
+  If the state trigger expression changes back to ``False`` during that time, the trigger is
+  canceled and a wait for a new trigger begins. If the state trigger expression changes, but is
+  still ``True`` then the ``state_hold`` time is not restarted - the trigger will still occur
+  that number of seconds after the first state trigger.
+
+``state_check_now=False``
+  If set, the ``@state_trigger`` expression is evaluated immediately when the trigger function
+  is defined (typically at startup), and the trigger occurs if the expression evaluates
+  to ``True`` or non-zero. Normally the expression is only evaluated when a state variable
+  changes, and not when the trigger function is first defined. This option is the same as
+  in the ``task.wait_until`` function, except the default value is ``True`` in that case.
 
 Multiple 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 they are
@@ -301,6 +310,19 @@ and all those values will simply get passed in into kwargs as a ``dict``. That
 form to use if you have multiple decorators, since each one passes different variables into the
 function (although all of them set ``trigger_type``).
 
+If ``state_check_now`` is set to ``True`` and the trigger occurs during its immediate check, since
+there is no underlying state variable change, the trigger function is called with only this arguments:
+
+.. code:: python
+
+   kwargs = {
+       "trigger_type": "state",
+   }
+
+If the trigger function uses ``var_name==None`` as a keyword argument, it can check if it is ``None``
+to determined whether it was called immediately or not. Similarly, if it uses the ``kwargs``
+form, if can check if ``var_name`` is in ``kwargs``.
+
 If ``state_hold`` is specified, the arguments to the trigger function reflect the variable change
 that cause the first trigger, not any subsequent ones during the ``state_hold`` period. Also, if
 the ``@time_active`` or ``@state_active`` decorators are used, they will be evaluated after the

tests/test_function.py

@@ -1,4 +1,5 @@
 """Test the pyscript component."""
+
 from ast import literal_eval
 import asyncio
 from datetime import datetime as dt
@@ -173,7 +174,7 @@ def func_startup_sync(trigger_type=None, trigger_time=None):
     log.info(f"func_startup_sync setting pyscript.done = {seq_num}, trigger_type = {trigger_type}, trigger_time = {trigger_time}")
     pyscript.done = seq_num
 
-@state_trigger("pyscript.f1var1 == '1'")
+@state_trigger("pyscript.f1var1 == '1'", state_check_now=True)
 def func1(var_name=None, value=None):
     global seq_num
 
@@ -355,7 +356,7 @@ def func6(var_name=None, value=None):
     log.info(f"func6 var = {var_name}, value = {value}")
     pyscript.done = [seq_num, var_name, pyscript.f6var1.attr1]
 
-@state_trigger("pyscript.f7var1 == '2' and pyscript.f7var1.old == '1'")
+@state_trigger("pyscript.f7var1 == '2' and pyscript.f7var1.old == '1'", state_check_now=True)
 @state_active("pyscript.f7var1 == '2' and pyscript.f7var1.old == '1' and pyscript.no_such_variable is None")
 def func7(var_name=None, value=None, old_value=None):
     global seq_num
@@ -365,7 +366,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_trigger("pyscript.f8var1 == '2'", state_check_now=True)
 @time_active(hold_off=10000)
 def func8(var_name=None, value=None):
     global seq_num
@@ -681,3 +682,44 @@ def func_trig(var_name=None, value=None):
         seq_num += 1
         hass.states.async_set("pyscript.var1", 101)
         assert literal_eval(await wait_until_done(notify_q)) == seq_num
+
+
+async def test_state_trigger_check_now(hass, caplog):
+    """Test state trigger."""
+    notify_q = asyncio.Queue(0)
+
+    hass.states.async_set("pyscript.fstartup", 1)
+
+    await setup_script(
+        hass,
+        notify_q,
+        [dt(2020, 7, 1, 10, 59, 59, 999998), dt(2020, 7, 1, 11, 59, 59, 999998)],
+        """
+
+from math import sqrt
+from homeassistant.core import Context
+
+seq_num = 0
+
+pyscript.fstartup = 1
+
+@state_trigger("pyscript.fstartup == '1'", state_check_now=True)
+def func_startup_sync(trigger_type=None, var_name=None):
+    global seq_num
+
+    seq_num += 1
+    log.info(f"func_startup_sync setting pyscript.done={seq_num}, trigger_type={trigger_type}, var_name={var_name}")
+    pyscript.done = [seq_num, trigger_type, var_name]
+""",
+    )
+    seq_num = 0
+
+    seq_num += 1
+    # fire event to start triggers, and handshake when they are running
+    hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED)
+    assert literal_eval(await wait_until_done(notify_q)) == [seq_num, "state", None]
+
+    seq_num += 1
+    hass.states.async_set("pyscript.fstartup", 0)
+    hass.states.async_set("pyscript.fstartup", 1)
+    assert literal_eval(await wait_until_done(notify_q)) == [seq_num, "state", "pyscript.fstartup"]