[discussion] Api on the fly

bin/cylc-checkpoint

@@ -44,7 +44,7 @@ def main():
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port,
         options.comms_timeout)
-    pclient('take_checkpoints', {'items': [name]})
+    pclient('take_checkpoints', {'name': name})
 
 
 if __name__ == "__main__":

bin/cylc-hold

@@ -18,7 +18,7 @@
 
 """cylc [control] hold [OPTIONS] ARGS
 
-Hold one or more waiting tasks (cylc hold REG TASKID ...), or
+Hold one or more waiting tasks (cylc hold REG TASK_GLOB ...), or
 a whole suite (cylc hold REG).
 
 Held tasks do not submit even if they are ready to run.
@@ -44,18 +44,17 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ("REG", "Suite name"),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task matching patterns')])
 
     parser.add_option(
         "--after",
         help="Hold whole suite AFTER this cycle point.",
         metavar="CYCLE_POINT", action="store", dest="hold_point_string")
 
-    options, args = parser.parse_args()
+    options, (suite, *task_globs) = parser.parse_args()
 
-    suite = args.pop(0)
-    if args:
-        prompt('Hold task(s) %s in %s' % (args, suite), options.force)
+    if task_globs:
+        prompt('Hold task(s) %s in %s' % (task_globs, suite), options.force)
     elif options.hold_point_string:
         prompt(
             'Hold suite after %s' % options.hold_point_string, options.force)
@@ -65,11 +64,10 @@ def main():
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port)
 
-    if args:
-        items = parser.parse_multitask_compat(options, args)
+    if task_globs:
         pclient(
             'hold_tasks',
-            {'items': items},
+            {'task_globs': task_globs},
             timeout=options.comms_timeout
         )
     elif options.hold_point_string:

bin/cylc-insert

@@ -65,12 +65,9 @@ def main():
     options, args = parser.parse_args()
     suite = args.pop(0)
 
-    # See "cop.parse_multitask_compat" for back compat discussion
-    # "cop.parse_multitask_compat" cannot be used here because argument 3
-    # (after suite argument) used to be "options.stop_point_string".
-    if (options.multitask_compat and len(args) in [2, 3] and
-            all("/" not in arg for arg in args) and
-            all("." not in arg for arg in args[1:])):
+    if (len(args) in [2, 3]
+            and all("/" not in arg for arg in args)
+            and all("." not in arg for arg in args[1:])):
         items = [(args[0] + "." + args[1])]
         if len(args) == 3:
             options.stop_point_string = args[2]

bin/cylc-kill

@@ -20,7 +20,7 @@
 
 Kill jobs of active tasks and update their statuses accordingly.
 
-To kill one or more tasks, "cylc kill REG TASKID ..."; to kill all active
+To kill one or more tasks, "cylc kill REG TASK_GLOB ..."; to kill all active
 tasks: "cylc kill REG".
 """
 
@@ -43,20 +43,19 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task matching patterns')])
 
-    options, args = parser.parse_args()
+    options, (suite, *task_globs) = parser.parse_args()
 
-    suite = args.pop(0)
-    if args:
-        prompt('Kill task %s in %s' % (args, suite), options.force)
+    if task_globs:
+        prompt('Kill task %s in %s' % (task_globs, suite), options.force)
     else:
         prompt('Kill ALL tasks in %s' % (suite), options.force)
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port)
     pclient(
         'kill_tasks',
-        {'items': parser.parse_multitask_compat(options, args)},
+        {'task_globs': task_globs},
         timeout=options.comms_timeout
     )
 

bin/cylc-make-docs

@@ -38,7 +38,7 @@ echo "Building the HTML Cylc Documentation with Sphinx:"
 echo >&2
 cd "$CYLC_DIR"/doc/
 echo "... Generating the command reference ..."
-./src/custom/make-commands.sh
+#./src/custom/make-commands.sh
 echo >&2
 
 echo "... Generating multi-page User Guide..."

bin/cylc-poll

@@ -20,8 +20,8 @@
 
 Poll (query) task jobs to verify and update their statuses.
 
-Use "cylc poll REG" to poll all active tasks, or "cylc poll REG TASKID" to poll
-individual tasks or families, or groups of them.
+Use "cylc poll REG" to poll all active tasks, or "cylc poll REG TASK_GLOB"
+to poll individual tasks or families, or groups of them.
 """
 
 import sys
@@ -42,29 +42,25 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task matching patterns')])
 
     parser.add_option(
         "-s", "--succeeded", help="Allow polling of succeeded tasks.",
         action="store_true", default=False, dest="poll_succ")
 
-    options, args = parser.parse_args()
+    options, (suite, *task_globs) = parser.parse_args()
 
-    suite = args.pop(0)
-    if args:
-        prompt('Poll task %s in %s' % (args, suite), options.force)
+    if task_globs:
+        prompt('Poll task %s in %s' % (task_globs, suite), options.force)
     else:
         prompt('Poll ALL tasks in %s' % (suite), options.force)
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port,
         options.comms_timeout)
-    items = parser.parse_multitask_compat(options, args)
-    # Back compat: back_out introduced >7.5.0
-    # So don't call with "poll_succ" if not necessary to avoid breakage.
-    if options.poll_succ:
-        pclient('poll_tasks', {'items': items, 'poll_succ': options.poll_succ})
-    else:
-        pclient('poll_tasks', {'items': items})
+    pclient(
+        'poll_tasks',
+        {'task_globs': task_globs, 'poll_succ': options.poll_succ}
+    )
 
 
 if __name__ == "__main__":

bin/cylc-release

@@ -18,7 +18,7 @@
 
 """cylc [control] release|unhold [OPTIONS] ARGS
 
-Release one or more held tasks (cylc release REG TASKID)
+Release one or more held tasks (cylc release REG TASK_GLOB)
 or the whole suite (cylc release REG). Held tasks do not
 submit even if they are ready to run.
 
@@ -43,21 +43,22 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ("REG", 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task matching patterns')])
 
-    options, args = parser.parse_args()
-    suite = args.pop(0)
+    options, (suite, *task_globs) = parser.parse_args()
 
-    if args:
-        prompt('Release task(s) %s in %s' % (args, suite), options.force)
+    if task_globs:
+        prompt('Release task(s) %s in %s' % (task_globs, suite), options.force)
     else:
         prompt('Release suite %s' % suite, options.force)
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port,
         options.comms_timeout)
-    if args:
-        items = parser.parse_multitask_compat(options, args)
-        pclient('release_tasks', {'items': items})
+    if task_globs:
+        pclient(
+            'release_tasks',
+            {'task_globs': task_globs}
+        )
     else:
         pclient('release_suite')
 

bin/cylc-remove

@@ -18,7 +18,7 @@
 
 """cylc [control] remove [OPTIONS] ARGS
 
-Remove one or more tasks (cylc remove REG TASKID), or all tasks with a
+Remove one or more tasks (cylc remove REG TASK_GLOB), or all tasks with a
 given cycle point (cylc remove REG *.POINT) from a running suite.
 
 Tasks will spawn successors first if they have not done so already.
@@ -42,24 +42,22 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ("REG", "Suite name"),
-            ('TASKID [...]', 'Task identifiers')])
+            ('TASK_GLOB [...]', 'Task matching patterns')])
 
     parser.add_option(
         "--no-spawn",
         help="Do not spawn successors before removal.",
         action="store_true", default=False, dest="no_spawn")
 
-    options, args = parser.parse_args()
+    options, (suite, *task_globs) = parser.parse_args()
 
-    suite = args.pop(0)
-    prompt('remove task(s) %s in %s' % (args, suite), options.force)
+    prompt('remove task(s) %s in %s' % (task_globs, suite), options.force)
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port,
         options.comms_timeout)
-    items = parser.parse_multitask_compat(options, args)
     pclient(
         'remove_tasks',
-        {'items': items, 'spawn': (not options.no_spawn)}
+        {'task_globs': task_globs, 'spawn': (not options.no_spawn)}
     )
 
 

bin/cylc-reset

@@ -52,7 +52,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task matching patterns')])
 
     parser.add_option(
         "-s", "--state", metavar="STATE",
@@ -70,9 +70,7 @@ def main():
               "Can be used more than once to reset multiple task outputs."),
         action="append", default=[], dest="outputs")
 
-    options, args = parser.parse_args()
-
-    suite = args.pop(0)
+    options, (suite, *task_globs) = parser.parse_args()
 
     if not options.state and not options.outputs:
         parser.error("Neither --state=STATE nor --output=OUTPUT is set")
@@ -83,7 +81,7 @@ def main():
             "'cylc reset -s spawn' is deprecated; calling 'cylc spawn'\n")
         cmd = sys.argv[0].replace('reset', 'spawn')
         try:
-            os.execvp(cmd, [cmd] + args)
+            os.execvp(cmd, [cmd] + task_globs)
         except OSError as exc:
             if exc.filename is None:
                 exc.filename = cmd
@@ -92,14 +90,14 @@ def main():
     if not options.state:
         options.state = ''
 
-    prompt('Reset task(s) %s in %s' % (args, suite), options.force)
+    prompt('Reset task(s) %s in %s' % (task_globs, suite), options.force)
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port,
         options.comms_timeout)
-    items = parser.parse_multitask_compat(options, args)
     pclient(
         'reset_task_states',
-        {'items': items, 'state': options.state, 'outputs': options.outputs}
+        {'task_globs': task_globs, 'state': options.state,
+         'outputs': options.outputs}
     )
 
 

bin/cylc-show

@@ -43,17 +43,16 @@ def main():
         __doc__, comms=True, noforce=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task names or identifiers')])
+            ('[TASKS ...]', 'Task names or ids (name.cycle)')])
 
     parser.add_option('--list-prereqs', action="store_true", default=False,
                       help="Print a task's pre-requisites as a list.")
 
     parser.add_option('--json', action="store_true", default=False,
                       help="Print output in JSON format.")
 
-    options, args = parser.parse_args()
-    suite = args[0]
-    task_args = args[1:]
+    options, (suite, *task_args) = parser.parse_args()
+
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port,
         options.comms_timeout)
@@ -83,8 +82,10 @@ def main():
                     print("%s: %s" % (key, value or "(not given)"))
 
     if task_ids:
-        results, bad_items = pclient('get_task_requisites', {
-            'items': task_ids, 'list_prereqs': options.list_prereqs})
+        results, bad_items = pclient(
+            'get_task_requisites',
+            {'task_globs': task_ids, 'list_prereqs': options.list_prereqs}
+        )
         if options.json:
             json_filter.append(results)
         else:

bin/cylc-spawn

@@ -41,20 +41,18 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task matching patterns')])
 
-    options, args = parser.parse_args()
+    options, (suite, *task_globs) = parser.parse_args()
 
-    suite = args.pop(0)
-
-    prompt('Spawn task(s) %s in %s' % (args, suite), options.force)
+    prompt('Spawn task(s) %s in %s' % (task_globs, suite), options.force)
     pclient = SuiteRuntimeClient(
         suite, options.owner, options.host, options.port,
         options.comms_timeout)
 
     pclient(
         'spawn_tasks',
-        {'items': parser.parse_multitask_compat(options, args)}
+        {'task_globs': task_globs}
     )