runem 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

runem/VERSION

@@ -1 +1 @@
-0.3.0
+0.5.0

runem/blocking_print.py

@@ -1,6 +1,40 @@
 import time
 import typing
 
+from rich.console import Console
+
+
+def _reset_console() -> Console:
+    """Sets the nice user-facing console.
+
+    This function exists so we can reset the output from tests.
+    """
+    global RICH_CONSOLE  # pylint: disable=global-statement
+
+    RICH_CONSOLE = Console(
+        log_path=False,  # Do NOT print the source path.
+        markup=False,  # Do NOT print markup e.g. `[blink]Don't Panic![/blink]`.
+    )
+    return RICH_CONSOLE
+
+
+# Overridden in tests.
+RICH_CONSOLE: Console = _reset_console()
+
+
+def _reset_console_for_tests() -> None:
+    """Overrides the console output with more deterministic version.
+
+    ... so we can have deterministic tests.
+    """
+    global RICH_CONSOLE  # pylint: disable=global-statement
+    RICH_CONSOLE = Console(
+        log_path=False,  # Do NOT print the source path.
+        log_time=False,  # Do not prefix with log time e.g. `[time] log message`.
+        markup=False,  # Do NOT print markup e.g. `[blink]Don't Panic![/blink]`.
+        width=999,  # A very wide width.
+    )
+
 
 def blocking_print(
     msg: str = "",
@@ -15,9 +49,11 @@ def blocking_print(
     already being written to (for example), i.e. the `print` would need to be a
     'blocking' call, which it is not.
     """
+    if end is None:
+        end = "\n"
     for _ in range(max_retries):
         try:
-            print(msg, end=end)
+            RICH_CONSOLE.print(msg, end=end)
             break  # Success, exit the retry loop
         except BlockingIOError:
             time.sleep(sleep_time_s)  # Wait a bit for the buffer to clear

runem/cli/initialise_options.py

@@ -0,0 +1,26 @@
+import argparse
+
+from runem.config_metadata import ConfigMetadata
+from runem.informative_dict import InformativeDict
+from runem.types.options import OptionsWritable
+
+
+def initialise_options(
+    config_metadata: ConfigMetadata,
+    args: argparse.Namespace,
+) -> OptionsWritable:
+    """Initialises and returns the set of options to use for this run.
+
+    Returns the options dictionary
+    """
+
+    options: OptionsWritable = InformativeDict(
+        {option["name"]: option["default"] for option in config_metadata.options_config}
+    )
+    if config_metadata.options_config and args.overrides_on:  # pragma: no branch
+        for option_name in args.overrides_on:  # pragma: no branch
+            options[option_name] = True
+    if config_metadata.options_config and args.overrides_off:  # pragma: no branch
+        for option_name in args.overrides_off:
+            options[option_name] = False
+    return options

runem/command_line.py

@@ -53,6 +53,14 @@ def _get_argparse_help_formatter() -> typing.Any:
     return argparse.HelpFormatter
 
 
+def error_on_log_logic(verbose: bool, silent: bool) -> None:
+    """Simply errors if we get logical inconsistencies in the logging-logic."""
+    if verbose and silent:
+        log("cannot parse '--verbose' and '--silent'")
+        # error exit
+        sys.exit(1)
+
+
 def parse_args(
     config_metadata: ConfigMetadata, argv: typing.List[str]
 ) -> ConfigMetadata:
@@ -130,7 +138,9 @@ def parse_args(
         nargs="+",
         default=config_metadata.all_job_tags,
         help=(
-            "Only jobs with the given tags. "
+            # TODO: clarify the logic by which we add/remove jobs based on tags
+            #       e.g. exclusive-in, union, x-or etc.
+            "Only run jobs with the given tags. "
             f"Defaults to '{sorted(config_metadata.all_job_tags)}'."
         ),
         required=False,
@@ -238,6 +248,16 @@ def parse_args(
         required=False,
     )
 
+    parser.add_argument(
+        "--silent",
+        "-s",
+        dest="silent",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help=("Whether to show warning messages or not. "),
+        required=False,
+    )
+
     parser.add_argument(
         "--spinner",
         dest="show_spinner",
@@ -271,6 +291,8 @@ def parse_args(
 
     args = parser.parse_args(argv[1:])
 
+    error_on_log_logic(args.verbose, args.silent)
+
     if args.show_root_path_and_exit:
         log(str(config_metadata.cfg_filepath.parent), decorate=False)
         # cleanly exit

runem/config_parse.py

@@ -149,6 +149,7 @@ def parse_job_config(
     in_out_job_names: JobNames,
     in_out_phases: JobPhases,
     phase_order: OrderedPhases,
+    silent: bool = False,
 ) -> None:
     """Parses and validates a job-entry read in from disk.
 
@@ -208,6 +209,7 @@ def parse_job_config(
                 in_out_job_names,
                 in_out_phases,
                 phase_order,
+                warn_missing_phase=(not silent),
             )
     except KeyError as err:
         raise ValueError(
@@ -215,8 +217,11 @@ def parse_job_config(
         ) from err
 
 
-def parse_config(
-    config: Config, cfg_filepath: pathlib.Path, hooks_only: bool = False
+def parse_config(  # noqa: C901
+    config: Config,
+    cfg_filepath: pathlib.Path,
+    silent: bool = False,
+    hooks_only: bool = False,
 ) -> typing.Tuple[
     Hooks,  # hooks:
     OrderedPhases,  # phase_order:
@@ -282,7 +287,10 @@ def parse_config(
 
     if not phase_order:
         if not hooks_only:
-            warn("phase ordering not configured! Runs will be non-deterministic!")
+            if silent:  # pragma: no cover
+                pass
+            else:
+                warn("phase ordering not configured! Runs will be non-deterministic!")
             phase_order = tuple(job_phases)
 
     # now parse out the job_configs
@@ -301,6 +309,7 @@ def parse_config(
             in_out_job_names=job_names,
             in_out_phases=job_phases,
             phase_order=phase_order,
+            silent=silent,
         )
     return (
         hooks,
@@ -341,7 +350,9 @@ def generate_config(
 
 
 def _load_user_hooks_from_config(
-    user_config: Config, cfg_filepath: pathlib.Path
+    user_config: Config,
+    cfg_filepath: pathlib.Path,
+    silent: bool,
 ) -> Hooks:
     hooks: Hooks
     (
@@ -353,7 +364,7 @@ def _load_user_hooks_from_config(
         _,
         _,
         _,
-    ) = parse_config(user_config, cfg_filepath, hooks_only=True)
+    ) = parse_config(user_config, cfg_filepath, silent, hooks_only=True)
     return hooks
 
 
@@ -361,6 +372,7 @@ def load_config_metadata(
     config: Config,
     cfg_filepath: pathlib.Path,
     user_configs: typing.List[typing.Tuple[Config, pathlib.Path]],
+    silent: bool = False,
     verbose: bool = False,
 ) -> ConfigMetadata:
     hooks: Hooks
@@ -380,12 +392,14 @@ def load_config_metadata(
         job_names,
         job_phases,
         tags,
-    ) = parse_config(config, cfg_filepath)
+    ) = parse_config(config, cfg_filepath, silent)
 
     user_config: Config
     user_config_path: pathlib.Path
     for user_config, user_config_path in user_configs:
-        user_hooks: Hooks = _load_user_hooks_from_config(user_config, user_config_path)
+        user_hooks: Hooks = _load_user_hooks_from_config(
+            user_config, user_config_path, silent
+        )
         if user_hooks:
             if verbose:
                 log(f"hooks: loading user hooks from '{str(user_config_path)}'")

runem/job_execute.py

@@ -11,7 +11,7 @@ from runem.config_metadata import ConfigMetadata
 from runem.informative_dict import ReadOnlyInformativeDict
 from runem.job import Job
 from runem.job_wrapper import get_job_wrapper
-from runem.log import error, log
+from runem.log import error, log, warn
 from runem.types.common import FilePathList, JobTags
 from runem.types.filters import FilePathListLookup
 from runem.types.runem_config import JobConfig
@@ -50,7 +50,8 @@ def job_execute_inner(
 
     if not file_list:
         # no files to work on
-        log(f"WARNING: skipping job '{label}', no files for job")
+        if not config_metadata.args.silent:
+            warn(f"skipping job '{label}', no files for job")
         return {
             "job": (f"{label}: no files!", timedelta(0)),
             "commands": [],

runem/runem.py

@@ -36,7 +36,8 @@ from rich.console import Console, ConsoleOptions, ConsoleRenderable, RenderResul
 from rich.spinner import Spinner
 from rich.text import Text
 
-from runem.command_line import parse_args
+from runem.blocking_print import RICH_CONSOLE
+from runem.command_line import error_on_log_logic, parse_args
 from runem.config import load_project_config, load_user_configs
 from runem.config_metadata import ConfigMetadata
 from runem.config_parse import load_config_metadata
@@ -57,8 +58,6 @@ from runem.types.types_jobs import (
 )
 from runem.utils import printable_set
 
-rich_console = Console()
-
 
 def _determine_run_parameters(argv: typing.List[str]) -> ConfigMetadata:
     """Loads config, parsing cli input and produces the run config.
@@ -68,12 +67,19 @@ def _determine_run_parameters(argv: typing.List[str]) -> ConfigMetadata:
 
     Return a ConfigMetadata object with all the required information.
     """
+
+    # Because we want to be able to show logging whilst parsing .runem.yml config, we
+    # need to check the state of the logging-verbosity switches here, manually, as well.
+    verbose = "--verbose" in argv
+    silent = ("--silent" in argv) or ("-s" in argv)
+    error_on_log_logic(verbose, silent)
+
     config: Config
     cfg_filepath: pathlib.Path
     config, cfg_filepath = load_project_config()
     user_configs: typing.List[typing.Tuple[Config, pathlib.Path]] = load_user_configs()
     config_metadata: ConfigMetadata = load_config_metadata(
-        config, cfg_filepath, user_configs, verbose=("--verbose" in argv)
+        config, cfg_filepath, user_configs, silent, verbose=("--verbose" in argv)
     )
 
     # Now we parse the cli arguments extending them with information from the
@@ -143,7 +149,7 @@ def _update_progress(
 
     last_running_jobs_set: typing.Set[str] = set()
 
-    with rich_console.status(spinner):
+    with RICH_CONSOLE.status(spinner):
         while is_running.value:
             running_jobs_set: typing.Set[str] = set(running_jobs.values())
 
@@ -157,7 +163,7 @@ def _update_progress(
                 spinner.text = report
             else:
                 if last_running_jobs_set != running_jobs_set:
-                    rich_console.log(report)
+                    RICH_CONSOLE.log(report)
 
             # Sleep for reduced CPU usage
             time.sleep(0.1)

{runem-0.3.0.dist-info → runem-0.5.0.dist-info}/METADATA

@@ -1,15 +1,23 @@
 Metadata-Version: 2.1
 Name: runem
-Version: 0.3.0
+Version: 0.5.0
 Summary: Awesome runem created by lursight
-Home-page: https://github.com/lursight/runem/
 Author: lursight
+License: Specify your license here
+Project-URL: Homepage, https://github.com/lursight/runem/
+Keywords: example,runem
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: packaging
-Requires-Dist: PyYAML
-Requires-Dist: rich
-Requires-Dist: typing_extensions
+Requires-Dist: packaging>=22.0
+Requires-Dist: PyYAML>=5.0.0
+Requires-Dist: rich>10.0.0
+Requires-Dist: typing_extensions>3.0.0
 Provides-Extra: tests
 Requires-Dist: black==24.10.0; extra == "tests"
 Requires-Dist: coverage==7.5; extra == "tests"
@@ -153,3 +161,4 @@ Read the [CONTRIBUTING.md](CONTRIBUTING.md) file.
 The runem mission is to improve developer velocity at
 [Lursight Ltd.](https://lursight.com), read more about the runem
 [mission](https://lursight.github.io/runem/docs/mission.html).
+

{runem-0.3.0.dist-info → runem-0.5.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
-runem/VERSION,sha256=2RXMldbKj0euKXcT7UbU5cXZnd0p_Dxh4mO98wXytbA,6
+runem/VERSION,sha256=oK1QZAE5pST4ZZEVcUW_HUZ06pwGW_6iFVjw97BEMMg,6
 runem/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 runem/__main__.py,sha256=dsOiVZegpfK9JOs5n7UmbX5iwwbj7iFkEbLoVeEgAn4,136
 runem/base.py,sha256=EZfR7FIlwEdU9Vfe47Wk2DOO8GQqpKxxLNKp6YHueZ4,316
-runem/blocking_print.py,sha256=S9dtgAeuTzc2-ht-vk9Wl6l-0PwS2tYbHDHDQQitrlA,841
+runem/blocking_print.py,sha256=R3c3HSnRMPCf7ykDXdKG2hKH4CzbBaxmOfP3xEU_wEI,1919
 runem/cli.py,sha256=wEt_Jnumhl8SiOdKdSJzLkJpWv6n3_Odhi_HeIixr1k,134
-runem/command_line.py,sha256=HsZjxJsVQZLfAeSRI6cpx6P1foeuqCYhHmeQ8Xg9RHY,13774
+runem/command_line.py,sha256=qkZFCCq9hUl6RO398SJzoigv8di5jGw2sdNwgTVBdd8,14474
 runem/config.py,sha256=UiEU0Jyg5qjrNStvasWYjMOABQHhpZjbPiX3-sH_CMg,5969
 runem/config_metadata.py,sha256=krDomUcADsAeUQrxwNmOS58eeaNIlqmhWIKWv8mUH4A,3300
-runem/config_parse.py,sha256=sXPMA8HSUcaJoq0dUfphK181waZqnIrq20mpYOQ_XCo,13498
+runem/config_parse.py,sha256=zXQ4rpj-igQufB5JtTsI1mOE_gBTdBcI2hI6HWU28gg,13830
 runem/files.py,sha256=59boeFvUANYOS-PllIjeKIht6lNINZ43WxahDg90oAc,4392
 runem/hook_manager.py,sha256=H0TL3HCqU2mgKm_-dgCD7TsK5T1bLT4g7x6kpytMPhU,4350
 runem/informative_dict.py,sha256=U7p9z78UwOT4TAfng1iDXCEyeYz6C-XZlx9Z1pWNVrI,1548
 runem/job.py,sha256=NOdRQnGePPyYdmIR_6JKVFzp9nbgNGetpE13bHEHaf4,3442
-runem/job_execute.py,sha256=BPkeTpeTGJs3QWa0-07DZvF1f0uKO79e4yMsTxq1UHk,4656
+runem/job_execute.py,sha256=-76IJI0PDU_XdQiDxTKUfOHEno9pixxQb_zi58rFumo,4702
 runem/job_filter.py,sha256=7vgG4YWJ9gyGBFjV7QbSojG5ofYoszAmxXx9HnMLkHo,5384
 runem/job_runner_simple_command.py,sha256=iP5an6yixW8o4C0ZBtu6csb-oVK3Q62ZZgtHBmxlXaU,2428
 runem/job_wrapper.py,sha256=q5GtopZ5vhSJ581rwU4-lF9KnbL3ZYgOC8fqaCnXD_g,983
@@ -21,9 +21,10 @@ runem/log.py,sha256=dIrocigvIJs1ZGkAzTogXkAK-0ZW3q5FkjpDgLdeW-E,630
 runem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 runem/report.py,sha256=IedwW9mmJfGC6vKQdKDHQH5eoiYzTWHaaD4a3J4e_Pc,9020
 runem/run_command.py,sha256=Egl_j4bJ9mwi2JEFCsl0W6WH2IRgIdpMN7qdj8voClQ,6386
-runem/runem.py,sha256=QbJU48zx1hyiRIG5Kf4DAa4Kka2dOKYgqlZ1T6fN62k,13316
+runem/runem.py,sha256=9QZgmXNPXOscRRLWDgOcPZ0lYRcG7jOog1M_o3MXZbs,13667
 runem/runem_version.py,sha256=MbETwZO2Tb1Y3hX_OYZjKepEMKA1cjNvr-7Cqhz6e3s,271
 runem/utils.py,sha256=3N_kel9LsriiMq7kOjT14XhfxUOgz4hdDg97wlLKm3U,221
+runem/cli/initialise_options.py,sha256=zx_EduWQk7yGBr3XUNrffHCSInPv05edFItHLnlo9dk,918
 runem/types/__init__.py,sha256=6TzF4KV9tDGuDTr2qAXmWWkfDU52WuVlQ8Hcz48aYDk,286
 runem/types/common.py,sha256=gPMSoJ3yRUYjHnoviRrpSg0gRwsGLFGWGpbTWkq4jX0,279
 runem/types/errors.py,sha256=rbM5BA6UhY1X7Q0OZLUNsG7JXAjgNFTG5KQuqPNuZm8,103
@@ -32,11 +33,20 @@ runem/types/hooks.py,sha256=lgrv5QAuHCEzr5dXDj4-azNcs63addY9zdrGWj5zv_s,292
 runem/types/options.py,sha256=y8_hyWYvhalC9-kZbvoDtxm0trZgyyGcswQqfuQy_pM,265
 runem/types/runem_config.py,sha256=qG_bghm5Nr-ZTbaZbf1v8Fx447V-hgEvvRy5NZ3t-Io,5141
 runem/types/types_jobs.py,sha256=wqiiBmRIJDbGlKcfOqewHGKx350w0p4_7pysMm7xGmo,4906
+scripts/test_hooks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scripts/test_hooks/json_validators.py,sha256=N2FyWcpjWzfFGycXLo-ecNLJkxTFPPbqPfVBcJLBlb4,967
+scripts/test_hooks/py.py,sha256=YUbwNny7NPmv2bY7k7YcbJ-jRcnNfjQajE9Hn1MLaBc,8821
+scripts/test_hooks/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scripts/test_hooks/runem_hooks.py,sha256=FJMuDBEOz3dr9gBW3WW6yKbUJs_LFXb3klpqSzCAZRk,628
+scripts/test_hooks/yarn.py,sha256=1QsG1rKAclpZoqp86ntkuvzYaYN4UkEvO0JhO2Kf5C8,1082
+tests/cli/test_initialise_options.py,sha256=Ogwfqz39r2o1waXMqCC22OJsgZoLF2stwGVO5AZUc4s,3148
+tests/data/help_output.3.10.txt,sha256=5TUpNITVL6pD5BpFAl-Orh3vkOpStveijZzvgJuI_sA,4280
+tests/data/help_output.3.11.txt,sha256=ycrF-xKgdQ8qrWzkkR-vbHe7NulUTsCsS0_Gda8xYDs,4162
 tests/test_types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/test_types/test_public_api.py,sha256=QHiwt7CetQur65JSbFRnOzQxhCJkX5MVLymHHVd_6yc,160
-runem-0.3.0.dist-info/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
-runem-0.3.0.dist-info/METADATA,sha256=60xJCeO4__eyLluCyFosw1UTsIbs1dyQFruOJ6iNM7I,5842
-runem-0.3.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-runem-0.3.0.dist-info/entry_points.txt,sha256=nu0g_vBeuPihYtimbtlNusxWovylMppvJ8UxdJlJfvM,46
-runem-0.3.0.dist-info/top_level.txt,sha256=Zu65aVeDPh8WbChU4Mi7-Md4S3XJDPuqdQjEE3DSQno,12
-runem-0.3.0.dist-info/RECORD,,
+runem-0.5.0.dist-info/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
+runem-0.5.0.dist-info/METADATA,sha256=9isKJbNwlMOME8i2ipmSBySxD-Om_tVIp0ji_3WJeRM,6215
+runem-0.5.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+runem-0.5.0.dist-info/entry_points.txt,sha256=nu0g_vBeuPihYtimbtlNusxWovylMppvJ8UxdJlJfvM,46
+runem-0.5.0.dist-info/top_level.txt,sha256=NkdxkwLKNNhxItveR2KqNqTshTZ268m5D7SjJEmG4-Y,20
+runem-0.5.0.dist-info/RECORD,,

{runem-0.3.0.dist-info → runem-0.5.0.dist-info}/top_level.txt

@@ -1,2 +1,3 @@
 runem
+scripts
 tests

scripts/test_hooks/json_validators.py

@@ -0,0 +1,32 @@
+import pathlib
+
+from typing_extensions import Unpack
+
+from runem.run_command import run_command
+from runem.types import FilePathList, JobKwargs
+
+
+def _json_validate(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    label = kwargs["label"]
+    json_files: FilePathList = kwargs["file_list"]
+    json_with_comments = (
+        "cspell.json",
+        "tsconfig.spec.json",
+        "launch.json",
+        "settings.json",
+    )
+    for json_file in json_files:
+        json_path = pathlib.Path(json_file)
+        if not json_path.exists():
+            raise RuntimeError(
+                f"could not find '{str(json_path)}, in {pathlib.Path('.').absolute()}"
+            )
+        if json_path.name in json_with_comments:
+            # until we use a validator that allows comments in json, skip these
+            continue
+
+        cmd = ["python", "-m", "json.tool", f"{json_file}"]
+        kwargs["label"] = f"{label} {json_file}"
+        run_command(cmd=cmd, **kwargs)

scripts/test_hooks/py.py

@@ -0,0 +1,292 @@
+import pathlib
+import shutil
+import typing
+
+from typing_extensions import Unpack
+
+from runem.log import log
+from runem.run_command import RunCommandUnhandledError, run_command
+from runem.types import FilePathList, JobKwargs, JobName, JobReturnData, Options
+
+
+def _job_py_code_reformat(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    """Runs python formatting code in serial order as one influences the other."""
+    label: JobName = kwargs["label"]
+    options: Options = kwargs["options"]
+    python_files: FilePathList = kwargs["file_list"]
+
+    # put into 'check' mode if requested on the command line
+    extra_args = []
+    docformatter_extra_args = [
+        "--in-place",
+    ]
+    if options["check-only"]:
+        extra_args.append("--check")
+        docformatter_extra_args = []  # --inplace is not compatible with --check
+
+    if options["isort"]:
+        isort_cmd = [
+            "python3",
+            "-m",
+            "isort",
+            "--profile",
+            "black",
+            "--treat-all-comment-as-code",
+            *extra_args,
+            *python_files,
+        ]
+        kwargs["label"] = f"{label} isort"
+        run_command(cmd=isort_cmd, **kwargs)
+
+    if options["black"]:
+        black_cmd = [
+            "python3",
+            "-m",
+            "black",
+            *extra_args,
+            *python_files,
+        ]
+        kwargs["label"] = f"{label} black"
+        run_command(cmd=black_cmd, **kwargs)
+
+    if options["docformatter"]:
+        docformatter_cmd = [
+            "python3",
+            "-m",
+            "docformatter",
+            "--wrap-summaries",
+            "88",
+            "--wrap-descriptions",
+            "88",
+            *docformatter_extra_args,
+            *extra_args,
+            *python_files,
+        ]
+        allowed_exits: typing.Tuple[int, ...] = (
+            0,  # no work/change required
+            3,  # no errors, but code was reformatted
+        )
+        if options["check-only"]:
+            # in check it is ONLY ok if no work/change was required
+            allowed_exits = (0,)
+        kwargs["label"] = f"{label} docformatter"
+        run_command(
+            cmd=docformatter_cmd,
+            ignore_fails=False,
+            valid_exit_ids=allowed_exits,
+            **kwargs,
+        )
+
+
+def _job_py_pylint(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    python_files: FilePathList = kwargs["file_list"]
+    root_path: pathlib.Path = kwargs["root_path"]
+
+    pylint_cfg = root_path / ".pylint.rc"
+    if not pylint_cfg.exists():
+        raise RuntimeError(f"PYLINT Config not found at '{pylint_cfg}'")
+
+    pylint_cmd = [
+        "python3",
+        "-m",
+        "pylint",
+        "-j1",
+        "--score=n",
+        f"--rcfile={pylint_cfg}",
+        *python_files,
+    ]
+    run_command(cmd=pylint_cmd, **kwargs)
+
+
+def _job_py_flake8(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    python_files: FilePathList = kwargs["file_list"]
+    root_path: pathlib.Path = kwargs["root_path"]
+    flake8_rc = root_path / ".flake8"
+    if not flake8_rc.exists():
+        raise RuntimeError(f"flake8 config not found at '{flake8_rc}'")
+
+    flake8_cmd = [
+        "python3",
+        "-m",
+        "flake8",
+        *python_files,
+    ]
+    run_command(cmd=flake8_cmd, **kwargs)
+
+
+def _job_py_mypy(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    python_files: FilePathList = kwargs["file_list"]
+    mypy_cmd = ["python3", "-m", "mypy", *python_files]
+    output = run_command(cmd=mypy_cmd, **kwargs)
+    if "mypy.ini" in output or "Not a boolean:" in output:
+        raise RunCommandUnhandledError(f"runem: mypy mis-config detected: {output}")
+
+
+def _delete_old_coverage_reports(root_path: pathlib.Path) -> None:
+    """To avoid false-positives on coverage we delete the coverage report files."""
+    old_coverage_report_files: typing.List[pathlib.Path] = list(
+        root_path.glob(".coverage_report*")
+    )
+    for old_coverage_report in old_coverage_report_files:
+        old_coverage_report.unlink()
+
+
+def _job_py_pytest(  # noqa: C901 # pylint: disable=too-many-branches,too-many-statements
+    **kwargs: Unpack[JobKwargs],
+) -> JobReturnData:
+    label: JobName = kwargs["label"]
+    options: Options = kwargs["options"]
+    procs: int = kwargs["procs"]
+    root_path: pathlib.Path = kwargs["root_path"]
+
+    reports: JobReturnData = {"reportUrls": []}
+    # TODO: use pytest.ini config pytest
+    # pytest_cfg = root_path / ".pytest.ini"
+    # assert pytest_cfg.exists()
+
+    if not options["unit-test"]:
+        # we've disabled unit-testing on the cli
+        return reports
+
+    if options["profile"]:
+        raise RuntimeError("not implemented - see run_test.sh for how to implement")
+
+    pytest_path = root_path / "tests"
+    assert pytest_path.exists()
+
+    coverage_switches: typing.List[str] = []
+    coverage_cfg = root_path / ".coveragerc"
+    if options["coverage"]:
+        _delete_old_coverage_reports(root_path)
+        assert coverage_cfg.exists()
+        coverage_switches = [
+            "--cov=.",
+            f"--cov-config={str(coverage_cfg)}",
+            "--cov-append",
+            "--no-cov-on-fail",  # do not show coverage terminal report when we fail
+            "--cov-fail-under=0",  # we do coverage filing later
+        ]
+
+    # TODO: do we want to disable logs on pytest runs?
+    # "PYTEST_LOG":"--no-print-logs --log-level=CRITICAL" ;
+
+    threading_switches: typing.List[str] = []
+    if procs == -1:
+        threading_switches = ["-n", "auto"]
+
+    verbose_switches: typing.List[str] = []
+    if "verbose" in kwargs and kwargs["verbose"]:
+        verbose_switches = ["-vvv"]
+
+    profile_switches: typing.List[str] = []
+    cmd_pytest = [
+        "python3",
+        "-m",
+        "pytest",
+        "--color=yes",
+        *threading_switches,
+        # "-c",
+        # str(pytest_cfg),
+        *coverage_switches,
+        "--failed-first",
+        "--exitfirst",
+        *profile_switches,
+        *verbose_switches,
+        str(pytest_path),
+    ]
+
+    env_overrides: typing.Dict[str, str] = {}
+
+    kwargs["label"] = f"{label} pytest"
+    run_command(
+        cmd=cmd_pytest,
+        env_overrides=env_overrides,
+        **kwargs,
+    )
+
+    if options["coverage"]:
+        reports_dir: pathlib.Path = root_path / "reports"
+        reports_dir.mkdir(parents=False, exist_ok=True)
+        coverage_output_dir: pathlib.Path = reports_dir / "coverage_python"
+        if coverage_output_dir.exists():
+            shutil.rmtree(coverage_output_dir)
+        coverage_output_dir.mkdir(exist_ok=True)
+        if kwargs["verbose"]:
+            log("COVERAGE: Collating coverage")
+        # first generate the coverage report for our gitlab cicd
+        gen_cobertura_coverage_report_cmd = [
+            "python3",
+            "-m",
+            "coverage",
+            "xml",
+            "-o",
+            str(coverage_output_dir / "cobertura.xml"),
+            f"--rcfile={str(coverage_cfg)}",
+        ]
+        kwargs["label"] = f"{label} coverage cobertura"
+        run_command(cmd=gen_cobertura_coverage_report_cmd, **kwargs)
+
+        # then a html report
+        gen_html_coverage_report_cmd = [
+            "python3",
+            "-m",
+            "coverage",
+            "html",
+            f"--rcfile={str(coverage_cfg)}",
+        ]
+        kwargs["label"] = f"{label} coverage html"
+        run_command(cmd=gen_html_coverage_report_cmd, **kwargs)
+
+        # then a standard command-line report that causes the tests to fail.
+        gen_cli_coverage_report_cmd = [
+            "python3",
+            "-m",
+            "coverage",
+            "report",
+            "--fail-under=100",
+            f"--rcfile={str(coverage_cfg)}",
+        ]
+        kwargs["label"] = f"{label} coverage cli"
+        report_html = coverage_output_dir / "index.html"
+        report_cobertura = coverage_output_dir / "cobertura.xml"
+        try:
+            run_command(cmd=gen_cli_coverage_report_cmd, **kwargs)
+        except BaseException:
+            print()
+            print(report_html)
+            print(report_cobertura)
+            raise
+        assert coverage_output_dir.exists(), coverage_output_dir
+        assert report_html.exists(), report_html
+        assert report_cobertura.exists(), report_cobertura
+        reports["reportUrls"].append(("coverage html", report_html))
+        reports["reportUrls"].append(("coverage cobertura", report_cobertura))
+        if kwargs["verbose"]:
+            log("COVERAGE: cli output done")
+    return reports
+
+
+def _install_python_requirements(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    options: Options = kwargs["options"]
+    if not (options["install-deps"]):
+        # not enabled
+        return
+    cmd = [
+        "python3",
+        "-m",
+        "pip",
+        "install",
+        "-e",
+        ".[tests]",
+    ]
+    run_command(cmd=cmd, **kwargs)

scripts/test_hooks/runem_hooks.py

@@ -0,0 +1,19 @@
+import pathlib
+from datetime import timedelta
+
+from typing_extensions import Unpack
+
+from runem.types import HookKwargs
+
+
+def _on_exit_hook(
+    **kwargs: Unpack[HookKwargs],
+) -> None:
+    """A noddy hook."""
+    assert "wall_clock_time_saved" in kwargs
+    wall_clock_time_saved: timedelta = kwargs["wall_clock_time_saved"]
+    root_path: pathlib.Path = pathlib.Path(__file__).parent.parent.parent
+    assert (root_path / ".runem.yml").exists()
+    times_log: pathlib.Path = root_path / ".times.log"
+    with times_log.open("a", encoding="utf-8") as file:
+        file.write(f"{str(wall_clock_time_saved.total_seconds())}\n")

scripts/test_hooks/yarn.py

@@ -0,0 +1,48 @@
+import pathlib
+
+from typing_extensions import Unpack
+
+from runem.run_command import run_command
+from runem.types import JobKwargs, Options
+
+
+def _job_yarn_deps(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    """Installs the yarn deps."""
+    options: Options = kwargs["options"]
+
+    install_requested = options["install-deps"]
+    if not (install_requested):
+        root_path: pathlib.Path = kwargs["root_path"]
+        if (root_path / "node_modules").exists():
+            # An install was not requested, nor required.
+            return
+
+    install_cmd = [
+        "yarn",
+        "install",
+    ]
+
+    run_command(cmd=install_cmd, **kwargs)
+
+
+def _job_prettier(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    """Runs prettifier on files, including json and maybe yml file.
+
+    TODO: connect me up!
+    """
+    options: Options = kwargs["options"]
+    command_variant = "pretty"
+    if options["check-only"]:
+        command_variant = "prettyCheck"
+
+    pretty_cmd = [
+        "yarn",
+        "run",
+        command_variant,
+    ]
+
+    run_command(cmd=pretty_cmd, **kwargs)

tests/cli/test_initialise_options.py

@@ -0,0 +1,105 @@
+import pathlib
+from argparse import Namespace
+from collections import defaultdict
+from typing import Dict
+from unittest.mock import MagicMock
+
+import pytest
+
+from runem.command_line import initialise_options
+from runem.config_metadata import ConfigMetadata
+from runem.types.runem_config import JobConfig, PhaseGroupedJobs
+
+Options = Dict[str, bool]
+
+
+@pytest.fixture(name="config_metadata")
+def config_metadata_fixture() -> ConfigMetadata:
+    config_file_path = pathlib.Path(__file__).parent / ".runem.yml"
+    expected_job: JobConfig = {
+        "addr": {
+            "file": "test_config_parse.py",
+            "function": "test_parse_config",
+        },
+        "label": "dummy job label",
+        "when": {
+            "phase": "dummy phase 1",
+            "tags": {"dummy tag 1", "dummy tag 2"},
+        },
+    }
+    expected_jobs: PhaseGroupedJobs = defaultdict(list)
+    expected_jobs["dummy phase 1"] = [
+        expected_job,
+    ]
+    return ConfigMetadata(
+        cfg_filepath=config_file_path,
+        phases=("dummy phase 1",),
+        options_config=(
+            {"name": "option1", "default": True},
+            {"name": "option2", "default": False},
+            {"name": "option3", "default": True},
+            {"name": "option4", "default": False},
+        ),
+        file_filters={
+            # "dummy tag": {
+            #     "tag": "dummy tag",
+            #     "regex": ".*1.txt",  # should match just one file
+            # }
+        },
+        hook_manager=MagicMock(),
+        jobs=expected_jobs,
+        all_job_names=set(("dummy job label",)),
+        all_job_phases=set(("dummy phase 1",)),
+        all_job_tags=set(
+            (
+                "dummy tag 2",
+                "dummy tag 1",
+            )
+        ),
+    )
+
+
+def test_initialise_options_no_overrides(config_metadata: ConfigMetadata) -> None:
+    args = Namespace(overrides_on=[], overrides_off=[])
+    options = initialise_options(config_metadata, args)
+    assert options == {
+        "option1": True,
+        "option2": False,
+        "option3": True,
+        "option4": False,
+    }
+
+
+def test_initialise_options_overrides_on(config_metadata: ConfigMetadata) -> None:
+    args = Namespace(overrides_on=["option2", "option4"], overrides_off=[])
+    options = initialise_options(config_metadata, args)
+    assert options == {
+        "option1": True,
+        "option2": True,
+        "option3": True,
+        "option4": True,
+    }
+
+
+def test_initialise_options_overrides_off(config_metadata: ConfigMetadata) -> None:
+    args = Namespace(overrides_on=[], overrides_off=["option1", "option3"])
+    options = initialise_options(config_metadata, args)
+    assert options == {
+        "option1": False,
+        "option2": False,
+        "option3": False,
+        "option4": False,
+    }
+
+
+def test_initialise_options_overrides_on_and_off(
+    config_metadata: ConfigMetadata,
+) -> None:
+    args = Namespace(overrides_on=["option2"], overrides_off=["option1"])
+    options = initialise_options(config_metadata, args)
+    assert options == {
+        "option1": False,
+        "option2": True,
+        "option3": True,
+        "option4": False,
+    }

tests/data/help_output.3.10.txt

@@ -0,0 +1,55 @@
+runem: WARNING: no phase found for 'echo "hello world!"', using 'dummy phase 1'
+usage: -c [-H] [--jobs JOBS [JOBS ...]] [--not-jobs JOBS_EXCLUDED [JOBS_EXCLUDED ...]] [--phases PHASES [PHASES ...]] [--not-phases PHASES_EXCLUDED [PHASES_EXCLUDED ...]] [--tags TAGS [TAGS ...]] [--not-tags TAGS_EXCLUDED [TAGS_EXCLUDED ...]] [--dummy-option-1---complete-option] [--no-dummy-option-1---complete-option] [--dummy-option-2---minimal] [--no-dummy-option-2---minimal] [--call-graphs | --no-call-graphs] [-f | --modified-files | --no-modified-files] [-h | --git-head-files | --no-git-head-files] [--always-files ALWAYS_FILES [ALWAYS_FILES ...]] [--git-files-since-branch GIT_SINCE_BRANCH] [--procs PROCS] [--root ROOT_DIR] [--root-show | --no-root-show] [--silent | --no-silent | -s] [--spinner | --no-spinner] [--verbose | --no-verbose] [--version | --no-version | -v]
+
+Runs the Lursight Lang test-suite
+
+[TEST_REPLACED_OPTION_HEADER]
+  -H, --help            show this help message and exit
+  --call-graphs, --no-call-graphs
+  -f, --modified-files, --no-modified-files
+                        only use files that have changed (default: False)
+  -h, --git-head-files, --no-git-head-files
+                        fast run of files (default: False)
+  --always-files ALWAYS_FILES [ALWAYS_FILES ...]
+                        list of paths/files to always check (overriding -f/-h), if the path matches the filter regex and if file-paths exist
+  --git-files-since-branch GIT_SINCE_BRANCH
+                        Get the list of paths/files changed between a branch, e.g., since 'origin/main'. Useful for checking files changed before pushing.
+  --procs PROCS, -j PROCS
+                        the number of concurrent test jobs to run, -1 runs all test jobs at the same time ([TEST_REPLACED_CORES] cores available)
+  --root ROOT_DIR       which dir to use as the base-dir for testing, defaults to directory containing the config '[TEST_REPLACED_DIR]'
+  --root-show, --no-root-show
+                        show the root-path of runem and exit (default: False)
+  --silent, --no-silent, -s
+                        Whether to show warning messages or not. (default: False)
+  --spinner, --no-spinner
+                        Whether to show the progress spinner or not. Helps reduce log-spam in ci/cd. (default: True)
+  --verbose, --no-verbose
+                        runs runem in in verbose mode, and streams jobs stdout/stderr to console (default: False)
+  --version, --no-version, -v
+                        show the version of runem and exit (default: False)
+
+jobs:
+  --jobs JOBS [JOBS ...]
+                        List of job-names to run the given jobs. Other filters will modify this list. Defaults to 'dummy job label 1', 'dummy job label 2', 'echo "hello world!"', 'hello world'
+  --not-jobs JOBS_EXCLUDED [JOBS_EXCLUDED ...]
+                        List of job-names to NOT run. Defaults to empty. Available options are: 'dummy job label 1', 'dummy job label 2', 'echo "hello world!"', 'hello world'
+
+phases:
+  --phases PHASES [PHASES ...]
+                        Run only the phases passed in, and can be used to change the phase order. Phases are run in the order given. Defaults to 'dummy phase 1', 'dummy phase 2'.
+  --not-phases PHASES_EXCLUDED [PHASES_EXCLUDED ...]
+                        List of phases to NOT run. This option does not change the phase run order. Options are '['dummy phase 1', 'dummy phase 2']'.
+
+tags:
+  --tags TAGS [TAGS ...]
+                        Only run jobs with the given tags. Defaults to '['dummy tag 1', 'dummy tag 2', 'tag only on job 1', 'tag only on job 2']'.
+  --not-tags TAGS_EXCLUDED [TAGS_EXCLUDED ...]
+                        Removes one or more tags from the list of job tags to be run. Options are '['dummy tag 1', 'dummy tag 2', 'tag only on job 1', 'tag only on job 2']'.
+
+job-param overrides:
+  --dummy-option-1---complete-option, --dummy option 1 multi alias 1, --dummy option 1 multi alias 2, -x, --dummy option alias 1
+                        a dummy option description
+  --no-dummy-option-1---complete-option, --no-dummy option 1 multi alias 1, --no-dummy option 1 multi alias 2, --no-x, --no-dummy option alias 1
+                        turn off a dummy option description
+  --dummy-option-2---minimal
+  --no-dummy-option-2---minimal

tests/data/help_output.3.11.txt

@@ -0,0 +1,55 @@
+runem: WARNING: no phase found for 'echo "hello world!"', using 'dummy phase 1'
+usage: -c [-H] [--jobs JOBS [JOBS ...]] [--not-jobs JOBS_EXCLUDED [JOBS_EXCLUDED ...]] [--phases PHASES [PHASES ...]] [--not-phases PHASES_EXCLUDED [PHASES_EXCLUDED ...]] [--tags TAGS [TAGS ...]] [--not-tags TAGS_EXCLUDED [TAGS_EXCLUDED ...]] [--dummy-option-1---complete-option] [--no-dummy-option-1---complete-option] [--dummy-option-2---minimal] [--no-dummy-option-2---minimal] [--call-graphs | --no-call-graphs] [-f | --modified-files | --no-modified-files] [-h | --git-head-files | --no-git-head-files] [--always-files ALWAYS_FILES [ALWAYS_FILES ...]] [--git-files-since-branch GIT_SINCE_BRANCH] [--procs PROCS] [--root ROOT_DIR] [--root-show | --no-root-show] [--silent | --no-silent | -s] [--spinner | --no-spinner] [--verbose | --no-verbose] [--version | --no-version | -v]
+
+Runs the Lursight Lang test-suite
+
+[TEST_REPLACED_OPTION_HEADER]
+  -H, --help            show this help message and exit
+  --call-graphs, --no-call-graphs
+  -f, --modified-files, --no-modified-files
+                        only use files that have changed
+  -h, --git-head-files, --no-git-head-files
+                        fast run of files
+  --always-files ALWAYS_FILES [ALWAYS_FILES ...]
+                        list of paths/files to always check (overriding -f/-h), if the path matches the filter regex and if file-paths exist
+  --git-files-since-branch GIT_SINCE_BRANCH
+                        Get the list of paths/files changed between a branch, e.g., since 'origin/main'. Useful for checking files changed before pushing.
+  --procs PROCS, -j PROCS
+                        the number of concurrent test jobs to run, -1 runs all test jobs at the same time ([TEST_REPLACED_CORES] cores available)
+  --root ROOT_DIR       which dir to use as the base-dir for testing, defaults to directory containing the config '[TEST_REPLACED_DIR]'
+  --root-show, --no-root-show
+                        show the root-path of runem and exit
+  --silent, --no-silent, -s
+                        Whether to show warning messages or not.
+  --spinner, --no-spinner
+                        Whether to show the progress spinner or not. Helps reduce log-spam in ci/cd.
+  --verbose, --no-verbose
+                        runs runem in in verbose mode, and streams jobs stdout/stderr to console
+  --version, --no-version, -v
+                        show the version of runem and exit
+
+jobs:
+  --jobs JOBS [JOBS ...]
+                        List of job-names to run the given jobs. Other filters will modify this list. Defaults to 'dummy job label 1', 'dummy job label 2', 'echo "hello world!"', 'hello world'
+  --not-jobs JOBS_EXCLUDED [JOBS_EXCLUDED ...]
+                        List of job-names to NOT run. Defaults to empty. Available options are: 'dummy job label 1', 'dummy job label 2', 'echo "hello world!"', 'hello world'
+
+phases:
+  --phases PHASES [PHASES ...]
+                        Run only the phases passed in, and can be used to change the phase order. Phases are run in the order given. Defaults to 'dummy phase 1', 'dummy phase 2'.
+  --not-phases PHASES_EXCLUDED [PHASES_EXCLUDED ...]
+                        List of phases to NOT run. This option does not change the phase run order. Options are '['dummy phase 1', 'dummy phase 2']'.
+
+tags:
+  --tags TAGS [TAGS ...]
+                        Only run jobs with the given tags. Defaults to '['dummy tag 1', 'dummy tag 2', 'tag only on job 1', 'tag only on job 2']'.
+  --not-tags TAGS_EXCLUDED [TAGS_EXCLUDED ...]
+                        Removes one or more tags from the list of job tags to be run. Options are '['dummy tag 1', 'dummy tag 2', 'tag only on job 1', 'tag only on job 2']'.
+
+job-param overrides:
+  --dummy-option-1---complete-option, --dummy option 1 multi alias 1, --dummy option 1 multi alias 2, -x, --dummy option alias 1
+                        a dummy option description
+  --no-dummy-option-1---complete-option, --no-dummy option 1 multi alias 1, --no-dummy option 1 multi alias 2, --no-x, --no-dummy option alias 1
+                        turn off a dummy option description
+  --dummy-option-2---minimal
+  --no-dummy-option-2---minimal