Type annotations & homogenise "[OPTIONS] ARGS" in script docstrings

cylc/flow/config.py

@@ -180,15 +180,15 @@ def __init__(
             'SequenceBase', Set[Tuple[str, str, bool, bool]]
         ] = {}
         self.taskdefs: Dict[str, TaskDef] = {}
-        self.initial_point: Optional['PointBase'] = None
-        self.start_point: Optional['PointBase'] = None
-        self.final_point: Optional['PointBase'] = None
         self.clock_offsets = {}
         self.expiration_offsets = {}
         self.ext_triggers = {}  # Old external triggers (client/server)
         self.xtrigger_mgr = xtrigger_mgr
         self.workflow_polling_tasks = {}  # type: ignore # TODO figure out type
 
+        self.initial_point: 'PointBase'
+        self.start_point: 'PointBase'
+        self.final_point: Optional['PointBase'] = None
         self.sequences: List['SequenceBase'] = []
         self.actual_first_point: Optional['PointBase'] = None
         self._start_point_for_actual_first_point: Optional['PointBase'] = None
@@ -591,7 +591,7 @@ def process_cycle_point_tz(self):
                 )
         self.cfg['scheduler']['cycle point time zone'] = orig_cp_tz
 
-    def process_initial_cycle_point(self):
+    def process_initial_cycle_point(self) -> None:
         """Validate and set initial cycle point from flow.cylc or options.
 
         Sets:
@@ -639,7 +639,7 @@ def process_initial_cycle_point(self):
                     f"Initial cycle point {self.initial_point} does not meet "
                     f"the constraints {constraints}")
 
-    def process_start_cycle_point(self):
+    def process_start_cycle_point(self) -> None:
         """Set the start cycle point from options.
 
         Sets:
@@ -655,7 +655,7 @@ def process_start_cycle_point(self):
             # Cold start.
             self.start_point = self.initial_point
 
-    def process_final_cycle_point(self):
+    def process_final_cycle_point(self) -> None:
         """Validate and set the final cycle point from flow.cylc or options.
 
         Sets:

cylc/flow/platforms.py

@@ -20,13 +20,15 @@
 import re
 from copy import deepcopy
 from typing import (
-    Any, Dict, Iterable, List, Optional, Tuple, Union)
+    Any, Dict, Iterable, List, Optional, Tuple, Union, overload)
 
 from cylc.flow.exceptions import PlatformLookupError
 from cylc.flow.cfgspec.glbl_cfg import glbl_cfg
 from cylc.flow.hostuserutil import is_remote_host
 
 
+UNKNOWN_TASK = 'unknown task'
+
 FORBIDDEN_WITH_PLATFORM: Tuple[Tuple[str, str, List[Optional[str]]], ...] = (
     ('remote', 'host', ['localhost', None]),
     ('job', 'batch system', [None]),
@@ -38,6 +40,20 @@
 PLATFORM_REC_COMMAND = re.compile(r'(\$\()\s*(.*)\s*([)])$')
 
 
+@overload
+def get_platform(
+    task_conf: Union[str, None] = None, task_id: str = UNKNOWN_TASK
+) -> Dict[str, Any]:
+    ...
+
+
+@overload
+def get_platform(
+    task_conf: Dict[str, Any], task_id: str = UNKNOWN_TASK
+) -> Optional[Dict[str, Any]]:
+    ...
+
+
 # BACK COMPAT: get_platform
 #     At Cylc 9 remove all Cylc7 upgrade logic.
 # from:
@@ -48,7 +64,7 @@
 #     Cylc9
 def get_platform(
     task_conf: Union[str, Dict[str, Any], None] = None,
-    task_id: str = 'unknown task'
+    task_id: str = UNKNOWN_TASK
 ) -> Optional[Dict[str, Any]]:
     """Get a platform.
 
@@ -432,7 +448,7 @@ def fail_if_platform_and_host_conflict(task_conf, task_name):
 
 
 def get_platform_deprecated_settings(
-    task_conf: Dict[str, Any], task_name: str = 'unknown task'
+    task_conf: Dict[str, Any], task_name: str = UNKNOWN_TASK
 ) -> List[str]:
     """Return deprecated [runtime][<task_name>] settings that should be
     upgraded to platforms.
@@ -548,5 +564,5 @@ def get_random_platform_for_install_target(
 
 def get_localhost_install_target() -> str:
     """Returns the install target of localhost platform"""
-    localhost = platform_from_name()
+    localhost = get_platform()
     return get_install_target_from_platform(localhost)

cylc/flow/scheduler_cli.py

@@ -15,12 +15,12 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """Common logic for "cylc play" CLI."""
 
+from ansimarkup import parse as cparse
 import asyncio
 from contextlib import suppress
 from functools import lru_cache
 import sys
-
-from ansimarkup import parse as cparse
+from typing import TYPE_CHECKING
 
 from cylc.flow import LOG, RSYNC_LOG
 from cylc.flow.exceptions import ServiceFileError
@@ -42,6 +42,10 @@
 from cylc.flow import workflow_files
 from cylc.flow.terminal import cli_function
 
+if TYPE_CHECKING:
+    from optparse import Values
+
+
 PLAY_DOC = r"""cylc play [OPTIONS] ARGS
 
 Start a new workflow, restart a stopped workflow, or resume a paused workflow.
@@ -60,7 +64,7 @@
 cycle point is considered to be satisfied.
 
 Examples:
-    # Start (at the initial cycle point), or restart, or resume workflow REG.
+    # Start (at the initial cycle point), or restart, or resume workflow REG
     $ cylc play REG
 
     # Start a new run from a cycle point after the initial cycle point
@@ -71,6 +75,10 @@
     $ cylc play --start-task=foo.3 REG
     $ cylc play -t foo.3 -t bar.3 REG
 
+    # Start, restart or resume the second installed run of the workflow
+    # "dogs/fido"
+    $ cylc play dogs/fido/run2
+
 At restart, tasks recorded as submitted or running are polled to determine what
 happened to them while the workflow was down.
 """
@@ -225,8 +233,7 @@ def get_option_parser(add_std_opts=False):
 }
 
 
-RunOptions = Options(
-    get_option_parser(add_std_opts=True), DEFAULT_OPTS)
+RunOptions = Options(get_option_parser(add_std_opts=True), DEFAULT_OPTS)
 
 
 def _open_logs(reg, no_detach):
@@ -256,7 +263,7 @@ def _close_logs():
             handler.close()
 
 
-def scheduler_cli(parser, options, reg):
+def scheduler_cli(options: 'Values', reg: str) -> None:
     """Run the workflow.
 
     This function should contain all of the command line facing
@@ -369,6 +376,6 @@ async def _run(scheduler: Scheduler) -> int:
 
 
 @cli_function(get_option_parser)
-def play(parser, options, reg):
+def play(parser: COP, options: 'Values', reg: str):
     """Implement cylc play."""
-    return scheduler_cli(parser, options, reg)
+    return scheduler_cli(options, reg)

cylc/flow/scripts/broadcast.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""cylc broadcast [OPTIONS] REG
+"""cylc broadcast [OPTIONS] ARGS
 
 Override [runtime] configuration items in a running workflow.
 
@@ -75,11 +75,11 @@
 
 See also 'cylc reload' - reload a modified workflow definition at run time."""
 
-import os.path
-import sys
+from ansimarkup import parse as cparse
 import re
+import sys
 from tempfile import NamedTemporaryFile
-from ansimarkup import parse as cparse
+from typing import Any, Dict, TYPE_CHECKING
 
 from cylc.flow import ID_DELIM
 from cylc.flow.task_id import TaskID
@@ -95,6 +95,10 @@
 from cylc.flow.parsec.validate import cylc_config_validate
 from cylc.flow.workflow_files import parse_reg
 
+if TYPE_CHECKING:
+    from optparse import Values
+
+
 REC_ITEM = re.compile(r'^\[([^\]]*)\](.*)$')
 
 MUTATION = '''
@@ -218,7 +222,10 @@ def report_bad_options(bad_options, is_set=False):
 
 def get_option_parser():
     """CLI for "cylc broadcast"."""
-    parser = COP(__doc__, comms=True)
+    parser = COP(
+        __doc__, comms=True,
+        argdoc=[('REG', "Workflow name")]
+    )
 
     parser.add_option(
         "-p", "--point", metavar="CYCLE_POINT",
@@ -294,12 +301,12 @@ def get_option_parser():
 
 
 @cli_function(get_option_parser)
-def main(_, options, workflow):
+def main(_, options: 'Values', workflow: str) -> None:
     """Implement cylc broadcast."""
     workflow = parse_reg(workflow)
     pclient = get_client(workflow, timeout=options.comms_timeout)
 
-    mutation_kwargs = {
+    mutation_kwargs: Dict[str, Any] = {
         'request_string': MUTATION,
         'variables': {
             'wFlows': [workflow],
@@ -311,7 +318,7 @@ def main(_, options, workflow):
         }
     }
 
-    query_kwargs = {
+    query_kwargs: Dict[str, Any] = {
         'request_string': QUERY,
         'variables': {
             'wFlows': [workflow],

cylc/flow/scripts/client.py

@@ -24,16 +24,21 @@
 Use the -n option if client function requires no keyword arguments.
 """
 
+from google.protobuf.json_format import MessageToDict
 import json
 import sys
-from google.protobuf.json_format import MessageToDict
+from typing import TYPE_CHECKING
 
 from cylc.flow.option_parsers import CylcOptionParser as COP
 from cylc.flow.network.client import WorkflowRuntimeClient
-from cylc.flow.terminal import cli_function
 from cylc.flow.network.server import PB_METHOD_MAP
+from cylc.flow.terminal import cli_function
 from cylc.flow.workflow_files import parse_reg
 
+if TYPE_CHECKING:
+    from optparse import Values
+
+
 INTERNAL = True
 
 
@@ -51,7 +56,7 @@ def get_option_parser():
 
 
 @cli_function(get_option_parser)
-def main(_, options, workflow, func):
+def main(_, options: 'Values', workflow: str, func: str) -> None:
     workflow = parse_reg(workflow)
     pclient = WorkflowRuntimeClient(workflow, timeout=options.comms_timeout)
     if options.no_input:

cylc/flow/scripts/config.py

@@ -49,7 +49,7 @@
 """
 
 import os.path
-from typing import List, Optional
+from typing import List, Optional, TYPE_CHECKING
 
 from cylc.flow.cfgspec.glbl_cfg import glbl_cfg
 from cylc.flow.config import WorkflowConfig
@@ -59,6 +59,9 @@
 from cylc.flow.templatevars import load_template_vars
 from cylc.flow.terminal import cli_function
 
+if TYPE_CHECKING:
+    from optparse import Values
+
 
 def get_option_parser():
     parser = COP(
@@ -109,7 +112,7 @@ def get_config_file_hierarchy(reg: Optional[str] = None) -> List[str]:
 
 
 @cli_function(get_option_parser)
-def main(parser, options, reg=None):
+def main(parser: COP, options: 'Values', reg: Optional[str] = None) -> None:
     if options.print_hierarchy:
         print("\n".join(get_config_file_hierarchy(reg)))
         return

cylc/flow/scripts/diff.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""cylc diff [OPTIONS] WORKFLOW1 WORKFLOW2
+"""cylc diff [OPTIONS] ARGS
 
 Compare two workflow configurations and display any differences.
 

cylc/flow/scripts/dump.py

@@ -34,17 +34,21 @@
   # Display the state of all tasks in a particular cycle point:
   $ cylc dump -t WORKFLOW | grep 2010082406"""
 
-from cylc.flow.network.client_factory import get_client
-import sys
-import json
-
 from graphene.utils.str_converters import to_snake_case
+import json
+import sys
+from typing import TYPE_CHECKING
 
 from cylc.flow.exceptions import CylcError
 from cylc.flow.option_parsers import CylcOptionParser as COP
+from cylc.flow.network.client_factory import get_client
 from cylc.flow.terminal import cli_function
 from cylc.flow.workflow_files import parse_reg
 
+if TYPE_CHECKING:
+    from optparse import Values
+
+
 TASK_SUMMARY_FRAGMENT = '''
 fragment tProxy on TaskProxy {
   id
@@ -167,7 +171,7 @@ def get_option_parser():
 
 
 @cli_function(get_option_parser)
-def main(_, options, workflow):
+def main(_, options: 'Values', workflow: str) -> None:
     workflow = parse_reg(workflow)
     pclient = get_client(workflow, timeout=options.comms_timeout)
 

cylc/flow/scripts/ext_trigger.py

@@ -35,6 +35,7 @@
 Note: to manually trigger a task use 'cylc trigger', not this command."""
 
 from time import sleep
+from typing import TYPE_CHECKING
 
 from cylc.flow import LOG
 from cylc.flow.exceptions import CylcError, ClientError
@@ -43,6 +44,9 @@
 from cylc.flow.terminal import cli_function
 from cylc.flow.workflow_files import parse_reg
 
+if TYPE_CHECKING:
+    from optparse import Values
+
 
 MAX_N_TRIES = 5
 RETRY_INTVL_SECS = 10.0
@@ -89,7 +93,13 @@ def get_option_parser():
 
 
 @cli_function(get_option_parser)
-def main(parser, options, workflow, event_msg, event_id):
+def main(
+    parser: COP,
+    options: 'Values',
+    workflow: str,
+    event_msg: str,
+    event_id: str
+) -> None:
     workflow = parse_reg(workflow)
     LOG.info('Send to workflow %s: "%s" (%s)', workflow, event_msg, event_id)
     pclient = get_client(workflow, timeout=options.comms_timeout)