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

runem/VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

runem/blocking_print.py

@@ -13,7 +13,14 @@ def _reset_console() -> Console:
 
     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]`.
+        # We allow markup here, BUT stdout/stderr from other procs should have
+        # `escape()` called on them so they don't error here.
+        # This means 'rich' effects/colors can be judiciously applied:
+        # e.g. `[blink]Don't Panic![/blink]`.
+        markup=True,
+        # `highlight` is what colourises string and number in print() calls.
+        # We do not want this to be auto-magic.
+        highlight=False,
     )
     return RICH_CONSOLE
 
@@ -31,7 +38,8 @@ def _reset_console_for_tests() -> None:
     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]`.
+        markup=True,  # Allow some markup e.g. `[blink]Don't Panic![/blink]`.
+        highlight=False,
         width=999,  # A very wide width.
     )
 

runem/log.py

@@ -3,13 +3,32 @@ import typing
 from runem.blocking_print import blocking_print
 
 
-def log(msg: str = "", decorate: bool = True, end: typing.Optional[str] = None) -> None:
+def log(
+    msg: str = "",
+    decorate: bool = True,
+    end: typing.Optional[str] = None,
+) -> None:
     """Thin wrapper around 'print', change the 'msg' & handles system-errors.
 
     One way we change it is to decorate the output with 'runem'
+
+    Parameters:
+        msg: str - the message to log out. Any `rich` markup will be escaped
+                   and not applied.
+        decorate: str - whether to add runem-specific prefix text. We do this
+                        to identify text that comes from the app vs text that
+                        comes from hooks or other third-parties.
+        end: Optional[str] - same as the end option used by `print()` and
+                             `rich`
+    Returns:
+        Nothing
     """
+    # Remove any markup as it will probably error, if unsanitised.
+    # msg = escape(msg)
+
     if decorate:
-        msg = f"runem: {msg}"
+        # Make it clear that the message comes from `runem` internals.
+        msg = f"[light_slate_grey]runem[/light_slate_grey]: {msg}"
 
     # print in a blocking manner, waiting for system resources to free up if a
     # runem job is contending on stdout or similar.
@@ -17,8 +36,8 @@ def log(msg: str = "", decorate: bool = True, end: typing.Optional[str] = None)
 
 
 def warn(msg: str) -> None:
-    log(f"WARNING: {msg}")
+    log(f"[yellow]WARNING[/yellow]: {msg}")
 
 
 def error(msg: str) -> None:
-    log(f"ERROR: {msg}")
+    log(f"[red]ERROR[/red]: {msg}")

runem/report.py

@@ -211,7 +211,10 @@ def _print_reports_by_phase(
         for job_report_url_info in report_urls:
             if not job_report_url_info:
                 continue
-            log(f"report: {str(job_report_url_info[0])}: {str(job_report_url_info[1])}")
+            log(
+                f"report: [blue]{str(job_report_url_info[0])}[/blue]: "
+                f"{str(job_report_url_info[1])}"
+            )
 
 
 def report_on_run(

runem/run_command.py

@@ -7,17 +7,33 @@ from subprocess import STDOUT as SUBPROCESS_STDOUT
 from subprocess import Popen
 from timeit import default_timer as timer
 
+from rich.markup import escape
+
 from runem.log import log
 
 TERMINAL_WIDTH = 86
 
 
-class RunCommandBadExitCode(RuntimeError):
-    pass
+class RunemJobError(RuntimeError):
+    """An exception type that stores the stdout/stderr.
+
+    Designed so that we do not print the full stdout via the exception stack, instead,
+    allows an opportunity to parse the markup in it.
+    """
+
+    def __init__(self, friendly_message: str, stdout: str):
+        self.stdout = stdout
+        super().__init__(friendly_message)
 
 
-class RunCommandUnhandledError(RuntimeError):
-    pass
+class RunCommandBadExitCode(RunemJobError):
+    def __init__(self, stdout: str):
+        super().__init__(friendly_message="Bad exit-code", stdout=stdout)
+
+
+class RunCommandUnhandledError(RunemJobError):
+    def __init__(self, stdout: str):
+        super().__init__(friendly_message="Unhandled job error", stdout=stdout)
 
 
 # A function type for recording timing information.
@@ -27,25 +43,25 @@ RecordSubJobTimeType = typing.Callable[[str, timedelta], None]
 def parse_stdout(stdout: str, prefix: str) -> str:
     """Prefixes each line of the output with a given label, except trailing new
     lines."""
+
     # Edge case: Return the prefix immediately for an empty string
     if not stdout:
         return prefix
 
-    # Split stdout into lines, noting if it ends with a newline
-    ends_with_newline = stdout.endswith("\n")
+    # Stop errors in `rich` by parsing out anything that might look like
+    # rich-markup.
+    stdout = escape(stdout)
+
+    # Split stdout into lines
     lines = stdout.split("\n")
 
     # Apply prefix to all lines except the last if it's empty (due to a trailing newline)
-    modified_lines = [f"{prefix}{line}" for line in lines[:-1]] + (
-        [lines[-1]]
-        if lines[-1] == "" and ends_with_newline
-        else [f"{prefix}{lines[-1]}"]
+    modified_lines = [f"{prefix}{escape(line)}" for line in lines[:-1]] + (
+        [f"{prefix}{escape(lines[-1])}"]
     )
 
     # Join the lines back together, appropriately handling the final newline
-    modified_stdout = "\n".join(modified_lines)
-    # if ends_with_newline:
-    #     modified_stdout += "\n"
+    modified_stdout: str = "\n".join(modified_lines)
 
     return modified_stdout
 
@@ -69,24 +85,34 @@ def _log_command_execution(
     label: str,
     env_overrides: typing.Optional[typing.Dict[str, str]],
     valid_exit_ids: typing.Optional[typing.Tuple[int, ...]],
+    decorate_logs: bool,
     verbose: bool,
     cwd: typing.Optional[pathlib.Path] = None,
 ) -> None:
     """Logs out useful debug information on '--verbose'."""
     if verbose:
-        log(f"running: start: {label}: {cmd_string}")
+        log(
+            f"running: start: [blue]{label}[/blue]: [yellow]{cmd_string}[yellow]",
+            decorate=decorate_logs,
+        )
         if valid_exit_ids is not None:
             valid_exit_strs = ",".join(str(exit_code) for exit_code in valid_exit_ids)
-            log(f"\tallowed return ids are: {valid_exit_strs}")
+            log(
+                f"\tallowed return ids are: [green]{valid_exit_strs}[/green]",
+                decorate=decorate_logs,
+            )
 
         if env_overrides:
             env_overrides_as_string = " ".join(
                 [f"{key}='{value}'" for key, value in env_overrides.items()]
             )
-            log(f"ENV OVERRIDES: {env_overrides_as_string} {cmd_string}")
+            log(
+                f"ENV OVERRIDES: [yellow]{env_overrides_as_string} {cmd_string}[/yellow]",
+                decorate=decorate_logs,
+            )
 
         if cwd:
-            log(f"cwd: {str(cwd)}")
+            log(f"cwd: {str(cwd)}", decorate=decorate_logs)
 
 
 def run_command(  # noqa: C901
@@ -98,6 +124,7 @@ def run_command(  # noqa: C901
     valid_exit_ids: typing.Optional[typing.Tuple[int, ...]] = None,
     cwd: typing.Optional[pathlib.Path] = None,
     record_sub_job_time: typing.Optional[RecordSubJobTimeType] = None,
+    decorate_logs: bool = True,
     **kwargs: typing.Any,
 ) -> str:
     """Runs the given command, returning stdout or throwing on any error."""
@@ -115,6 +142,7 @@ def run_command(  # noqa: C901
         label,
         env_overrides,
         valid_exit_ids,
+        decorate_logs,
         verbose,
         cwd,
     )
@@ -143,7 +171,12 @@ def run_command(  # noqa: C901
                 stdout += line
                 if verbose:
                     # print each line of output, assuming that each has a newline
-                    log(parse_stdout(line, prefix=f"{label}: "))
+                    log(
+                        parse_stdout(
+                            line, prefix=f"[green]| [/green][blue]{label}[/blue]: "
+                        ),
+                        decorate=False,
+                    )
 
             # Wait for the subprocess to finish and get the exit code
             process.wait()
@@ -154,15 +187,15 @@ def run_command(  # noqa: C901
                 )
                 raise RunCommandBadExitCode(
                     (
-                        f"non-zero exit {process.returncode} (allowed are "
-                        f"{valid_exit_strs}) from {cmd_string}"
+                        f"non-zero exit [red]{process.returncode}[/red] (allowed are "
+                        f"[green]{valid_exit_strs}[/green]) from {cmd_string}"
                     )
                 )
     except BaseException as err:
         if ignore_fails:
             return ""
         parsed_stdout: str = (
-            parse_stdout(stdout, prefix=f"{label}: ERROR: ") if process else ""
+            parse_stdout(stdout, prefix="[red]| [/red]") if process else ""
         )
         env_overrides_as_string = ""
         if env_overrides:
@@ -171,11 +204,11 @@ def run_command(  # noqa: C901
             )
             env_overrides_as_string = f"{env_overrides_as_string} "
         error_string = (
-            f"runem: test: FATAL: command failed: {label}"
-            f"\n\t{env_overrides_as_string}{cmd_string}"
-            f"\nERROR"
+            f"runem: [red bold]FATAL[/red bold]: command failed: [blue]{label}[/blue]"
+            f"\n\t[yellow]{env_overrides_as_string}{cmd_string}[/yellow]"
+            f"\n[red underline]| ERROR[/red underline]"
             f"\n{str(parsed_stdout)}"
-            f"\nERROR END"
+            f"\n[red underline]| ERROR END[/red underline]"
         )
 
         if isinstance(err, RunCommandBadExitCode):
@@ -184,7 +217,10 @@ def run_command(  # noqa: C901
         raise RunCommandUnhandledError(error_string) from err
 
     if verbose:
-        log(f"running: done: {label}: {cmd_string}")
+        log(
+            f"running: done: [blue]{label}[/blue]: [yellow]{cmd_string}[/yellow]",
+            decorate=decorate_logs,
+        )
 
     if record_sub_job_time is not None:
         # Capture how long this run took

runem/runem.py

@@ -19,6 +19,7 @@ We do:
 - time tests and tell you what used the most time, and how much time run-tests saved
   you
 """
+import contextlib
 import multiprocessing
 import os
 import pathlib
@@ -30,10 +31,9 @@ from datetime import timedelta
 from itertools import repeat
 from multiprocessing.managers import DictProxy, ValueProxy
 from timeit import default_timer as timer
-from types import TracebackType
 
-from rich.console import Console, ConsoleOptions, ConsoleRenderable, RenderResult
 from rich.spinner import Spinner
+from rich.status import Status
 from rich.text import Text
 
 from runem.blocking_print import RICH_CONSOLE
@@ -46,6 +46,7 @@ from runem.job_execute import job_execute
 from runem.job_filter import filter_jobs
 from runem.log import error, log, warn
 from runem.report import report_on_run
+from runem.run_command import RunemJobError
 from runem.types.common import OrderedPhases, PhaseName
 from runem.types.filters import FilePathListLookup
 from runem.types.hooks import HookName
@@ -56,7 +57,7 @@ from runem.types.types_jobs import (
     JobRunMetadatasByPhase,
     JobTiming,
 )
-from runem.utils import printable_set
+from runem.utils import printable_set_coloured
 
 
 def _determine_run_parameters(argv: typing.List[str]) -> ConfigMetadata:
@@ -92,38 +93,8 @@ def _determine_run_parameters(argv: typing.List[str]) -> ConfigMetadata:
     return config_metadata
 
 
-class DummySpinner(ConsoleRenderable):  # pragma: no cover
-    """A dummy spinner for when spinners are disabled."""
-
-    def __init__(self) -> None:
-        self.text = ""
-
-    def __rich__(self) -> Text:
-        """Return a rich Text object for rendering."""
-        return Text(self.text)
-
-    def __rich_console__(
-        self, console: Console, options: ConsoleOptions
-    ) -> RenderResult:
-        """Yield an empty string or placeholder text."""
-        yield Text(self.text)
-
-    def __enter__(self) -> None:
-        """Support for context manager."""
-        pass
-
-    def __exit__(
-        self,
-        exc_type: typing.Optional[typing.Type[BaseException]],
-        exc_value: typing.Optional[BaseException],
-        traceback: typing.Optional[TracebackType],
-    ) -> None:
-        """Support for context manager."""
-        pass
-
-
 def _update_progress(
-    label: str,
+    phase: str,
     running_jobs: typing.Dict[str, str],
     completed_jobs: typing.Dict[str, str],
     all_jobs: Jobs,
@@ -140,30 +111,36 @@ def _update_progress(
         is_running (ValueProxy[bool]): Flag indicating if jobs are still running.
         num_workers (int): Indicates the number of workers performing the jobs.
     """
-    # Using the `rich` module to show a loading spinner on console
-    spinner: typing.Union[Spinner, DummySpinner]
-    if show_spinner:
-        spinner = Spinner("dots", text="Starting tasks...")
-    else:
-        spinner = DummySpinner()
 
     last_running_jobs_set: typing.Set[str] = set()
 
-    with RICH_CONSOLE.status(spinner):
+    # Using the `rich` module to show a loading spinner on console
+    spinner_ctx: typing.Union[Status, typing.ContextManager[None]] = (
+        RICH_CONSOLE.status(Spinner("dots", text="Starting tasks..."))
+        if show_spinner
+        else contextlib.nullcontext()
+    )
+
+    with spinner_ctx:
         while is_running.value:
             running_jobs_set: typing.Set[str] = set(running_jobs.values())
 
             # Progress report
             progress: str = f"{len(completed_jobs)}/{len(all_jobs)}"
-            running_jobs_list = printable_set(
-                running_jobs_set
+            running_jobs_list = printable_set_coloured(
+                running_jobs_set,
+                "blue",
             )  # Reflect current running jobs accurately
-            report: str = f"{label}: {progress}({num_workers}): {running_jobs_list}"
+            report: str = (
+                f"[green]{phase}[/green]: {progress}({num_workers}): {running_jobs_list}"
+            )
             if show_spinner:
-                spinner.text = report
+                assert isinstance(spinner_ctx, Status)
+                spinner_ctx.update(Text.from_markup(report))
             else:
                 if last_running_jobs_set != running_jobs_set:
                     RICH_CONSOLE.log(report)
+                    last_running_jobs_set = running_jobs_set
 
             # Sleep for reduced CPU usage
             time.sleep(0.1)
@@ -176,7 +153,7 @@ def _process_jobs(
     phase: PhaseName,
     jobs: Jobs,
     show_spinner: bool,
-) -> typing.Optional[BaseException]:
+) -> typing.Optional[RunemJobError]:
     """Execute each given job asynchronously.
 
     This is where the major real-world time savings happen, and it could be
@@ -196,12 +173,12 @@ def _process_jobs(
     num_concurrent_procs: int = min(max_num_concurrent_procs, len(jobs))
     log(
         (
-            f"Running '{phase}' with {num_concurrent_procs} workers (of "
+            f"Running '[green]{phase}[/green]' with {num_concurrent_procs} workers (of "
             f"{max_num_concurrent_procs} max) processing {len(jobs)} jobs"
         )
     )
 
-    subprocess_error: typing.Optional[BaseException] = None
+    subprocess_error: typing.Optional[RunemJobError] = None
 
     with multiprocessing.Manager() as manager:
         running_jobs: DictProxy[typing.Any, typing.Any] = manager.dict()
@@ -235,7 +212,7 @@ def _process_jobs(
                         repeat(file_lists),
                     ),
                 )
-        except BaseException as err:  # pylint: disable=broad-exception-caught
+        except RunemJobError as err:  # pylint: disable=broad-exception-caught
             subprocess_error = err
         finally:
             # Signal the terminal_writer process to exit
@@ -251,7 +228,7 @@ def _process_jobs_by_phase(
     filtered_jobs_by_phase: PhaseGroupedJobs,
     in_out_job_run_metadatas: JobRunMetadatasByPhase,
     show_spinner: bool,
-) -> typing.Optional[BaseException]:
+) -> typing.Optional[RunemJobError]:
     """Execute each job asynchronously, grouped by phase.
 
     Whilst it is conceptually useful to group jobs by 'phase', Phases are
@@ -275,7 +252,7 @@ def _process_jobs_by_phase(
         if config_metadata.args.verbose:
             log(f"Running Phase {phase}")
 
-        failure_exception: typing.Optional[BaseException] = _process_jobs(
+        failure_exception: typing.Optional[RunemJobError] = _process_jobs(
             config_metadata,
             file_lists,
             in_out_job_run_metadatas,
@@ -293,7 +270,7 @@ def _process_jobs_by_phase(
 
 
 MainReturnType = typing.Tuple[
-    ConfigMetadata, JobRunMetadatasByPhase, typing.Optional[BaseException]
+    ConfigMetadata, JobRunMetadatasByPhase, typing.Optional[RunemJobError]
 ]
 
 
@@ -333,7 +310,7 @@ def _main(
 
     start = timer()
 
-    failure_exception: typing.Optional[BaseException] = _process_jobs_by_phase(
+    failure_exception: typing.Optional[RunemJobError] = _process_jobs_by_phase(
         config_metadata,
         file_lists,
         filtered_jobs_by_phase,
@@ -362,7 +339,7 @@ def timed_main(argv: typing.List[str]) -> None:
     start = timer()
     config_metadata: ConfigMetadata
     job_run_metadatas: JobRunMetadatasByPhase
-    failure_exception: typing.Optional[BaseException]
+    failure_exception: typing.Optional[RunemJobError]
     config_metadata, job_run_metadatas, failure_exception = _main(argv)
     phase_run_oder: OrderedPhases = config_metadata.phases
     end = timer()
@@ -372,14 +349,15 @@ def timed_main(argv: typing.List[str]) -> None:
     system_time_spent, wall_clock_time_saved = report_on_run(
         phase_run_oder, job_run_metadatas, time_taken
     )
-    message: str = "DONE: runem took"
+    message: str = "[green bold]DONE[/green bold]: runem took"
     if failure_exception:
-        message = "FAILED: your jobs failed after"
+        message = "[red bold]FAILED[/red bold]: your jobs failed after"
     log(
         (
             f"{message}: {time_taken.total_seconds()}s, "
-            f"saving you {wall_clock_time_saved.total_seconds()}s, "
-            f"without runem you would have waited {system_time_spent.total_seconds()}s"
+            f"saving you [green]{wall_clock_time_saved.total_seconds()}s[/green], "
+            "without runem you would have waited "
+            f"[red]{system_time_spent.total_seconds()}s[/red]"
         )
     )
 
@@ -392,6 +370,7 @@ def timed_main(argv: typing.List[str]) -> None:
     if failure_exception is not None:
         # we got a failure somewhere, now that we've reported the timings we
         # re-raise.
+        error(failure_exception.stdout)
         raise failure_exception
 
 

runem/types/__init__.py

@@ -1,11 +1,12 @@
 from runem.types.common import FilePathList, JobName
 from runem.types.options import Options
-from runem.types.types_jobs import HookKwargs, JobKwargs, JobReturnData
+from runem.types.types_jobs import HookKwargs, JobKwargs, JobReturn, JobReturnData
 
 __all__ = [
     "FilePathList",
     "HookKwargs",
     "JobName",
+    "JobReturn",
     "JobReturnData",
     "Options",
     "JobKwargs",

runem/utils.py

@@ -4,3 +4,15 @@ import typing
 def printable_set(some_set: typing.Set[typing.Any]) -> str:
     """Get a printable, deterministic string version of a set."""
     return ", ".join([f"'{set_item}'" for set_item in sorted(list(some_set))])
+
+
+def printable_set_coloured(some_set: typing.Set[typing.Any], colour: str) -> str:
+    """`printable_set` but elements are surrounded with colour mark-up.
+
+    Parameters:
+        some_set: a set of anything
+        colour: a `rich` Console supported colour
+    """
+    return ", ".join(
+        [f"'[{colour}]{set_item}[/{colour}]'" for set_item in sorted(list(some_set))]
+    )

runem-0.6.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.2
+Name: runem
+Version: 0.6.0
+Summary: Awesome runem created by lursight
+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>=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"
+Requires-Dist: docformatter==1.7.5; extra == "tests"
+Requires-Dist: flake8-bugbear==24.2.6; extra == "tests"
+Requires-Dist: flake8==7.0.0; extra == "tests"
+Requires-Dist: gitchangelog==3.0.4; extra == "tests"
+Requires-Dist: isort==5.13.2; extra == "tests"
+Requires-Dist: mkdocs==1.5.3; extra == "tests"
+Requires-Dist: mypy==1.9.0; extra == "tests"
+Requires-Dist: pydocstyle==6.3.0; extra == "tests"
+Requires-Dist: pylint==3.1.0; extra == "tests"
+Requires-Dist: pylama==8.4.1; extra == "tests"
+Requires-Dist: pytest-cov==6.0.0; extra == "tests"
+Requires-Dist: pytest-profiling==1.7.0; extra == "tests"
+Requires-Dist: pytest-xdist==3.6.1; extra == "tests"
+Requires-Dist: pytest==8.3.3; extra == "tests"
+Requires-Dist: setuptools; extra == "tests"
+Requires-Dist: termplotlib==0.3.9; extra == "tests"
+Requires-Dist: tox; extra == "tests"
+Requires-Dist: types-PyYAML==6.0.12.20240311; extra == "tests"
+Requires-Dist: requests-mock==1.11.0; extra == "tests"
+Requires-Dist: types-setuptools; extra == "tests"
+
+<!-- [![codecov](https://codecov.io/gh/lursight/runem/branch/main/graph/badge.svg?token=run-test_token_here)](https://codecov.io/gh/lursight/runem) -->
+[![CI](https://github.com/lursight/runem/actions/workflows/main.yml/badge.svg)](https://github.com/lursight/runem/actions/workflows/main.yml)
+[![DOCS](https://lursight.github.io/runem/docs/VIEW-DOCS-31c553.svg)](https://lursight.github.io/runem/)
+
+# Run’em
+
+**Your Blueprint of Commands. Your Engine of Parallel Execution.**
+Run’em is your definitive blueprint of tasks and commands—instantly discoverable, effortlessly parallel, and elegantly extensible.
+
+## Core Strengths
+
+**Blueprint** - discover tasks and onboard smoothly\
+**Parallel**  - get results quicker\
+**Simple**  - define task easily\
+**Extensible** - add tasks quickly\
+**Filters** - powerful task selection\
+**Reports** - see metrics on tasks
+
+## Why Run’em?
+- **Command Blueprint:** Instantly see and run all your tasks. No guesswork, no rummaging.
+- **Effortless Parallelism:** Execute tasks side-by-side to obliterate downtime.
+- **Simple YAML Declarations:** Define everything in one `.runem.yml`.
+- **Extensible & Smart:** Adapt to monorepos, complex workflows, and evolving needs.
+- **Discoverable by Design:** `runem --help` guides your team, new hires, or contributors to every defined command.
+
+## Contents
+- [Run’em](#runem)
+  - [Core Strengths](#core-strengths)
+  - [Why Run’em?](#why-runem)
+  - [Contents](#contents)
+- [Highlights](#highlights)
+- [Quick Start](#quick-start)
+- [Basic Use](#basic-use)
+- [Advanced Use](#advanced-use)
+- [Help & Discovery](#help--discovery)
+- [Troubleshooting](#troubleshooting)
+- [Contribute & Support](#contribute--support)
+- [About Run’em](#about-runem)
+
+# Highlights
+## Blueprint of Commands:
+The blueprint (available via `--help`) gives you a manifest of all jobs and tasks in a
+project. A single source of truth for all tasks.
+## Parallel Execution:
+Maximise speed with automatic concurrency. Runem tries to run all tasks as quickly as
+possible, looking at resources, with dependencies. It is not yet a full
+dependency-execution graph, but by version 1.0.0 it will be.
+## Filtering:
+Use powerful and flexible filtering. Select or excluded tasks by `tags`, `name` and
+`phase`. Chose the task to be run based on your needs, right now.
+
+You can also customise filtering by adding your own command `options`.
+
+See `--tags`, `--not-tags`, `--jobs`, `--not-jobs`, `--phases` and `--not-phases`.
+## Powerful Insights:** Understand what ran, how fast, and what failed.
+**Quiet by Default:** Focus on what matters, and reveal detail only when needed.
+
+# Quick Start
+**Install:**
+```bash
+pip install runem
+```
+**Define a task:**
+
+```yaml
+`# .runem.yml
+ - job:
+    command: echo "hello world!"
+```
+
+**Run:**
+
+```bash
+runem
+```
+
+Run multiple commands in parallel, see timing, and keep output minimal. Need detail?
+
+```bash
+runem --verbose
+```
+
+[Quick Start Docs](https://lursight.github.io/runem/docs/quick_start.html)
+
+# Basic Use
+
+Get comfortable with typical workflows:
+[Basic Use Docs](https://lursight.github.io/runem/docs/basic_use.html)
+
+# Advanced Use
+
+Scale up with multi-phase configs, filtered execution, and custom reporting:
+[Advanced Configuration](https://lursight.github.io/runem/docs/configuration.html)
+[Custom Reporting](https://lursight.github.io/runem/docs/reports.html)
+
+# Help & Discovery
+
+`runem --help` is your radar—instantly mapping out every available task:
+[Help & Job Discovery](https://lursight.github.io/runem/docs/help_and_job_discovery.html)
+
+# Troubleshooting
+
+Swift solutions to common issues:
+[Troubleshooting & Known Issues](https://lursight.github.io/runem/docs/troubleshooting_known_issues.html)
+
+---
+
+# Contribute & Support
+
+Brought to you by [Lursight Ltd.](https://lursight.com) and an open community.
+[CONTRIBUTING.md](CONTRIBUTING.md)
+[❤️ Sponsor](https://github.com/sponsors/lursight/)
+
+# About Run’em
+
+Run’em exists to accelerate your team’s delivery and reduce complexity. Learn about our [Mission](https://lursight.github.io/runem/docs/mission.html).
+

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

@@ -1,8 +1,8 @@
-runem/VERSION,sha256=oK1QZAE5pST4ZZEVcUW_HUZ06pwGW_6iFVjw97BEMMg,6
+runem/VERSION,sha256=l6XW5UCmEg0Jw53bZn4Ojiusf8wv_vgTuC4I_WA2W84,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=R3c3HSnRMPCf7ykDXdKG2hKH4CzbBaxmOfP3xEU_wEI,1919
+runem/blocking_print.py,sha256=2nCvc10zXl1DRJldkruKthKjfmZKErcmxQzt3pjmN-c,2289
 runem/cli.py,sha256=wEt_Jnumhl8SiOdKdSJzLkJpWv6n3_Odhi_HeIixr1k,134
 runem/command_line.py,sha256=qkZFCCq9hUl6RO398SJzoigv8di5jGw2sdNwgTVBdd8,14474
 runem/config.py,sha256=UiEU0Jyg5qjrNStvasWYjMOABQHhpZjbPiX3-sH_CMg,5969
@@ -17,15 +17,15 @@ 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
 runem/job_wrapper_python.py,sha256=rx7J_N-JXs8GgMq7Sla7B9s_ZAfofKUhEnzgMcq_bts,4303
-runem/log.py,sha256=dIrocigvIJs1ZGkAzTogXkAK-0ZW3q5FkjpDgLdeW-E,630
+runem/log.py,sha256=6r6HIJyvp19P6PZNo93qdIxE0SpTAsY4ELrETBl1dC4,1363
 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=9QZgmXNPXOscRRLWDgOcPZ0lYRcG7jOog1M_o3MXZbs,13667
+runem/report.py,sha256=beye95AV9Lop_K7eOoLY40vKt0VGkIdg-ig-SmJ_5MY,9083
+runem/run_command.py,sha256=R77jqAtrXPBkFtT7QXJfnQkivU4h01M8G0Q2sjWY6Gs,7691
+runem/runem.py,sha256=6XZqf59_ZMyrBaK1FlaLzMXYNoDQsTUcbFqTbpZL1ik,13192
 runem/runem_version.py,sha256=MbETwZO2Tb1Y3hX_OYZjKepEMKA1cjNvr-7Cqhz6e3s,271
-runem/utils.py,sha256=3N_kel9LsriiMq7kOjT14XhfxUOgz4hdDg97wlLKm3U,221
+runem/utils.py,sha256=MEYfox09rLvb6xmay_3rV1cWmdqMbhaAjOomYGNk15k,602
 runem/cli/initialise_options.py,sha256=zx_EduWQk7yGBr3XUNrffHCSInPv05edFItHLnlo9dk,918
-runem/types/__init__.py,sha256=6TzF4KV9tDGuDTr2qAXmWWkfDU52WuVlQ8Hcz48aYDk,286
+runem/types/__init__.py,sha256=0bWG7hE7VeqJ2oIu-xhrqQud8hcNp6WNbF3uMfT_n9g,314
 runem/types/common.py,sha256=gPMSoJ3yRUYjHnoviRrpSg0gRwsGLFGWGpbTWkq4jX0,279
 runem/types/errors.py,sha256=rbM5BA6UhY1X7Q0OZLUNsG7JXAjgNFTG5KQuqPNuZm8,103
 runem/types/filters.py,sha256=8R5fyMssN0ISGBilJhEtbdHFl6OP7uI51WKkB5SH6EA,255
@@ -44,9 +44,9 @@ tests/data/help_output.3.10.txt,sha256=5TUpNITVL6pD5BpFAl-Orh3vkOpStveijZzvgJuI_
 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.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.6.0.dist-info/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
+runem-0.6.0.dist-info/METADATA,sha256=00_gsiXfiHPCwcZumnmOU2KjaUTvR6kF9c9nr4p2YHc,5892
+runem-0.6.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+runem-0.6.0.dist-info/entry_points.txt,sha256=nu0g_vBeuPihYtimbtlNusxWovylMppvJ8UxdJlJfvM,46
+runem-0.6.0.dist-info/top_level.txt,sha256=NkdxkwLKNNhxItveR2KqNqTshTZ268m5D7SjJEmG4-Y,20
+runem-0.6.0.dist-info/RECORD,,

{runem-0.5.0.dist-info → runem-0.6.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

runem-0.5.0.dist-info/METADATA

@@ -1,164 +0,0 @@
-Metadata-Version: 2.1
-Name: runem
-Version: 0.5.0
-Summary: Awesome runem created by lursight
-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>=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"
-Requires-Dist: docformatter==1.7.5; extra == "tests"
-Requires-Dist: flake8-bugbear==24.2.6; extra == "tests"
-Requires-Dist: flake8==7.0.0; extra == "tests"
-Requires-Dist: gitchangelog==3.0.4; extra == "tests"
-Requires-Dist: isort==5.13.2; extra == "tests"
-Requires-Dist: mkdocs==1.5.3; extra == "tests"
-Requires-Dist: mypy==1.9.0; extra == "tests"
-Requires-Dist: pydocstyle==6.3.0; extra == "tests"
-Requires-Dist: pylint==3.1.0; extra == "tests"
-Requires-Dist: pylama==8.4.1; extra == "tests"
-Requires-Dist: pytest-cov==6.0.0; extra == "tests"
-Requires-Dist: pytest-profiling==1.7.0; extra == "tests"
-Requires-Dist: pytest-xdist==3.6.1; extra == "tests"
-Requires-Dist: pytest==8.3.3; extra == "tests"
-Requires-Dist: setuptools; extra == "tests"
-Requires-Dist: termplotlib==0.3.9; extra == "tests"
-Requires-Dist: tox; extra == "tests"
-Requires-Dist: types-PyYAML==6.0.12.20240311; extra == "tests"
-Requires-Dist: requests-mock==1.11.0; extra == "tests"
-Requires-Dist: types-setuptools; extra == "tests"
-
-<!-- [![codecov](https://codecov.io/gh/lursight/runem/branch/main/graph/badge.svg?token=run-test_token_here)](https://codecov.io/gh/lursight/runem) -->
-[![CI](https://github.com/lursight/runem/actions/workflows/main.yml/badge.svg)](https://github.com/lursight/runem/actions/workflows/main.yml)
-[![DOCS](https://lursight.github.io/runem/docs/VIEW-DOCS-31c553.svg)](https://lursight.github.io/runem/)
-
-# Run'em: Accelerate Your Development Workflow
-**Boost Efficiency and Save Time**
-Runem is a flexible, multi-process tool designed to speed up your everyday tasks by running them in parallel. Whether you're testing, linting, or deploying, runem helps you work smarter and faster.
-
-## Why Choose Run'em?
-- **Streamlined Task Management**: Configure tasks with ease using declarative .runem.yml files.
-- **Multiprocess Execution**: Run multiple tasks simultaneously, minimizing wall-clock time.
-- **Optimized for Monorepos**: Supports multiple projects and task types, with easy filtering and configuration.
-- **Detailed Reporting**: Get insights into task execution time and efficiency gains.
-
-## Contents
-- [Run'em: Accelerate Your Development Workflow](#runem-accelerate-your-development-workflow)
-  - [Why Choose Run'em?](#why-choose-runem)
-  - [Contents](#contents)
-- [Features At A Glance:](#features-at-a-glance)
-- [Using Run'em](#using-runem)
-  - [Installation](#installation)
-  - [Quick-start](#quick-start)
-  - [Basic quick-start](#basic-quick-start)
-    - [A more complete quick-start](#a-more-complete-quick-start)
-  - [Basic Use](#basic-use)
-  - [Advanced Use](#advanced-use)
-    - [Advanced configuration options](#advanced-configuration-options)
-    - [Custom reports](#custom-reports)
-- [Help and job discovery](#help-and-job-discovery)
-- [Troubleshooting](#troubleshooting)
-- [Contributing to and supporting runem](#contributing-to-and-supporting-runem)
-  - [Development](#development)
-  - [Sponsor](#sponsor)
-- [About runem](#about-runem)
-
-
-# Features At A Glance:
-- **Tagging**: Easily run specific job groups (e.g., lint, test, python).
-- **Phases**: Organize tasks by phase (e.g., edit, test, deploy).
-- **Configurable Options**: Customize how jobs are executed using simple options.
-- **Declarative**: Jobs are define using simple YAML in [.runem.yml](https://lursight.github.io/runem/docs/configuration.html) .
-
-# Using Run'em
-
-## Installation
-
-```bash
-pip install runem
-```
-
-## Quick-start
-
-## Basic quick-start
-Create the following `.runem.yml` file at the root of your project:
-
-```yml
-- job:
-    command: echo "hello world!"
-```
-
-Then anywhere in your project run `runem` to see how and when that task is run, and how long it took:
-```bash
-runem
-```
-
-To see the actual log output you will need to use `--verbose` as `runem` hides anything that isn't important. Only failures and reports are considered important.
-```bash
-# Or, to see "hello world!", use --verbose
-runem --verbose  # add --verbose to see the actual output
-```
-
-To see how you can control your job use `--help`:
-```bash
-runem --help
-```
-
-### A more complete quick-start
-
-See [quick-start docs](https://lursight.github.io/runem/docs/quick_start.html) for more quick-start tips.
-
-## Basic Use
-
-See [docs on basic use and use-cases](https://lursight.github.io/runem/docs/basic_use.html) for a comprehensive introduction.
-
-## Advanced Use
-
-### Advanced configuration options
-See [configuration docs](https://lursight.github.io/runem/docs/configuration.html) for advanced configuration and use.
-
-### Custom reports
-See [reporting docs](https://lursight.github.io/runem/docs/reports.html) for more information on how reporting works.
-
-
-# Help and job discovery
-
-`--help` is designed to help your team discover what jobs and tasks they can automated. Read more at 
-[help and discovery docs](https://lursight.github.io/runem/docs/help_and_job_discovery.html).
-
-# Troubleshooting
-
-See [troubleshooting and known issues docs](https://lursight.github.io/runem/docs/troubleshooting_known_issues.html).
-
----
-# Contributing to and supporting runem
-
-Awesome runem created by lursight
-
-## Development
-
-Read the [CONTRIBUTING.md](CONTRIBUTING.md) file.
-
-## Sponsor
-
-[❤️ Sponsor this project](https://github.com/sponsors/lursight/)
-
-# About runem
-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).
-