added "now" as datetime spec to mean trigger startup time; see #139

Author: craigbarratt

custom_components/pyscript/trigger.py

@@ -38,14 +38,18 @@ def parse_time_offset(offset_str):
     value = 0
     if len(match) == 4:
         value = float(match[1].replace(" ", ""))
-        if match[2] == "m" or match[2] == "min" or match[2] == "minutes":
+        if match[2] in {"m", "min", "mins", "minute", "minutes"}:
             scale = 60
-        elif match[2] == "h" or match[2] == "hr" or match[2] == "hours":
+        elif match[2] in {"h", "hr", "hour", "hours"}:
             scale = 60 * 60
-        elif match[2] == "d" or match[2] == "day" or match[2] == "days":
+        elif match[2] in {"d", "day", "days"}:
             scale = 60 * 60 * 24
-        elif match[2] == "w" or match[2] == "week" or match[2] == "weeks":
+        elif match[2] in {"w", "week", "weeks"}:
             scale = 60 * 60 * 24 * 7
+        elif match[2] not in {"", "s", "sec", "second", "seconds"}:
+            _LOGGER.error("can't parse time offset %s", offset_str)
+    else:
+        _LOGGER.error("can't parse time offset %s", offset_str)
     return value * scale
 
 
@@ -352,9 +356,12 @@ async def wait_until(
             this_timeout = None
             state_trig_timeout = False
             time_next = None
+            startup_time = None
             if time_trigger is not None:
                 now = dt_now()
-                time_next = cls.timer_trigger_next(time_trigger, now)
+                if startup_time is None:
+                    startup_time = now
+                time_next = cls.timer_trigger_next(time_trigger, now, startup_time)
                 _LOGGER.debug(
                     "trigger %s wait_until time_next = %s, now = %s", ast_ctx.name, time_next, now,
                 )
@@ -507,26 +514,27 @@ async def wait_until(
         return ret
 
     @classmethod
-    def parse_date_time(cls, date_time_str, day_offset, now):
+    def parse_date_time(cls, date_time_str, day_offset, now, startup_time):
         """Parse a date time string, returning datetime."""
         year = now.year
         month = now.month
         day = now.day
 
-        dt_str = date_time_str.strip().lower()
+        dt_str_orig = dt_str = date_time_str.strip().lower()
         #
         # parse the date
         #
-        skip = True
-        match0 = re.split(r"^0*(\d+)[-/]0*(\d+)(?:[-/]0*(\d+))?", dt_str)
-        match1 = re.split(r"^(\w+).*", dt_str)
-        if len(match0) == 5:
-            if match0[3] is None:
-                month, day = int(match0[1]), int(match0[2])
-            else:
+        match0 = re.match(r"0*(\d+)[-/]0*(\d+)(?:[-/]0*(\d+))?", dt_str)
+        match1 = re.match(r"(\w+)", dt_str)
+        if match0:
+            if match0[3]:
                 year, month, day = int(match0[1]), int(match0[2]), int(match0[3])
+            else:
+                month, day = int(match0[1]), int(match0[2])
             day_offset = 0  # explicit date means no offset
-        elif len(match1) == 3:
+            dt_str = dt_str[len(match0.group(0)) :]
+        elif match1:
+            skip = True
             if match1[1] in cls.dow2int:
                 dow = cls.dow2int[match1[1]]
                 if dow >= (now.isoweekday() % 7):
@@ -539,39 +547,38 @@ def parse_date_time(cls, date_time_str, day_offset, now):
                 day_offset = 1
             else:
                 skip = False
-        else:
-            skip = False
+            if skip:
+                dt_str = dt_str[len(match1.group(0)) :]
         if day_offset != 0:
             now = dt.datetime(year, month, day) + dt.timedelta(days=day_offset)
             year = now.year
             month = now.month
             day = now.day
         else:
             now = dt.datetime(year, month, day)
-        if skip:
-            i = dt_str.find(" ")
-            if i >= 0:
-                dt_str = dt_str[i + 1 :].strip()
-            else:
-                return now
+        dt_str = dt_str.strip()
+        if len(dt_str) == 0:
+            return now
 
         #
         # parse the time
         #
-        skip = True
-        match0 = re.split(r"0*(\d+):0*(\d+)(?::0*(\d*\.?\d+(?:[eE][-+]?\d+)?))?", dt_str)
-        if len(match0) == 5:
-            if match0[3] is not None:
+        match0 = re.match(r"0*(\d+):0*(\d+)(?::0*(\d*\.?\d+(?:[eE][-+]?\d+)?))?", dt_str)
+        if match0:
+            if match0[3]:
                 hour, mins, sec = int(match0[1]), int(match0[2]), float(match0[3])
             else:
                 hour, mins, sec = int(match0[1]), int(match0[2]), 0
+            dt_str = dt_str[len(match0.group(0)) :]
         elif dt_str.startswith("sunrise") or dt_str.startswith("sunset"):
             location = sun.get_astral_location(cls.hass)
             try:
                 if dt_str.startswith("sunrise"):
                     time_sun = location.sunrise(dt.date(year, month, day))
+                    dt_str = dt_str[7:]
                 else:
                     time_sun = location.sunset(dt.date(year, month, day))
+                    dt_str = dt_str[6:]
             except Exception:
                 _LOGGER.warning("'%s' not defined at this latitude", dt_str)
                 # return something in the past so it is ignored
@@ -580,27 +587,30 @@ def parse_date_time(cls, date_time_str, day_offset, now):
             hour, mins, sec = time_sun.hour, time_sun.minute, time_sun.second
         elif dt_str.startswith("noon"):
             hour, mins, sec = 12, 0, 0
+            dt_str = dt_str[4:]
         elif dt_str.startswith("midnight"):
             hour, mins, sec = 0, 0, 0
+            dt_str = dt_str[8:]
+        elif dt_str.startswith("now") and dt_str_orig == dt_str:
+            #
+            # "now" means the first time, and only matches if there was no date specification
+            #
+            hour, mins, sec = 0, 0, 0
+            now = startup_time
+            dt_str = dt_str[3:]
         else:
             hour, mins, sec = 0, 0, 0
-            skip = False
         now += dt.timedelta(seconds=sec + 60 * (mins + 60 * hour))
-        if skip:
-            i = dt_str.find(" ")
-            if i >= 0:
-                dt_str = dt_str[i + 1 :].strip()
-            else:
-                return now
         #
         # parse the offset
         #
-        if len(dt_str) > 0 and (dt_str[0] == "+" or dt_str[0] == "-"):
+        dt_str = dt_str.strip()
+        if len(dt_str) > 0:
             now = now + dt.timedelta(seconds=parse_time_offset(dt_str))
         return now
 
     @classmethod
-    def timer_active_check(cls, time_spec, now):
+    def timer_active_check(cls, time_spec, now, startup_time):
         """Check if the given time matches the time specification."""
         results = {"+": [], "-": []}
         for entry in time_spec if isinstance(time_spec, list) else [time_spec]:
@@ -627,10 +637,10 @@ def timer_active_check(cls, time_spec, now):
                     _LOGGER.error("Invalid range expression: %s", exc)
                     return False
 
-                start = cls.parse_date_time(dt_start.strip(), 0, now)
-                end = cls.parse_date_time(dt_end.strip(), 0, start)
+                start = cls.parse_date_time(dt_start.strip(), 0, now, startup_time)
+                end = cls.parse_date_time(dt_end.strip(), 0, start, startup_time)
 
-                if start < end:
+                if start <= end:
                     this_match = start <= now <= end
                 else:  # Over midnight
                     this_match = now >= start or now <= end
@@ -649,7 +659,7 @@ def timer_active_check(cls, time_spec, now):
         return result
 
     @classmethod
-    def timer_trigger_next(cls, time_spec, now):
+    def timer_trigger_next(cls, time_spec, now, startup_time):
         """Return the next trigger time based on the given time and time specification."""
         next_time = None
         if not isinstance(time_spec, list):
@@ -668,39 +678,41 @@ def timer_trigger_next(cls, time_spec, now):
                     next_time = val
 
             elif len(match1) == 3:
-                this_t = cls.parse_date_time(match1[1].strip(), 0, now)
-                if this_t <= now:
+                this_t = cls.parse_date_time(match1[1].strip(), 0, now, startup_time)
+                if this_t <= now and this_t != startup_time:
                     #
                     # Try tomorrow (won't make a difference if spec has full date)
                     #
-                    this_t = cls.parse_date_time(match1[1].strip(), 1, now)
-                if now < this_t and (next_time is None or this_t < next_time):
+                    this_t = cls.parse_date_time(match1[1].strip(), 1, now, startup_time)
+                startup = now == this_t and now == startup_time
+                if (now < this_t or startup) and (next_time is None or this_t < next_time):
                     next_time = this_t
 
             elif len(match2) == 5:
                 start_str, period_str = match2[1].strip(), match2[2].strip()
-                start = cls.parse_date_time(start_str, 0, now)
+                start = cls.parse_date_time(start_str, 0, now, startup_time)
                 period = parse_time_offset(period_str)
                 if period <= 0:
                     _LOGGER.error("Invalid non-positive period %s in period(): %s", period, time_spec)
                     continue
 
                 if match2[3] is None:
-                    if now < start and (next_time is None or start < next_time):
+                    startup = now == start and now == startup_time
+                    if (now < start or startup) and (next_time is None or start < next_time):
                         next_time = start
-                    if now >= start:
+                    if now >= start and not startup:
                         secs = period * (1.0 + math.floor((now - start).total_seconds() / period))
                         this_t = start + dt.timedelta(seconds=secs)
                         if now < this_t and (next_time is None or this_t < next_time):
                             next_time = this_t
                     continue
                 end_str = match2[3].strip()
-                end = cls.parse_date_time(end_str, 0, now)
+                end = cls.parse_date_time(end_str, 0, now, startup_time)
                 end_offset = 1 if end < start else 0
                 for day in [-1, 0, 1]:
-                    start = cls.parse_date_time(start_str, day, now)
-                    end = cls.parse_date_time(end_str, day + end_offset, now)
-                    if now < start:
+                    start = cls.parse_date_time(start_str, day, now, startup_time)
+                    end = cls.parse_date_time(end_str, day + end_offset, now, startup_time)
+                    if now < start or (now == start and now == startup_time):
                         if next_time is None or start < next_time:
                             next_time = start
                         break
@@ -894,13 +906,17 @@ async def trigger_watch(self):
             state_trig_waiting = False
             state_trig_notify_info = [None, None]
             state_false_time = None
+            startup_time = None
             check_state_expr_on_start = self.state_check_now or self.state_hold_false is not None
 
             while True:
                 timeout = None
                 state_trig_timeout = False
                 notify_info = None
                 notify_type = None
+                now = dt_now()
+                if startup_time is None:
+                    startup_time = now
                 if self.run_on_startup:
                     #
                     # first time only - skip waiting for other triggers
@@ -921,8 +937,7 @@ async def trigger_watch(self):
                     check_state_expr_on_start = False
                 else:
                     if self.time_trigger:
-                        now = dt_now()
-                        time_next = TrigTime.timer_trigger_next(self.time_trigger, now)
+                        time_next = TrigTime.timer_trigger_next(self.time_trigger, now, startup_time)
                         _LOGGER.debug(
                             "trigger %s time_next = %s, now = %s", self.name, time_next, now,
                         )
@@ -1066,7 +1081,7 @@ async def trigger_watch(self):
                         self.active_expr.get_logger().error(exc)
                         trig_ok = False
                 if trig_ok and self.time_active:
-                    trig_ok = TrigTime.timer_active_check(self.time_active, dt_now())
+                    trig_ok = TrigTime.timer_active_check(self.time_active, now, startup_time)
 
                 if not trig_ok:
                     _LOGGER.debug(

docs/reference.rst

@@ -537,37 +537,48 @@ Several of the time specifications use a ``datetime`` format, which is ISO: ``yy
 with the following features:
 
 - There is no time-zone (local is assumed).
-- Seconds can include a decimal (fractional) portion if you need finer resolution.
 - The date is optional, and the year can be omitted with just ``mm/dd``.
 - The date can also be replaced by a day of the week (either full like ``sunday`` or 3-letters like
   ``sun``, in your local languarge based on the locale; however, on Windows and other platforms that
   lack ``locale.nl_langinfo``, the days of week default to English).
 - The meaning of partial or missing dates depends on the trigger, as explained below.
+- The date and time can be replaced with ``now``, which means the current date and time when the
+  trigger was first evaluated (eg, at startup or when created as an inner function or closure),
+  and remains fixed for the lifetime of the trigger.
 - The time can instead be ``sunrise``, ``sunset``, ``noon`` or ``midnight``.
+- If the time is missing, midnight is assumed (so ``thursday`` is the same as ``thursday 00:00:00``)
+- Seconds are optional, and can include a decimal (fractional) portion if you need finer resolution.
 - The ``datetime`` can be followed by an optional offset
-  of the form ``[+-]number{seconds|minutes|hours|days|weeks}`` and abbreviations ``{s|m|h|d|w}`` or
-  ``{sec|min|hr|day|week}`` can be used. That allows things like ``sunrise + 30m`` to mean 30
-  minutes after sunrise, or ``sunday sunset - 1h`` to mean an hour before sunset on Sundays. The
-  ``number`` can be floating point. (Note, there is no i18n support for those offset abbreviations -
-  they are in English.)
+  of the form ``[+-]number{seconds|minutes|hours|days|weeks}`` with abbreviations:
+
+  - ``{s|sec|second|seconds}`` or empty for seconds,
+  - ``{m|min|mins|minute|minutes}`` for minutes,
+  - ``{h|hr|hour|hours}`` for hours,
+  - ``{d|day|days}`` for days,
+  - ``{w|week|weeks}`` for weeks.
+  That allows things like ``sunrise + 30m`` to mean 30 minutes after sunrise, or ``sunday sunset - 1.5 hour``
+  to mean 1.5 hours before sunset on Sundays. The ``number`` can be floating point. (Note, there is no
+  i18n support for those offset abbreviations - they are in English.)
 
 In ``@time_trigger``, each string specification ``time_spec`` can take one of four forms:
 
-- ``"startup"`` triggers on HASS start and reload (ie, on function definition)
+- ``"startup"`` triggers on HASS start and reload (ie, on function definition), and is
+  equivalent to ``"once(now)"``
 - ``"shutdown"`` triggers on HASS shutdown and reload (ie, when the trigger function is
   no longer referenced)
 - ``"once(datetime)"`` triggers once on the date and time. If the year is
   omitted, it triggers once per year on the date and time (eg, birthday). If the date is just a day
   of week, it triggers once on that day of the week. If the date is omitted, it triggers once each
-  day at the indicated time.
+  day at the indicated time. ``once(now + 5 min)`` means trigger once 5 minutes after startup.
 - ``"period(datetime_start, interval, datetime_end)"`` or
   ``"period(datetime_start, interval)"`` triggers every interval starting at the starting datetime
   and finishing at the optional ending datetime. When there is no ending datetime, the periodic
   trigger runs forever. The interval has the form ``number{sec|min|hours|days|weeks}`` (the same as
-  datetime offset without the leading sign), and single-letter abbreviations can be used.
-- ``"cron(min hr dom mon dow)"`` triggers
-  according to Linux-style crontab. Each of the five entries are separated by spaces and correspond
-  to minutes, hours, day-of-month, month, day-of-week (0 = sunday):
+  datetime offset without the leading sign), and the same abbreviations can be used. Period start
+  and ends can also be based on ``now``, for example ``period(now + 10m, 5min, now + 30min)`` will
+  cause five triggers at 10, 15, 20, 25 and 30 minutes after startup.
+- ``"cron(min hr dom mon dow)"`` triggers according to Linux-style crontab. Each of the five entries
+  are separated by spaces and correspond to minutes, hours, day-of-month, month, day-of-week (0 = sunday):
 
   ============ ==============
   field        allowed values
@@ -583,7 +594,11 @@ In ``@time_trigger``, each string specification ``time_spec`` can take one of fo
   numbers or ranges (no spaces). Ranges are inclusive. For example, if you specify hours as
   ``6,10-13`` that means hours of 6,10,11,12,13. The trigger happens on the next minute, hour, day
   that matches the specification. See any Linux documentation for examples and more details (note:
-  names for days of week and months are not supported; only their integer values are).
+  names for days of week and months are not supported; only their integer values are). The cron
+  features use the ``croniter`` package, so check its `documentation <https://pypi.org/project/croniter/>`
+  for additional specification formats that are supported (eg: ``*/5`` repeats every 5th unit,
+  days of week can be specified with English abbreviations, and an optional 6th field allows seconds
+  to be specified).
 
 When the ``@time_trigger`` occurs and the function is called, the keyword argument ``trigger_type``
 is set to ``"time"``, and ``trigger_time`` is the exact ``datetime`` of the time specification that

tests/test_function.py

@@ -191,7 +191,11 @@ async def test_state_trigger(hass, caplog):
         hass,
         notify_q,
         notify_q2,
-        [dt(2020, 7, 1, 10, 59, 59, 999998), dt(2020, 7, 1, 11, 59, 59, 999998)],
+        [
+            dt(2020, 7, 1, 10, 59, 59, 999998),
+            dt(2020, 7, 1, 10, 59, 59, 999998),
+            dt(2020, 7, 1, 11, 59, 59, 999998),
+        ],
         """
 
 from math import sqrt