Added state_hold_false=None to @state_trigger and task.wait_until()

This requires the trigger expression to be ``False`` for at least that period
(including 0) before a successful trigger.  Proposed by @tchef69 (#89).

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_check_now"},
+            "state_trigger": {"state_hold", "state_check_now", "state_hold_false"},
         }
         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

@@ -151,6 +151,8 @@ async def wait_until(
         event_trigger=None,
         timeout=None,
         state_hold=None,
+        state_hold_false=None,
+        __test_handshake__=None,
     ):
         """Wait for zero or more triggers, until an optional timeout."""
         if state_trigger is None and time_trigger is None and event_trigger is None:
@@ -169,6 +171,12 @@ async def wait_until(
         state_trig_waiting = False
         state_trig_notify_info = [None, None]
 
+        #
+        # at startup we start our state_hold_false window,
+        # although it could get updated if state_check_now is set.
+        #
+        state_false_time = time.monotonic()
+
         if state_trigger is not None:
             state_trig = []
             if isinstance(state_trigger, str):
@@ -212,7 +220,13 @@ async def wait_until(
                 exc = state_trig_eval.get_exception_obj()
                 if exc is not None:
                     raise exc
-                if state_hold is not None and state_trig_ok:
+                if state_hold_false is not None:
+                    #
+                    # if state_trig_ok we wait until it is false;
+                    # otherwise we consider now to be the start of the false hold time
+                    #
+                    state_false_time = None if state_trig_ok else time.monotonic()
+                elif state_hold is not None and state_trig_ok:
                     state_trig_waiting = True
                     state_trig_notify_info = [None, {"trigger_type": "state"}]
                     last_state_trig_time = time.monotonic()
@@ -248,6 +262,14 @@ async def wait_until(
             Event.notify_add(event_trigger[0], notify_q)
         time0 = time.monotonic()
 
+        if __test_handshake__:
+            #
+            # used for testing to avoid race conditions
+            # we use this as a handshake that we are about to
+            # listen to the queue
+            #
+            State.set(__test_handshake__[0], __test_handshake__[1])
+
         while True:
             ret = None
             this_timeout = None
@@ -319,6 +341,26 @@ async def wait_until(
                         if exc is not None:
                             break
 
+                        if state_hold_false is not None:
+                            if state_false_time is None:
+                                if state_trig_ok:
+                                    #
+                                    # wasn't False, so ignore
+                                    #
+                                    continue
+                                #
+                                # first False, so remember when it is
+                                #
+                                state_false_time = time.monotonic()
+                            elif state_trig_ok:
+                                too_soon = time.monotonic() - state_false_time < state_hold_false
+                                state_false_time = None
+                                if too_soon:
+                                    #
+                                    # was False but not for long enough, so start over
+                                    #
+                                    continue
+
                 if state_hold is not None:
                     if state_trig_ok:
                         if not state_trig_waiting:
@@ -594,7 +636,8 @@ def __init__(
         self.trig_cfg = trig_cfg
         self.state_trigger = trig_cfg.get("state_trigger", {}).get("args", 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_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.time_trigger = trig_cfg.get("time_trigger", {}).get("args", None)
         self.event_trigger = trig_cfg.get("event_trigger", {}).get("args", None)
@@ -727,6 +770,11 @@ async def trigger_watch(self):
             last_state_trig_time = None
             state_trig_waiting = False
             state_trig_notify_info = [None, None]
+            #
+            # at startup we start our state_hold_false window,
+            # although it could get updated if state_check_now is set.
+            #
+            state_false_time = time.monotonic()
 
             while True:
                 timeout = None
@@ -761,7 +809,7 @@ async def trigger_watch(self):
                         if time_next is not None:
                             timeout = (time_next - now).total_seconds()
                     if state_trig_waiting:
-                        time_left = last_state_trig_time + self.state_hold_dur - time.monotonic()
+                        time_left = last_state_trig_time + self.state_hold - time.monotonic()
                         if timeout is None or time_left < timeout:
                             timeout = time_left
                             state_trig_timeout = True
@@ -798,7 +846,9 @@ async def trigger_watch(self):
                     new_vars, func_args = notify_info
 
                     if not ident_any_values_changed(func_args, self.state_trig_ident_any):
+                        #
                         # if var_name not in func_args we are state_check_now
+                        #
                         if "var_name" in func_args and not ident_values_changed(
                             func_args, self.state_trig_ident
                         ):
@@ -810,10 +860,38 @@ async def trigger_watch(self):
                             if exc is not None:
                                 self.state_trig_eval.get_logger().error(exc)
                                 trig_ok = False
+
+                            if self.state_hold_false is not None:
+                                if "var_name" not in func_args:
+                                    #
+                                    # this is state_check_now check
+                                    # if immediately true, force wait until False
+                                    # otherwise start False wait now
+                                    #
+                                    state_false_time = None if trig_ok else time.monotonic()
+                                    continue
+                                if state_false_time is None:
+                                    if trig_ok:
+                                        #
+                                        # wasn't False, so ignore
+                                        #
+                                        continue
+                                    #
+                                    # first False, so remember when it is
+                                    #
+                                    state_false_time = time.monotonic()
+                                elif trig_ok:
+                                    too_soon = time.monotonic() - state_false_time < self.state_hold_false
+                                    state_false_time = None
+                                    if too_soon:
+                                        #
+                                        # was False but not for long enough, so start over
+                                        #
+                                        continue
                         else:
                             trig_ok = False
 
-                    if self.state_hold_dur is not None:
+                    if self.state_hold is not None:
                         if trig_ok:
                             if not state_trig_waiting:
                                 state_trig_waiting = True
@@ -823,14 +901,14 @@ async def trigger_watch(self):
                                     "trigger %s got %s trigger; now waiting for state_hold of %g seconds",
                                     notify_type,
                                     self.name,
-                                    self.state_hold_dur,
+                                    self.state_hold,
                                 )
                             else:
                                 _LOGGER.debug(
                                     "trigger %s got %s trigger; still waiting for state_hold of %g seconds",
                                     notify_type,
                                     self.name,
-                                    self.state_hold_dur,
+                                    self.state_hold,
                                 )
                             continue
                         if state_trig_waiting:

docs/new_features.rst

@@ -23,8 +23,13 @@ Planned new features post 1.0.0 include:
 
 The new features since 1.0.0 in master include:
 
-- None so far
+- Added ``state_hold_false=None`` optional period in seconds to ``@state_trigger`` and ``task.wait_until()``.
+  This requires the trigger expression to be ``False`` for at least that period (including 0) before a
+  successful trigger.  Proposed by @tchef69 (#89).
 
 Bug fixes since 1.0.0 in master include:
 
-- the deprecated function ``state.get_attr`` was missing an ``await``, which caused an exception; in 1.0.0 use ``state.getattr`` instead (#88).
+- state setting now copies the attributes, to avoid a strange ``MappingProxyType`` recursion error
+  inside HASS, reported by @github392 (#87).
+- the deprecated function ``state.get_attr`` was missing an ``await``, which caused an exception; in 1.0.0 use
+  ``state.getattr``, reported and fixed by @dlashua (#88).

docs/reference.rst

@@ -257,7 +257,7 @@ function.
 
 .. code:: python
 
-    @state_trigger(str_expr, ..., state_hold=None, state_check_now=False)
+    @state_trigger(str_expr, ..., state_hold=None, state_hold_false=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 any
@@ -291,6 +291,29 @@ Optional arguments are:
   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_hold_false=None``
+  If set, the ``@state_trigger`` expression must evaluate to ``False`` for this duration in seconds
+  before the next trigger can occur. The default value of ``None`` means that triggers can occur
+  without the trigger expression having to be ``False`` between triggers. A value of ``0`` requires
+  the expression become ``False`` between triggers, but with no minimum time in that state.
+  If the expression evaluates to ``True`` during the ``state_hold_false`` period, that trigger is
+  ignored, and when the expression next is ``False`` the `state_hold_false`` period starts over.
+
+  For example, by default the expression ``"int(sensor.temp_outside) >= 50"`` will trigger every
+  time ``sensor.temp_outside`` changes to a value that is 50 or more.  If instead
+  ``state_hold_false=0``, the trigger will only occur when ``sensor.temp_outside`` changes the first
+  time to 50 or more. It has to go back below 50 for ``state_hold_false`` seconds before a new
+  trigger can occur. To summarize, the default behavior is level triggered, and setting ``state_hold_false``
+  makes it edge triggered.
+
+  The ``state_hold_false`` period applies at startup, although the expression is not checked at
+  startup if ``state_check_now==False``. So if ``state_hold_false=0`` the first trigger after startup
+  will succeed, whether or not the expression was previously ``False``. That behavior can be changed
+  by setting ``state_check_now=True``; the expression is checked at startup, and if ``True`` the
+  trigger will not occur, and a wait for the next ``False`` will begin. So setting ``state_check_now=True``
+  and ``state_hold_false`` enforces the need for the expression to be ``False`` before the first
+  trigger.
+
 All state variables in HASS have string values. So you’ll have to do comparisons against string
 values or cast the variable to an integer or float. These two examples are essentially equivalent
 (note the use of single quotes inside the outer double quotes):
@@ -852,9 +875,18 @@ It takes the following keyword arguments (all are optional):
   delays returning 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 - ``task.wait_until() will return that number of seconds after the first state
+  restarted - ``task.wait_until()`` will return that number of seconds after the first state
   trigger (unless a different trigger type or a ``timeout`` occurs first). This setting also
   applies to the initial check when ``state_check_now=True``.
+- ``state_hold_false=None`` requires the expression evaluate to ``False`` for this duration in seconds
+  before a subsequent state trigger occurs. The default value of ``None`` means that the trigger can
+  occur without the trigger expression having to be ``False``. A value of ``0`` requires the
+  expression become ``False`` before the trigger, but with no minimum time in that state.
+  With the default of ``state_check_now=True``, the state trigger expression is checked at startup,
+  and if ``True`` the trigger will not occur, and a wait for the next ``False`` will begin.
+  If ``state_check_now==False``, the ``state_hold_false`` period applies at startup, although the
+  expression is not checked at startup. So if ``state_hold_false=0`` the first trigger after startup
+  will succeed, whether or not the expression was previously ``False``.
 
 When a trigger occurs, the return value is a ``dict`` containing the same keyword values that are
 passed into the function when the corresponding decorator trigger occurs. There will always be a key