~_W'FLOW_NAME ⇒ ~_W'FLOW_ID and ~_W'FLOW_NAME re-instated as Cy…

…lc7 consistent (#4455)

* write test for new WORKFLOW_ID=foo/run1 and WORKFLOW_NAME=foo

* Renamed CYLC_WORKFLOW_NAME ⇒ CYLC_WORKFLOW_ID
Made CYLC_WORKFLOW_ID = CYLC_WORKFLOW_NAME - trailing "runX"

* allow test_header init_workflow to set whether to use --no-run-name

* fixed test for CYLC_WORKFLOW_ID

* CHANGES.md added

* Apply suggestions from code review

Co-authored-by: Ronnie Dutta <[email protected]>

* remove unwanted files; add documentation for change to init_workflow

* finished rename of runN_remover

* added docstring as per @MetRonnie suggestion

* remove accidental PR pollution

* replaced refs in script docstrings to REG to WORKFLOW/ID/NAME

* Apply suggestions from code review

Co-authored-by: Ronnie Dutta <[email protected]>

* Fixed some review comments; fixed cylc play docstring!

* fix test reliant on REG

Co-authored-by: Ronnie Dutta <[email protected]>

CHANGES.md

@@ -100,6 +100,10 @@ workflow directory are recorded by `log/version`.
 [#4404](https://github.com/cylc/cylc-flow/pull/4404) - The Cylc Graph section
 now accepts ``&`` and ``|`` as valid line breaks in the same way as ``=>``.
 
+[#4455](https://github.com/cylc/cylc-flow/pull/4455) - `CYLC_WORKFLOW_NAME`
+renamed to `CYLC_WORKFLOW_ID`. `CYLC_WORKFLOW_NAME` re-added as
+`CYLC_WORKFLOW_ID` shorn of any trailing `runX`.
+
 
 ### Fixes
 

cylc/flow/config.py

@@ -75,6 +75,7 @@
     get_workflow_run_log_dir,
     get_workflow_run_share_dir,
     get_workflow_run_work_dir,
+    get_workflow_name_from_id
 )
 from cylc.flow.platforms import FORBIDDEN_WITH_PLATFORM
 from cylc.flow.print_tree import print_tree
@@ -182,7 +183,8 @@ def __init__(
         if self.mem_log is None:
             self.mem_log = lambda x: None
         self.mem_log("config.py:config.py: start init config")
-        self.workflow = workflow  # workflow name
+        self.workflow = workflow  # workflow id
+        self.workflow_name = get_workflow_name_from_id(self.workflow)
         self.fpath = str(fpath)  # workflow definition
         self.fdir = os.path.dirname(fpath)
         self.run_dir = run_dir or get_workflow_run_dir(self.workflow)
@@ -1366,7 +1368,8 @@ def process_workflow_env(self):
         """Workflow context is exported to the local environment."""
         for key, value in {
             **verbosity_to_env(cylc.flow.flags.verbosity),
-            'CYLC_WORKFLOW_NAME': self.workflow,
+            'CYLC_WORKFLOW_ID': self.workflow,
+            'CYLC_WORKFLOW_NAME': self.workflow_name,
             'CYLC_WORKFLOW_RUN_DIR': self.run_dir,
             'CYLC_WORKFLOW_LOG_DIR': self.log_dir,
             'CYLC_WORKFLOW_WORK_DIR': self.work_dir,

cylc/flow/option_parsers.py

@@ -177,9 +177,9 @@ def __init__(
         self.auto_add = auto_add
         if argdoc is None:
             if prep:
-                argdoc = [('WORKFLOW', 'Workflow name or path')]
+                argdoc = [('WORKFLOW | PATH', 'Workflow name or path')]
             else:
-                argdoc = [('REG', 'Workflow name')]
+                argdoc = [('WORKFLOW', 'Workflow name')]
 
         if '--color=never' not in '='.join(sys.argv[2:]):
             # Before option parsing, for `--help`, make comments grey in usage.

cylc/flow/pathutil.py

@@ -409,3 +409,15 @@ def is_relative_to(path1: Union[Path, str], path2: Union[Path, str]) -> bool:
     except ValueError:
         return False
     return True
+
+
+def get_workflow_name_from_id(workflow_id: str) -> str:
+    """Workflow name is the ID shorn of the runN directory name.
+
+    Examples:
+    >>> get_workflow_name_from_id('my_workflow/run42')
+    'my_workflow'
+    >>> get_workflow_name_from_id('my_other_workflow')
+    'my_other_workflow'
+    """
+    return re.sub(rf'{re.escape(os.sep)}run\d+$', '', workflow_id)

cylc/flow/scheduler.py

@@ -77,7 +77,8 @@
     get_workflow_run_share_dir,
     get_workflow_run_work_dir,
     get_workflow_test_log_name,
-    make_workflow_run_tree
+    make_workflow_run_tree,
+    get_workflow_name_from_id
 )
 from cylc.flow.platforms import (
     get_install_target_from_platform,
@@ -246,6 +247,7 @@ class Scheduler:
     def __init__(self, reg: str, options: Values) -> None:
         # flow information
         self.workflow = reg
+        self.workflow_name = get_workflow_name_from_id(self.workflow)
         self.owner = get_user()
         self.host = get_host()
         self.id = f'{self.owner}{ID_DELIM}{self.workflow}'
@@ -1109,7 +1111,8 @@ def load_flow_file(self, is_reload=False):
         self.task_job_mgr.job_file_writer.set_workflow_env({
             **verbosity_to_env(cylc.flow.flags.verbosity),
             'CYLC_UTC': str(get_utc_mode()),
-            'CYLC_WORKFLOW_NAME': self.workflow,
+            'CYLC_WORKFLOW_ID': self.workflow,
+            'CYLC_WORKFLOW_NAME': self.workflow_name,
             'CYLC_CYCLING_MODE': str(
                 self.config.cfg['scheduling']['cycling mode']
             ),

cylc/flow/scheduler_cli.py

@@ -71,16 +71,18 @@
 as satisfied.
 
 Examples:
-    # Start (at the initial cycle point), or restart, or resume workflow REG
-    $ cylc play REG
+    # Start (at the initial cycle point), restart, or resume workflow WORKFLOW
+    $ cylc play WORKFLOW
 
     # Start a new run from a cycle point after the initial cycle point
-    $ cylc play --start-cycle-point=3 REG  # (integer cycling)
-    $ cylc play --start-cycle-point=20250101T0000Z REG  # (datetime cycling)
+    # (integer cycling)
+    $ cylc play --start-cycle-point=3 WORKFLOW
+    # (datetime cycling):
+    $ cylc play --start-cycle-point=20250101T0000Z WORKFLOW
 
     # Start a new run from specified tasks in the graph
-    $ cylc play --start-task=foo.3 REG
-    $ cylc play -t foo.3 -t bar.3 REG
+    $ cylc play --start-task=foo.3 WORKFLOW
+    $ cylc play -t foo.3 -t bar.3 WORKFLOW
 
     # Start, restart or resume the second installed run of the workflow
     # "dogs/fido"
@@ -91,7 +93,7 @@
 """
 
 
-FLOW_NAME_ARG_DOC = ("REG", "Workflow name")
+FLOW_NAME_ARG_DOC = ("WORKFLOW", "Workflow name or ID")
 
 RESUME_MUTATION = '''
 mutation (

cylc/flow/scripts/broadcast.py

@@ -48,20 +48,20 @@
 
 Examples:
   # To broadcast a variable to all tasks (quote items with internal spaces):
-  $ cylc broadcast -s "[environment]VERSE = the quick brown fox" REG
+  $ cylc broadcast -s "[environment]VERSE = the quick brown fox" WORKFLOW
 
   # To do the same with a file:
   $ cat >'broadcast.cylc' <<'__FLOW__'
   $ [environment]
   $     VERSE = the quick brown fox
   $ __FLOW__
-  $ cylc broadcast -F 'broadcast.cylc' REG
+  $ cylc broadcast -F 'broadcast.cylc' WORKFLOW
 
   # To cancel the same broadcast:
-  $ cylc broadcast --cancel "[environment]VERSE" REG
+  $ cylc broadcast --cancel "[environment]VERSE" WORKFLOW
 
   # If -F FILE was used, the same file can be used to cancel the broadcast:
-  $ cylc broadcast -G 'broadcast.cylc' REG
+  $ cylc broadcast -G 'broadcast.cylc' WORKFLOW
 
 Use -d/--display to see active broadcasts. Multiple --cancel options or
 multiple --set and --set-file options can be used on the same command line.
@@ -224,7 +224,7 @@ def get_option_parser():
     """CLI for "cylc broadcast"."""
     parser = COP(
         __doc__, comms=True,
-        argdoc=[('REG', "Workflow name")]
+        argdoc=[('WORKFLOW', 'Workflow name or ID')]
     )
 
     parser.add_option(

cylc/flow/scripts/cat_log.py

@@ -225,7 +225,7 @@ def get_option_parser():
     parser = COP(
         __doc__,
         argdoc=[
-            ("REG", "Workflow name"),
+            ("WORKFLOW", "Workflow name or ID"),
             ("[TASK-ID]", """Task ID""")
         ]
     )

cylc/flow/scripts/clean.py

@@ -71,7 +71,7 @@
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[('REG', "Workflow name")],
+        argdoc=[('WORKFLOW', 'Workflow name or ID')],
         segregated_log=True
     )
 

cylc/flow/scripts/client.py

@@ -44,7 +44,7 @@
 
 def get_option_parser():
     parser = COP(__doc__, comms=True, argdoc=[
-        ('REG', 'Workflow name'),
+        ('WORKFLOW', 'Workflow name or ID'),
         ('METHOD', 'Network API function name')])
 
     parser.add_option(

cylc/flow/scripts/config.py

@@ -20,8 +20,9 @@
 
 Parse and print Cylc configuration files.
 
-Print parsed configuration, after runtime inheritance. If REG is specified,
-print the workflow configuration, otherwise print the global configuration.
+Print parsed configuration, after runtime inheritance. If WORKFLOW is
+specified, print the workflow configuration, otherwise print the global
+configuration.
 
 Note:
   This is different to `cylc view` which doesn't parse the configuration,
@@ -66,7 +67,7 @@
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[("[REG]", "Workflow name or path")],
+        argdoc=[("[WORKFLOW]", "Workflow name, ID, or path")],
         jset=True, icp=True
     )
 

cylc/flow/scripts/ext_trigger.py

@@ -75,7 +75,7 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True,
-        argdoc=[("REG", "Workflow name"),
+        argdoc=[("WORKFLOW", "Workflow name or ID"),
                 ("MSG", "External trigger message"),
                 ("ID", "Unique trigger ID")])
 

cylc/flow/scripts/get_workflow_contact.py

@@ -32,7 +32,7 @@
 
 
 def get_option_parser():
-    return COP(__doc__, argdoc=[('REG', 'Workflow name')])
+    return COP(__doc__, argdoc=[('WORKFLOW', 'Workflow name or ID')])
 
 
 @cli_function(get_option_parser)

cylc/flow/scripts/hold.py

@@ -97,7 +97,7 @@ def get_option_parser() -> COP:
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', "Workflow name"),
+            ('WORKFLOW', 'Workflow name or ID'),
             # TODO: switch back to TASK_ID?
             ('[TASK_GLOB ...]', "Task matching patterns")]
     )

cylc/flow/scripts/install.py

@@ -22,18 +22,18 @@
 
 The workflow can then be started, stopped, and targeted by name.
 
-Normal installation creates a directory "~/cylc-run/REG/", with a run
-directory "~/cylc-run/REG/run1". A "_cylc-install/source" symlink to the source
-directory will be created in the REG directory.
+Normal installation creates a directory "~/cylc-run/WORKFLOW_NAME/", with a run
+directory "~/cylc-run/WORKFLOW_NAME/run1". A "_cylc-install/source" symlink to
+the source directory will be created in the WORKFLOW_NAME directory.
 Any files or directories (excluding .git, .svn) from the source directory are
 copied to the new run directory.
 A ".service" directory will also be created and used for server authentication
 files at run time.
 
-If the argument REG is used, Cylc will search for the workflow in the list of
-directories given by "global.cylc[install]source dirs", and install the first
-match. Otherwise, the workflow in the current working directory, or the one
-specified by the "--directory" option, will be installed.
+If the argument WORKFLOW_NAME is used, Cylc will search for the workflow in the
+list of directories given by "global.cylc[install]source dirs", and install the
+first match. Otherwise, the workflow in the current working directory, or the
+one specified by the "--directory" option, will be installed.
 
 Workflow names can be hierarchical, corresponding to the path under ~/cylc-run.
 
@@ -86,7 +86,7 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True, prep=True,
-        argdoc=[("[REG]", "Workflow name")]
+        argdoc=[('[WORKFLOW_NAME]', 'Workflow name')]
     )
 
     parser.add_option(
@@ -153,7 +153,8 @@ def install(
         source = opts.source
     else:
         if opts.source:
-            parser.error("REG and --directory are mutually exclusive.")
+            parser.error(
+                "WORKFLOW_NAME and --directory are mutually exclusive.")
         source = search_install_source_dirs(reg)
     flow_name = opts.flow_name or reg
 

cylc/flow/scripts/kill.py

@@ -21,8 +21,8 @@
 Kill running or submitted jobs.
 
 Examples:
-  $ cylc kill REG  # kill all active tasks in the workflow
-  $ cylc kill REG TASK_GLOB ...  # kill one or more active tasks
+  $ cylc kill WORKFLOW  # kill all active tasks in the workflow
+  $ cylc kill WORKFLOW TASK_GLOB ...  # kill one or more active tasks
 """
 
 from typing import TYPE_CHECKING
@@ -55,7 +55,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', 'Workflow name'),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_GLOB ...]', 'Task matching patterns')])
 
     return parser

cylc/flow/scripts/message.py

@@ -90,7 +90,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True,
         argdoc=[
-            ('[REG]', 'Workflow name'),
+            ('[WORKFLOW]', 'Workflow name or ID'),
             ('[TASK-JOB]', 'Task job identifier CYCLE/TASK_NAME/SUBMIT_NUM'),
             ('[[SEVERITY:]MESSAGE ...]', 'Messages')])
     parser.add_option(

cylc/flow/scripts/pause.py

@@ -57,7 +57,7 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
-        argdoc=[('REG', "Workflow name")]
+        argdoc=[('WORKFLOW', 'Workflow name or ID')]
     )
     return parser
 

cylc/flow/scripts/ping.py

@@ -20,7 +20,7 @@
 
 Test communication with a running workflow.
 
-If workflow REG is running or TASK in workflow REG is currently running,
+If workflow WORKFLOW is running or TASK in WORKFLOW is currently running,
 exit with success status, else exit with error status."""
 
 from ansimarkup import parse as cparse
@@ -65,7 +65,11 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True,
-        argdoc=[('REG', 'Workflow name'), ('[TASK]', 'Task ' + TaskID.SYNTAX)])
+        argdoc=[
+            ('WORKFLOW', 'Workflow name or ID'),
+            ('[TASK]', 'Task ' + TaskID.SYNTAX)
+        ]
+    )
 
     return parser
 

cylc/flow/scripts/poll.py

@@ -21,8 +21,8 @@
 Poll (query) task jobs to verify and update their statuses.
 
 Examples:
-  $ cylc poll REG  # poll all active tasks
-  $ cylc poll REG TASK_GLOB  # poll multiple active tasks or families
+  $ cylc poll WORKFLOW  # poll all active tasks
+  $ cylc poll WORKFLOW TASK_GLOB  # poll multiple active tasks or families
 """
 
 from typing import TYPE_CHECKING
@@ -55,7 +55,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', 'Workflow name'),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_GLOB ...]', 'Task matching patterns')]
     )
     return parser

cylc/flow/scripts/reinstall.py

@@ -58,7 +58,7 @@
 
 def get_option_parser():
     parser = COP(
-        __doc__, comms=True, argdoc=[('[REG]', 'Workflow name')]
+        __doc__, comms=True, argdoc=[('[WORKFLOW]', 'Workflow name or ID')]
     )
 
     parser.add_cylc_rose_options()

cylc/flow/scripts/release.py

@@ -84,7 +84,7 @@ def get_option_parser() -> COP:
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', "Workflow name"),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_GLOB ...]', "Task matching patterns")]
     )
 

cylc/flow/scripts/reload.py

@@ -26,8 +26,8 @@
 a task is already running at reload time.
 
 If the workflow was started with Jinja2 template variables set on the command
-line (cylc play --set 'FOO="bar"' REG) the same template settings apply to the
-reload (only changes to the flow.cylc file itself are reloaded).
+line (cylc play --set 'FOO="bar"' WORKFLOW) the same template settings apply to
+the reload (only changes to the flow.cylc file itself are reloaded).
 
 If the modified workflow definition does not parse, failure to reload will
 be reported but no harm will be done to the running workflow."""