Fixed wait_until, added documentation

Author: contagon

custom_components/pyscript/trigger.py

@@ -224,6 +224,8 @@ async def wait_until(
         event_trigger=None,
         mqtt_trigger=None,
         webhook_trigger=None,
+        webhook_local_only=True,
+        webhook_methods=None,
         timeout=None,
         state_hold=None,
         state_hold_false=None,
@@ -374,6 +376,10 @@ async def wait_until(
                     if len(state_trig_ident) > 0:
                         State.notify_del(state_trig_ident, notify_q)
                     raise exc
+            if webhook_methods is None:
+                webhook_methods = {"POST", "PUT"}
+            Webhook.notify_add(webhook_trigger[0], webhook_local_only, webhook_methods, notify_q)
+
         time0 = time.monotonic()
 
         if __test_handshake__:

docs/reference.rst

@@ -787,7 +787,7 @@ Wildcards in topics are supported. The ``topic`` variables will be set to the fu
 the message arrived on.
 
 NOTE: The `MQTT Integration in Home Assistant <https://www.home-assistant.io/integrations/mqtt/>`__
-must be set up to use ``@mqtt_trigger``. 
+must be set up to use ``@mqtt_trigger``.
 
 @state_active
 ^^^^^^^^^^^^^
@@ -857,6 +857,45 @@ true if the current time doesn't match any of the "not" (negative) specification
 allows multiple arguments with and without ``not``. The condition will be met if the current time
 matches any of the positive arguments, and none of the negative arguments.
 
+@webhook_trigger
+^^^^^^^^^^^^^^^^
+
+.. code:: python
+
+    @webhook_trigger(webhook_id, str_expr=None, local_only=True, methods={"POST", "PUT", kwargs=None)
+
+``@webhook_trigger`` listens for calls to a `Home Assistant webhook <https://www.home-assistant.io/docs/automation/trigger/#webhook-trigger>`__
+at `your_hass_url/api/webhook/webhook_id` and triggers whenever a request is made at that endpoint.
+Multiple ``@webhook_trigger`` decorators can be applied to a single function if you want
+to trigger off different mqtt topics.
+
+An optional ``str_expr`` can be used to match against payload message data, and the trigger will only occur
+if that expression evaluates to ``True`` or non-zero. This expression has available these four
+variables:
+
+Setting `local_only` option to `False` will allow request made from anywhere on the internet (as opposed to just locally).
+The methods option needs to be an list or set with elements `GET`, `HEAD`, `POST`, or `PUT`.
+
+- ``trigger_type`` is set to "mqtt"
+- ``webhook_id`` is set to the webhook_id that was called.
+- ``webhook_data`` is the data/json that was sent in the request returned as a `MultiDictProxy <https://aiohttp-kxepal-test.readthedocs.io/en/latest/multidict.html#aiohttp.MultiDictProxy>`__ (ie a python dictionary that allows multiple of the same keys).
+
+When the ``@webhook_trigger`` occurs, those same variables are passed as keyword arguments to the
+function in case it needs them. Additional keyword parameters can be specified by setting the
+optional ``kwargs`` argument to a ``dict`` with the keywords and values.
+
+An simple example looks like
+
+.. code:: python
+
+  @webhook_trigger("myid", kwargs={"extra": 10})
+  def webhook_test(webhook_data, extra):
+      log.info(f"It ran! {webhook_data}, {extra}")
+
+which if called using the curl command `curl -X POST -d 'key1=xyz&key2=abc' hass_url/api/webhook/myid
+bhook` outputs `It ran! <MultiDictProxy('key1': 'xyz', 'key2': 'abc')>, 10`
+
+
 Other Function Decorators
 -------------------------
 
@@ -1313,6 +1352,13 @@ It takes the following keyword arguments (all are optional):
 - ``mqtt_trigger=None`` can be set to a string or list of two strings, just like
   ``@mqtt_trigger``. The first string is the MQTT topic, and the second string
   (when the setting is a two-element list) is an expression based on the message variables.
+- ``webhook_trigger=None`` can be set to a string or list of two strings, just like
+  ``@webhook_trigger``. The first string is the webhook id, and the second string
+  (when the setting is a two-element list) is an expression based on the message variables.
+- ``webhook_local_only=True`` is used with ``webhook_trigger`` to specify whether to only allow
+  local webhooks.
+- ``webhook_methods={"POST", "PUT"}`` is used with ``webhook_trigger`` to specify allowed webhook
+  request methods.
 - ``timeout=None`` an overall timeout in seconds, which can be floating point.
 - ``state_check_now=True`` if set, ``task.wait_until()`` checks any ``state_trigger``
   immediately to see if it is already ``True``, and will return immediately if so. If
@@ -1566,7 +1612,7 @@ Pyscript supports importing two types of packages or modules:
   will cause all of the module files to be unloaded, and any scripts or apps that import that module
   will be reloaded. Imports of pyscript modules and packages are not affected by the ``allow_all_imports``
   setting - if a file is in the ``<config>/pyscript/modules`` folder then it can be imported.
-  
+
   Package-style layout is also supported where a PACKAGE is defined in
   ``<config>/pyscript/modules/PACKAGE/__init__.py``, and that file can, in turn,
   do relative imports of other files in that same directory. This form is most convenient for