update time_trigger kwarg for startup and shutdown triggers per #103

Author: craigbarratt

custom_components/pyscript/trigger.py

@@ -790,7 +790,7 @@ def stop(self):
                 Function.reaper_cancel(self.task)
         if self.run_on_shutdown:
             notify_type = "shutdown"
-            notify_info = {"trigger_type": "shutdown", "trigger_time": None}
+            notify_info = {"trigger_type": "time", "trigger_time": "shutdown"}
             action_future = self.call_action(notify_type, notify_info, run_task=False)
             Function.reaper_await(action_future)
 
@@ -841,7 +841,7 @@ async def trigger_watch(self):
                     # first time only - skip waiting for other triggers
                     #
                     notify_type = "startup"
-                    notify_info = {"trigger_type": "time", "trigger_time": None}
+                    notify_info = {"trigger_type": "time", "trigger_time": "startup"}
                     self.run_on_startup = False
                 elif check_state_expr_on_start:
                     #

docs/new_features.rst

@@ -29,21 +29,32 @@ Planned new features post 1.0.0 include:
 
 The new features since 1.0.0 in master include:
 
+- Adding new decorator ``@mqtt_trigger`` by @dlashua (#98, #105).
 - ``pyscript.reload`` only reloads changed files (changed contents, mtime, or an app's yaml configuration).
   All files in an app or module are reloaded if any one has changed, and any script, app or module that
   imports a changed modules (directly or indirectly) is also reloaded. Setting the optional ``global_ctx``
   service parameter to ``*`` forces reloading all files (which is the behavior in 1.0.0 and earlier).  See #106.
-- Adding new decorator ``@mqtt_trigger`` by @dlashua (#98, #105).
 - 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. Setting this optional parameter makes state triggers edge triggered (ie,
   triggers only on transition from ``False`` to ``True``), instead of the default level trigger
-  (ie, only has to evaluate to ``True``). Proposed by @tchef69 (#89).
+  (ie, only has to evaluate to ``True``). Proposed by @tchef69 (#89), with suggestions from @dlashua (#95).
+- ``@time_trigger`` now supports a ``"shutdown"`` trigger, which occurs on HASS shutdown or whenever
+  the trigger function is no longer referenced (eg: during reload, or redefinition in Jupyter),
+  requested by @dlashua (#103).
 - All .py files below the ``pyscript/scripts`` directory are autoloaded, recursively.  Also, any
   file name or directory starting with ``#`` is skipped (including top-level and ``apps``), which is
   an in-place way of disabling a specific script, app or directory tree (#97).
 - ``del`` and new function ``state.delete()`` can delete state variables and state variable attributes.
 
+Breaking changes since 1.0.0 include:
+
+- The ``pyscript.reload`` service only reloads changed files; prior behavior of reloading all files can be
+  requested by setting the optional ``global_ctx`` service parameter to ``*``.
+- The ``trigger_time`` trigger function argument is now set to ``startup`` for a startup trigger,
+  rather than ``None``. This was done to be consistent with the new ``shutdown`` trigger, which
+  calls the trigger function with `trigger_time="shutdown"``.
+
 Bug fixes since 1.0.0 in master include:
 
 - State setting now copies the attributes, to avoid a strange ``MappingProxyType`` recursion error

docs/reference.rst

@@ -515,7 +515,9 @@ with the following features:
 
 In ``@time_trigger``, each string specification ``time_spec`` can take one of four forms:
 
-- ``"startup"`` triggers on HASS start and reload.
+- ``"startup"`` triggers on HASS start and reload (ie, on function definition)
+- ``"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
@@ -547,8 +549,8 @@ In ``@time_trigger``, each string specification ``time_spec`` can take one of fo
 
 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
-caused the trigger (it will be slightly before the current time), or ``None`` in the case of a
-``startup`` trigger.
+caused the trigger (it will be slightly before the current time), or ``startup`` or ``shutdown``
+in the case of a ``startup`` or ``shutdown`` trigger.
 
 A final special form of ``@time_trigger`` has no arguments, which causes the function to run once
 automatically on startup or reload, which is the same as providing a single ``"startup"`` time
@@ -563,7 +565,16 @@ specification:
 
 The function is not re-started after it returns, unless a reload occurs. Startup occurs when the
 ``EVENT_HOMEASSISTANT_STARTED`` event is fired, which is after everything else is initialized and
-ready, so this function can call any services etc.
+ready, so this function can call any services etc. A startup trigger can also occur after
+HASS is started when a new trigger function is defined (eg, on reload, defined at run-time
+using inner function/closure, or interactively in Jupyter).
+
+Similarly, the ``shutdown`` trigger occurs when the ``EVENT_HOMEASSISTANT_STOP`` event is fired,
+meaning HASS is shutting down. It also occurs whenever a trigger function is no longer referenced
+(meaning it's being deleted), which happens during reload or redefined interactively in Jupyter.
+It's important that any trigger function based on ``shutdown`` runs as quickly as possible,
+since the shutdown of HASS (or reload completion) will be stalled until your function
+completes.
 
 @event_trigger
 ^^^^^^^^^^^^^^

tests/test_function.py

@@ -911,7 +911,7 @@ def func_startup_sync(trigger_type=None, trigger_time=None):
     global seq_num
 
     seq_num += 1
-    pyscript.done = seq_num
+    pyscript.done = [seq_num, trigger_type, trigger_time]
 
 def factory(trig_value):
 
@@ -939,7 +939,7 @@ def func_trig(var_name=None, value=None):
     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
+    assert literal_eval(await wait_until_done(notify_q)) == [seq_num, "time", "startup"]
 
     #
     # trigger them one at a time to make sure each is working

tests/test_reload.py

@@ -55,6 +55,10 @@ def func3():
 other_abc = 987
 
 log.info(f"{__name__} global_ctx={pyscript.get_global_ctx()}")
+
+@time_trigger("shutdown")
+def shutdown(trigger_time=None):
+    log.info(f"{__name__} global_ctx={pyscript.get_global_ctx()} shutdown trigger_time={trigger_time}")
 """,
         f"{conf_dir}/modules/xyz2/__init__.py": """
 from .other import xyz
@@ -193,6 +197,7 @@ def func20():
         conf["apps"]["world2"]["var1"] = 200
         await hass.services.async_call("pyscript", "reload", {}, blocking=True)
         assert "world2 global_ctx=apps.world2.__init__ var1=200, other_abc=987" in caplog.text
+        assert "world2.other global_ctx=apps.world2.other shutdown trigger_time=shutdown" in caplog.text
 
         #
         # change a module inside an app
@@ -203,12 +208,17 @@ def func20():
 other_abc = 654
 
 log.info(f"{__name__} global_ctx={pyscript.get_global_ctx()}")
+
+@time_trigger("shutdown")
+def shutdown(trigger_time=None):
+    log.info(f"{__name__} global_ctx={pyscript.get_global_ctx()} shutdown_new trigger_time={trigger_time}")
 """
         mock_open[f"{conf_dir}/apps/world2/other.py"].read_data = file_contents[
             f"{conf_dir}/apps/world2/other.py"
         ]
         await hass.services.async_call("pyscript", "reload", {}, blocking=True)
         assert "world2 global_ctx=apps.world2.__init__ var1=200, other_abc=654" in caplog.text
+        assert "world2.other global_ctx=apps.world2.other shutdown trigger_time=shutdown" in caplog.text
 
         #
         # now confirm certain files reloaded the correct number of times,
@@ -220,5 +230,15 @@ def func20():
             assert caplog.text.count("hello global_ctx=file.hello xyz=") == 4 + i
             assert caplog.text.count("modules/xyz2/other global_ctx=modules.xyz2.other") == 2 + i
             assert caplog.text.count("modules/xyz2 global_ctx=modules.xyz2.__init__") == 2 + i
+            assert (
+                caplog.text.count("world2.other global_ctx=apps.world2.other shutdown trigger_time=shutdown")
+                == 2
+            )
+            assert (
+                caplog.text.count(
+                    "world2.other global_ctx=apps.world2.other shutdown_new trigger_time=shutdown"
+                )
+                == i
+            )
             if i < 2:
                 await hass.services.async_call("pyscript", "reload", {"global_ctx": "*"}, blocking=True)