diff --git a/cylc/flow/xtriggers/echo.py b/cylc/flow/xtriggers/echo.py
index 1bc96db6955..686b4f59112 100644
--- a/cylc/flow/xtriggers/echo.py
+++ b/cylc/flow/xtriggers/echo.py
@@ -14,15 +14,17 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
-"""An xtrigger function that prints its arguments and never succeeds.
-This may be a useful aid to understanding how xtriggers work. Try returning
-True (success) and some results dict to pass on to dependent tasks.
+def echo(*args, **kwargs):
+ """An xtrigger function that prints its arguments and never succeeds.
-"""
+ This may be a useful aid to understanding how xtriggers work. Try returning
+ True (success) and some results dict to pass on to dependent tasks.
+ Returns
+ tuple: (False, {})
-def echo(*args, **kwargs):
+ """
print("echo: ARGS:", args)
print("echo: KWARGS:", kwargs)
- return (False, {})
+ return False, {}
diff --git a/cylc/flow/xtriggers/suite_state.py b/cylc/flow/xtriggers/suite_state.py
index 210e8a7976b..a0cc380400b 100644
--- a/cylc/flow/xtriggers/suite_state.py
+++ b/cylc/flow/xtriggers/suite_state.py
@@ -14,14 +14,11 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
-"""xtrigger function to check a remote suite state.
-
-"""
-
import os
import sqlite3
-from cylc.flow.cycling.util import add_offset
+
from cylc.flow.cfgspec.glbl_cfg import glbl_cfg
+from cylc.flow.cycling.util import add_offset
from cylc.flow.dbstatecheck import CylcSuiteDBChecker
from metomi.isodatetime.parsers import TimePointParser
@@ -30,8 +27,46 @@ def suite_state(suite, task, point, offset=None, status='succeeded',
message=None, cylc_run_dir=None, debug=False):
"""Connect to a suite DB and query the requested task state.
- Reports satisfied only if the remote suite state has been achieved.
- Returns all suite state args to pass on to triggering tasks.
+ * Reports satisfied only if the remote suite state has been achieved.
+ * Returns all suite state args to pass on to triggering tasks.
+
+ Arguments:
+ suite (str):
+ The suite to interrogate.
+ task (str):
+ The name of the task to query.
+ offset (str):
+ The offset between the cycle this xtrigger is used in and the one
+ it is querying for as an ISO8601 time duration.
+ e.g. PT1H (one hour).
+ status (str):
+ The task status required for this xtrigger to be satisfied.
+ message (str):
+ The custom task output required for this xtrigger to be satisfied.
+ .. note::
+
+ This cannot be specified in conjunction with ``status``.
+
+ cylc_run_dir (str):
+ The directory in which the suite to interrogate.
+
+ .. note::
+
+ This only needs to be supplied if the suite is running in a
+ different location to what is specified in the global
+ configuration (usually ``~/cylc-run``).
+
+ debug (bool):
+ Flag to enable debug information.
+
+ Returns:
+ tuple: (satisfied, results)
+
+ satisfied (bool):
+ True if ``satisfied`` else ``False``.
+ results (dict):
+ Dictionary containing the args / kwargs which were provided
+ to this xtrigger (except ``debug``).
"""
cylc_run_dir = os.path.expandvars(
@@ -61,4 +96,4 @@ def suite_state(suite, task, point, offset=None, status='succeeded',
'message': message,
'cylc_run_dir': cylc_run_dir
}
- return (satisfied, results)
+ return satisfied, results
diff --git a/cylc/flow/xtriggers/xrandom.py b/cylc/flow/xtriggers/xrandom.py
index bcb46e56880..43420dc0ba4 100644
--- a/cylc/flow/xtriggers/xrandom.py
+++ b/cylc/flow/xtriggers/xrandom.py
@@ -14,12 +14,6 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
-"""xtrigger with a configurable random chance of success.
-
-Used for testing xtriggers.
-
-"""
-
from random import random, randint
from time import sleep
@@ -31,46 +25,62 @@
def xrandom(percent, secs=0, _=None, debug=False):
"""Random xtrigger, with configurable sleep and percent success.
- Sleep for seconds, and report satisfied with ~ likelihood.
- If satisfied, return a random color and size as the result.
- The '_' argument is not used in the function code, but can be used to
+ Sleep for ``sec`` seconds, and report satisfied with ~``percent``
+ likelihood.
+
+ The ``_`` argument is not used in the function code, but can be used to
specialize the function signature to cycle point or task.
- If the percent is zero, it returns that the trigger condition was
- not satisfied, and an empty dictionary.
- >>> xrandom(0, 0)
- (False, {})
+ Args:
+ percent (float):
+ Percent likelihood of passing.
+ secs (int):
+ Seconds to sleep before starting the trigger.
+ _ (object):
+ Used to allow users to specialize the trigger with extra
+ parameters.
+ debug (bool):
+ Flag to enable debug information.
+
+ Examples:
+ If the percent is zero, it returns that the trigger condition was
+ not satisfied, and an empty dictionary.
+ >>> xrandom(0, 0)
+ (False, {})
- If the percent is not zero, but the random percent success is not met,
- then it also returns that the trigger condition was not satisfied,
- and an empty dictionary.
- >>> import sys
- >>> mocked_random = lambda: 0.3
- >>> sys.modules[__name__].random = mocked_random
- >>> xrandom(15.5, 0)
- (False, {})
+ If the percent is not zero, but the random percent success is not met,
+ then it also returns that the trigger condition was not satisfied,
+ and an empty dictionary.
+ >>> import sys
+ >>> mocked_random = lambda: 0.3
+ >>> sys.modules[__name__].random = mocked_random
+ >>> xrandom(15.5, 0)
+ (False, {})
- Finally, if the percent is not zero, and the random percent success is
- met, then it returns that the trigger condition was satisfied, and a
- dictionary containing random color and size as result.
- >>> import sys
- >>> mocked_random = lambda: 0.9
- >>> sys.modules[__name__].random = mocked_random
- >>> mocked_randint = lambda x, y: 1
- >>> sys.modules[__name__].randint = mocked_randint
- >>> xrandom(99.99, 0)
- (True, {'COLOR': 'orange', 'SIZE': 'small'})
+ Finally, if the percent is not zero, and the random percent success is
+ met, then it returns that the trigger condition was satisfied, and a
+ dictionary containing random color and size as result.
+ >>> import sys
+ >>> mocked_random = lambda: 0.9
+ >>> sys.modules[__name__].random = mocked_random
+ >>> mocked_randint = lambda x, y: 1
+ >>> sys.modules[__name__].randint = mocked_randint
+ >>> xrandom(99.99, 0)
+ (True, {'COLOR': 'orange', 'SIZE': 'small'})
- Args:
- percent (float): percent likelihood.
- secs (int): seconds to sleep before starting the trigger.
- _ (object): used to allow users to specialize the trigger
- with extra parameters.
- debug (bool): flag to enable debug information.
Returns:
- A tuple with the trigger flag (bool) which is set to True if the
- trigger was evaluated successful, False otherwise, and a random
- color and size (dict).
+ tuple: (satisfied, results)
+
+ satisfied (bool):
+ True if ``satisfied`` else ``False``.
+ results (dict):
+ A dictionary containing the following keys:
+
+ ``COLOR``
+ A random color (e.g. red, orange, ...)
+ ``SIZE``
+ A random size (e.g. small, medium, ...) as the result.
+
"""
sleep(float(secs))
results = {}
@@ -80,4 +90,4 @@ def xrandom(percent, secs=0, _=None, debug=False):
'COLOR': COLORS[randint(0, len(COLORS) - 1)], # nosec
'SIZE': SIZES[randint(0, len(SIZES) - 1)] # nosec
}
- return (satisfied, results)
+ return satisfied, results