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