runem 0.0.28__tar.gz → 0.0.29__tar.gz

{runem-0.0.28 → runem-0.0.29}/HISTORY.md

@@ -4,6 +4,113 @@ Changelog
 
 (unreleased)
 ------------
+- Merge pull request #40 from lursight/fix/time_saved. [Frank Harrison]
+
+  Fix/time saved
+- Feat(prettier-bars): clarifies that total is user-space time. [Frank
+  Harrison]
+
+  ... not wall-clock or system-time
+- Feat(prettier-bars): distiguishes the wall-clock bars. [Frank
+  Harrison]
+
+  ... from the total/sum and sub-job bars, so that it's slightly easier to
+  see where the time is being really spent.
+- Fix(time-saved): clarifies which measurement is the wall-clock time
+  for the entire run. [Frank Harrison]
+- Fix(time-saved): add message about how long we _would_ have waited
+  without runem. [Frank Harrison]
+- Fix(time-saved): renames all variable associated with timing reports.
+  [Frank Harrison]
+
+  This just makes someting which can become intractable/confusing a lot
+  easier to follow.
+- Fix(time-saved): check that time-saved is reported correctly. [Frank
+  Harrison]
+
+  Here we add a test first and then fix the missing math to calculate the
+  time-saved by using runem. We broke this in the previous feature for
+  rendering the tree slightly more elegantly.
+- Feat(hide-single-leafs): only show the job when it has a single child.
+  [Frank Harrison]
+
+  We would get duplicated information for jobs which had single
+  run_command invocations. This only shows sub-tasks/jobs if there are
+  more than one sub-tasks meaning the output looks a lot nicer & clearer.
+- Chore(deps): adds setuptools as a explicit dep. [Frank Harrison]
+
+  ... otherwise we get the following error (more often in python 3.12),
+  perhaps due to setuptools being removed from distros?:
+
+  ```text
+  Traceback (most recent call last):
+    File "/var/www/mydir/virtualenvs/dev/bin/pip", line 5, in <module>
+      from pkg_resources import load_entry_point
+  ImportError: No module named pkg_resources
+  ```
+- Merge pull request #39 from lursight/feat/time_all_run_command_calls.
+  [Frank Harrison]
+
+  Feat/time all run command calls
+- Feat(pretty-tree): refactors out the phase-job report generator.
+  [Frank Harrison]
+
+  This is just to make pylint happy.
+- Feat(pretty-tree): makes the report tree neater. [Frank Harrison]
+- Feat(time-all-sub-tasks): re-raise errors for context in ci/cd. [Frank
+  Harrison]
+
+  In github ci/cd we were hitting the asserts but had no context of where
+  they're raised from or why. This should fix that if they still occur.
+- Feat(time-all-sub-tasks): adds a test to test the time-recording
+  functions. [Frank Harrison]
+- Feat(time-all-sub-tasks): adds all run_command times to report output.
+  [Frank Harrison]
+- Chore(type): uses a type-alias instead of manual type. [Frank
+  Harrison]
+- Merge pull request #37 from
+  lursight/dependabot/github_actions/actions/upload-artifact-4. [Frank
+  Harrison]
+
+  chore(deps): bump actions/upload-artifact from 3 to 4
+- Chore(deps): bump actions/upload-artifact from 3 to 4.
+  [dependabot[bot]]
+
+  Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 3 to 4.
+  - [Release notes](https://github.com/actions/upload-artifact/releases)
+  - [Commits](https://github.com/actions/upload-artifact/compare/v3...v4)
+
+  ---
+  updated-dependencies:
+  - dependency-name: actions/upload-artifact
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Merge pull request #36 from lursight/chore/more_python_versions_in_ci.
+  [Frank Harrison]
+
+  Chore/more python versions in ci
+- Chore(github-ci): workaround for python 3.12 setuptools issue. [Frank
+  Harrison]
+
+  This fies what looks like an issue with pytest hooks running ci/cd (and
+  on local machine) where we get:
+    ModuleNotFoundError: No module named 'pkg_resources'
+- Chore(github-ci): updates the python `--help` tests for 3.11 (and
+  later) [Frank Harrison]
+- Chore(github-ci): test python 3.9, 3.11 and 3.12 in ci. [Frank
+  Harrison]
+
+  We don't bother with 3.10 because we test 3.9 and boundaries for
+  features are on the 3.11 version.
+
+  We don't bother with earlier than 3.9, even though 3.8 is the earliest
+  officially supported version.
+
+
+0.0.28 (2024-03-01)
+-------------------
+- Release: version 0.0.28 🚀 [Frank Harrison]
 - Merge pull request #35 from lursight/fix/aliases_not_setting_options.
   [Frank Harrison]
 

{runem-0.0.28 → runem-0.0.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: runem
-Version: 0.0.28
+Version: 0.0.29
 Summary: Awesome runem created by lursight
 Home-page: https://github.com/lursight/runem/
 Author: lursight
@@ -26,6 +26,7 @@ Requires-Dist: pytest-cov==4.1.0; extra == "test"
 Requires-Dist: pytest-profiling==1.7.0; extra == "test"
 Requires-Dist: pytest-xdist==3.3.1; extra == "test"
 Requires-Dist: pytest==7.4.3; extra == "test"
+Requires-Dist: setuptools; extra == "test"
 Requires-Dist: termplotlib==0.3.9; extra == "test"
 Requires-Dist: types-PyYAML==6.0.12.12; extra == "test"
 Requires-Dist: requests-mock==1.10.0; extra == "test"
@@ -400,12 +401,12 @@ runem: reports:
 runem: runem: 8.820488s
 runem: ├runem.pre-build: 0.019031s
 runem: ├runem.run-phases: 8.801317s
-runem: ├pre-run (total): 0.00498s
+runem: ├pre-run (user-time): 0.00498s
 runem: │├pre-run.install python requirements: 2.6e-05s
 runem: │├pre-run.ls -alh runem: 0.004954s
-runem: ├edit (total): 0.557559s
+runem: ├edit (user-time): 0.557559s
 runem: │├edit.reformat py: 0.557559s
-runem: ├analysis (total): 21.526145s
+runem: ├analysis (user-time): 21.526145s
 runem: │├analysis.pylint py: 7.457029s
 runem: │├analysis.flake8 py: 0.693754s
 runem: │├analysis.mypy py: 1.071956s
@@ -430,12 +431,12 @@ runem: reports:
 runem                                  [14.174612]  ███████████████▋
 ├runem.pre-build                       [ 0.025858]
 ├runem.run-phases                      [14.148587]  ███████████████▋
-├pre-run (total)                       [ 0.005825]
+├pre-run (user-time)                   [ 0.005825]
 │├pre-run.install python requirements  [ 0.000028]
 │├pre-run.ls -alh runem                [ 0.005797]
-├edit (total)                          [ 0.579153]  ▋
+├edit (user-time)                      [ 0.579153]  ▋
 │├edit.reformat py                     [ 0.579153]  ▋
-├analysis (total)                      [36.231034]  ████████████████████████████████████████
+├analysis (user-time)                  [36.231034]  ████████████████████████████████████████
 │├analysis.pylint py                   [12.738303]  ██████████████▏
 │├analysis.flake8 py                   [ 0.798575]  ▉
 │├analysis.mypy py                     [ 0.335984]  ▍

{runem-0.0.28 → runem-0.0.29}/README.md

@@ -367,12 +367,12 @@ runem: reports:
 runem: runem: 8.820488s
 runem: ├runem.pre-build: 0.019031s
 runem: ├runem.run-phases: 8.801317s
-runem: ├pre-run (total): 0.00498s
+runem: ├pre-run (user-time): 0.00498s
 runem: │├pre-run.install python requirements: 2.6e-05s
 runem: │├pre-run.ls -alh runem: 0.004954s
-runem: ├edit (total): 0.557559s
+runem: ├edit (user-time): 0.557559s
 runem: │├edit.reformat py: 0.557559s
-runem: ├analysis (total): 21.526145s
+runem: ├analysis (user-time): 21.526145s
 runem: │├analysis.pylint py: 7.457029s
 runem: │├analysis.flake8 py: 0.693754s
 runem: │├analysis.mypy py: 1.071956s
@@ -397,12 +397,12 @@ runem: reports:
 runem                                  [14.174612]  ███████████████▋
 ├runem.pre-build                       [ 0.025858]
 ├runem.run-phases                      [14.148587]  ███████████████▋
-├pre-run (total)                       [ 0.005825]
+├pre-run (user-time)                   [ 0.005825]
 │├pre-run.install python requirements  [ 0.000028]
 │├pre-run.ls -alh runem                [ 0.005797]
-├edit (total)                          [ 0.579153]  ▋
+├edit (user-time)                      [ 0.579153]  ▋
 │├edit.reformat py                     [ 0.579153]  ▋
-├analysis (total)                      [36.231034]  ████████████████████████████████████████
+├analysis (user-time)                  [36.231034]  ████████████████████████████████████████
 │├analysis.pylint py                   [12.738303]  ██████████████▏
 │├analysis.flake8 py                   [ 0.798575]  ▉
 │├analysis.mypy py                     [ 0.335984]  ▍

runem-0.0.29/runem/VERSION

@@ -0,0 +1 @@
+0.0.29

{runem-0.0.28 → runem-0.0.29}/runem/job_execute.py

@@ -11,14 +11,23 @@ from runem.informative_dict import ReadOnlyInformativeDict
 from runem.job import Job
 from runem.job_wrapper import get_job_wrapper
 from runem.log import log
-from runem.types import FilePathListLookup, JobConfig, JobFunction, JobReturn, JobTags
+from runem.types import (
+    FilePathListLookup,
+    JobConfig,
+    JobFunction,
+    JobReturn,
+    JobTags,
+    JobTiming,
+    TimingEntries,
+    TimingEntry,
+)
 
 
 def job_execute_inner(
     job_config: JobConfig,
     config_metadata: ConfigMetadata,
     file_lists: FilePathListLookup,
-) -> typing.Tuple[typing.Tuple[str, timedelta], JobReturn]:
+) -> typing.Tuple[JobTiming, JobReturn]:
     """Wrapper for running a job inside a sub-process.
 
     Returns the time information and any reports the job generated
@@ -38,7 +47,19 @@ def job_execute_inner(
     if not file_list:
         # no files to work on
         log(f"WARNING: skipping job '{label}', no files for job")
-        return (f"{label}: no files!", timedelta(0)), None
+        return {
+            "job": (f"{label}: no files!", timedelta(0)),
+            "commands": [],
+        }, None
+
+    sub_command_timings: TimingEntries = []
+
+    def _record_sub_job_time(label: str, timing: timedelta) -> None:
+        """Record timing information for sub-commands/tasks, atomically.
+
+        For example inside of run_command() calls
+        """
+        sub_command_timings.append((label, timing))
 
     if (
         "ctx" in job_config
@@ -71,6 +92,7 @@ def job_execute_inner(
                 # unpack useful data points from the job_config
                 label=Job.get_job_name(job_config),
                 job=job_config,
+                record_sub_job_time=_record_sub_job_time,
             )
     except BaseException:  # pylint: disable=broad-exception-caught
         # log that we hit an error on this job and re-raise
@@ -83,8 +105,8 @@ def job_execute_inner(
     time_taken: timedelta = timedelta(seconds=end - start)
     if config_metadata.args.verbose:
         log(f"job: DONE: '{label}': {time_taken}")
-    timing_data = (label, time_taken)
-    return (timing_data, reports)
+    this_job_timing_data: TimingEntry = (label, time_taken)
+    return ({"job": this_job_timing_data, "commands": sub_command_timings}, reports)
 
 
 def job_execute(
@@ -92,7 +114,7 @@ def job_execute(
     running_jobs: typing.Dict[str, str],
     config_metadata: ConfigMetadata,
     file_lists: FilePathListLookup,
-) -> typing.Tuple[typing.Tuple[str, timedelta], JobReturn]:
+) -> typing.Tuple[JobTiming, JobReturn]:
     """Thin-wrapper around job_execute_inner needed for mocking in tests.
 
     Needed for faster tests.

runem-0.0.29/runem/report.py

@@ -0,0 +1,252 @@
+import re
+import typing
+from collections import defaultdict
+from datetime import timedelta
+
+from runem.log import log
+from runem.types import (
+    JobReturn,
+    JobRunMetadatasByPhase,
+    JobRunReportByPhase,
+    JobRunTimesByPhase,
+    JobTiming,
+    OrderedPhases,
+    PhaseName,
+    ReportUrlInfo,
+    ReportUrls,
+    TimingEntries,
+)
+
+try:
+    import termplotlib
+except ImportError:  # pragma: FIXME: add code coverage
+    termplotlib = None
+
+
+def _align_bar_graphs_workaround(original_text: str) -> str:
+    """Module termplotlib doesn't align floats, this fixes that.
+
+    This makes it so we can align the point in the floating point string, without it,
+    larger numbers push their bars right, instead of at the same place.
+    """
+    # Find the maximum width between '[' and '.' characters
+    max_width = max(
+        int(match.end() - match.start() - 2)
+        for match in re.finditer(r"\[.*?(\d+)\.", original_text)
+    )
+
+    # Replace each line with aligned numbers
+    formatted_text = re.sub(
+        r"\[.*?(\d+)\.", lambda m: f"[{m.group(1):>{max_width}}.", original_text
+    )
+
+    return formatted_text
+
+
+def _replace_bar_characters(text: str, end_str: str, replace_char: str) -> str:
+    """Replaces block characters in lines containing `end_str` with give char.
+
+    Args:
+        text_lines (List[str]): A list of strings, each representing a line of text.
+        replace_char (str): The character to replace all bocks with
+
+    Returns:
+        List[str]: The modified list of strings with block characters replaced
+                   on specified lines.
+    """
+    # Define the block character and its light shade replacement
+    block_chars = (
+        "▏▎▋▊█▌▐▄▀─"  # Extend this string with any additional block characters you use
+    )
+
+    text_lines: typing.List[str] = text.split("\n")
+
+    # Process each line, replacing block characters if `end_str` is present
+    modified_lines = [
+        line.translate(str.maketrans(block_chars, replace_char * len(block_chars)))
+        if end_str in line
+        else line
+        for line in text_lines
+    ]
+
+    return "\n".join(modified_lines)
+
+
+def _semi_shade_phase_totals(text: str) -> str:
+    light_shade_char = "░"
+    return _replace_bar_characters(text, "(user-time)", light_shade_char)
+
+
+def _dot_jobs(text: str) -> str:
+    dot_char = "·"
+    return _replace_bar_characters(text, "(+)", dot_char)
+
+
+def _plot_times(
+    wall_clock_for_runem_main: timedelta,
+    phase_run_oder: OrderedPhases,
+    timing_data: JobRunTimesByPhase,
+) -> typing.Tuple[timedelta, timedelta]:
+    """Prints a report to terminal on how well we performed.
+
+    Also calculates the wall-clock time-saved for the user.
+
+    Returns the total system time spent and the time-saved.     (system-time-spent,
+    wall-clock-time-saved)
+    """
+    labels: typing.List[str] = []
+    times: typing.List[float] = []
+
+    # Track active processing time for jobs, distinct from wall-clock time (the
+    # time the user experiences).
+    system_time_spent: timedelta = timedelta()  # init to 0
+
+    for idx, phase in enumerate(phase_run_oder):
+        not_last_phase: bool = idx < len(phase_run_oder) - 1
+        utf8_phase = "├" if not_last_phase else "└"
+        utf8_phase_group = "│" if not_last_phase else " "
+        # log(f"Phase '{phase}' jobs took:")
+        phase_start_idx = len(labels)
+
+        phase_job_times: timedelta = _gen_jobs_report(
+            phase,
+            labels,
+            times,
+            utf8_phase_group,
+            timing_data[phase],
+        )
+        labels.insert(phase_start_idx, f"{utf8_phase}{phase} (user-time)")
+        times.insert(phase_start_idx, phase_job_times.total_seconds())
+        system_time_spent += phase_job_times
+
+    runem_app_timing: typing.List[JobTiming] = timing_data["_app"]
+    job_metadata: JobTiming
+    for job_metadata in reversed(runem_app_timing):
+        job_label, job_time_total = job_metadata["job"]
+        labels.insert(0, f"├runem.{job_label}")
+        times.insert(0, job_time_total.total_seconds())
+    labels.insert(0, "runem (total wall-clock)")
+    times.insert(0, wall_clock_for_runem_main.total_seconds())
+    if termplotlib:
+        fig = termplotlib.figure()
+        # cspell:disable-next-line
+        fig.barh(
+            times,
+            labels,
+            force_ascii=False,
+        )
+        shaded_bar_graph: str = _semi_shade_phase_totals(fig.get_string())
+        dotted_bar_graph: str = _dot_jobs(shaded_bar_graph)
+
+        # ensure the graphs get aligned nicely.
+        final_bar_graph: str = _align_bar_graphs_workaround(dotted_bar_graph)
+        print(final_bar_graph)
+    else:  # pragma: FIXME: add code coverage
+        for job_label, time in zip(labels, times):
+            log(f"{job_label}: {time}s")
+
+    wall_clock_time_saved: timedelta = system_time_spent - wall_clock_for_runem_main
+    return system_time_spent, wall_clock_time_saved
+
+
+def _gen_jobs_report(
+    phase: PhaseName,
+    labels: typing.List[str],
+    times: typing.List[float],
+    utf8_phase_group: str,
+    job_timings: typing.List[JobTiming],
+) -> timedelta:
+    """Gathers the reports for sub-jobs.
+
+    Split out from _plot_times as the code was getting complex
+    """
+    job_timing: JobTiming
+
+    # Filter out JobTiming instances with non-zero total_seconds
+    non_zero_timing_data: typing.List[JobTiming] = [
+        job_timing
+        for job_timing in job_timings
+        if job_timing["job"][1].total_seconds() != 0
+    ]
+
+    job_time_sum: timedelta = timedelta()  # init to 0
+    for idx, job_timing in enumerate(non_zero_timing_data):
+        not_last: bool = idx < len(non_zero_timing_data) - 1
+        utf8_job = "├" if not_last else "└"
+        utf8_sub_jobs = "│" if not_last else " "
+        job_label, job_time_total = job_timing["job"]
+        job_bar_label: str = f"{phase}.{job_label}"
+        labels.append(f"{utf8_phase_group}{utf8_job}{job_bar_label}")
+        times.append(job_time_total.total_seconds())
+        job_time_sum += job_time_total
+        sub_command_times: TimingEntries = job_timing["commands"]
+
+        if len(sub_command_times) <= 1:
+            # we only have one or fewer sub-commands, just show the job-time
+            continue
+
+        # also print the sub-components of the job as we have more than one
+        for idx, (sub_job_label, sub_job_time) in enumerate(sub_command_times):
+            sub_utf8 = "├"
+            if idx == len(sub_command_times) - 1:
+                sub_utf8 = "└"
+            labels.append(
+                f"{utf8_phase_group}{utf8_sub_jobs}{sub_utf8}{job_bar_label}"
+                f".{sub_job_label} (+)"
+            )
+            times.append(sub_job_time.total_seconds())
+    return job_time_sum
+
+
+def _print_reports_by_phase(
+    phase_run_oder: OrderedPhases, report_data: JobRunReportByPhase
+) -> None:
+    """Logs out the reports by grouped by phase."""
+    for phase in phase_run_oder:
+        report_urls: ReportUrls = report_data[phase]
+        job_report_url_info: ReportUrlInfo
+        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])}")
+
+
+def report_on_run(
+    phase_run_oder: OrderedPhases,
+    job_run_metadatas: JobRunMetadatasByPhase,
+    wall_clock_for_runem_main: timedelta,
+) -> typing.Tuple[timedelta, timedelta]:
+    """Generate high-level reports AND prints out any reports returned by jobs.
+
+    IMPORTANT: returns the wall-clock time saved to the user.
+    """
+    log("reports:")
+
+    # First, collate all data, timing and reports
+    timing_data: JobRunTimesByPhase = defaultdict(list)
+    report_data: JobRunReportByPhase = defaultdict(list)
+    phase: PhaseName
+    for phase in job_run_metadatas:
+        timing: JobTiming
+        reports: JobReturn
+        for timing, reports in job_run_metadatas[phase]:
+            timing_data[phase].append(timing)
+            if reports:
+                # the job returned some report urls, record them against the
+                # job's phase
+                report_data[phase].extend(reports["reportUrls"])
+
+    # Now plot the times on the terminal to give a visual report of the timing.
+    time_metrics: typing.Tuple[timedelta, timedelta] = _plot_times(
+        wall_clock_for_runem_main=wall_clock_for_runem_main,
+        phase_run_oder=phase_run_oder,
+        timing_data=timing_data,
+    )
+
+    # Penultimate-ly print out the available reports grouped by run-phase.
+    _print_reports_by_phase(phase_run_oder, report_data)
+
+    # Return the key metrics for runem, the system vs wall-clock time saved to
+    # the user
+    # TODO: write this to disk
+    return time_metrics

{runem-0.0.28 → runem-0.0.29}/runem/run_command.py

@@ -1,9 +1,11 @@
 import os
 import pathlib
 import typing
+from datetime import timedelta
 from subprocess import PIPE as SUBPROCESS_PIPE
 from subprocess import STDOUT as SUBPROCESS_STDOUT
 from subprocess import Popen
+from timeit import default_timer as timer
 
 from runem.log import log
 
@@ -18,6 +20,10 @@ class RunCommandUnhandledError(RuntimeError):
     pass
 
 
+# A function type for recording timing information.
+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."""
@@ -91,11 +97,16 @@ def run_command(  # noqa: C901
     ignore_fails: bool = False,
     valid_exit_ids: typing.Optional[typing.Tuple[int, ...]] = None,
     cwd: typing.Optional[pathlib.Path] = None,
+    record_sub_job_time: typing.Optional[RecordSubJobTimeType] = None,
     **kwargs: typing.Any,
 ) -> str:
     """Runs the given command, returning stdout or throwing on any error."""
     cmd_string = " ".join(cmd)
 
+    if record_sub_job_time is not None:
+        # start the capture of how long this sub-task takes.
+        start = timer()
+
     run_env: typing.Dict[str, str] = _prepare_environment(
         env_overrides,
     )
@@ -174,4 +185,11 @@ def run_command(  # noqa: C901
 
     if verbose:
         log(f"running: done: {label}: {cmd_string}")
+
+    if record_sub_job_time is not None:
+        # Capture how long this run took
+        end = timer()
+        time_taken: timedelta = timedelta(seconds=end - start)
+        record_sub_job_time(label, time_taken)
+
     return stdout

{runem-0.0.28 → runem-0.0.29}/runem/runem.py

@@ -297,9 +297,11 @@ def _main(
     end = timer()
 
     job_run_metadatas: JobRunMetadatasByPhase = defaultdict(list)
-    job_run_metadatas["_app"].append(
-        (("pre-build", (timedelta(seconds=end - start))), None)
-    )
+    pre_build_time: JobTiming = {
+        "job": ("pre-build", (timedelta(seconds=end - start))),
+        "commands": [],
+    }
+    job_run_metadatas["_app"].append((pre_build_time, None))
 
     start = timer()
 
@@ -313,7 +315,10 @@ def _main(
 
     end = timer()
 
-    phase_run_timing: JobTiming = ("run-phases", timedelta(seconds=end - start))
+    phase_run_timing: JobTiming = {
+        "job": ("run-phases", timedelta(seconds=end - start)),
+        "commands": [],
+    }
     phase_run_report: JobReturn = None
     phase_run_metadata: JobRunMetadata = (phase_run_timing, phase_run_report)
     job_run_metadatas["_app"].append(phase_run_metadata)
@@ -333,14 +338,19 @@ def timed_main(argv: typing.List[str]) -> None:
     phase_run_oder, job_run_metadatas, failure_exception = _main(argv)
     end = timer()
     time_taken: timedelta = timedelta(seconds=end - start)
-    time_saved = report_on_run(phase_run_oder, job_run_metadatas, time_taken)
+    wall_clock_time_saved: timedelta
+    system_time_spent: timedelta
+    system_time_spent, wall_clock_time_saved = report_on_run(
+        phase_run_oder, job_run_metadatas, time_taken
+    )
     message: str = "DONE: runem took"
     if failure_exception:
         message = "FAILED: your jobs failed after"
     log(
         (
             f"{message}: {time_taken.total_seconds()}s, "
-            f"saving you {time_saved.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"
         )
     )
 

{runem-0.0.28 → runem-0.0.29}/runem/types.py

@@ -32,7 +32,21 @@ class JobReturnData(typing.TypedDict, total=False):
     reportUrls: ReportUrls  # urls containing reports for the user
 
 
-JobTiming = typing.Tuple[str, timedelta]
+TimingEntry = typing.Tuple[str, timedelta]
+TimingEntries = typing.List[TimingEntry]
+
+
+class JobTiming(typing.TypedDict, total=True):
+    """A hierarchy of timing info. Job->JobCommands.
+
+    The overall time for a job is in 'job', the child calls to run_command are in
+    'commands'
+    """
+
+    job: TimingEntry  # the overall time for a job
+    commands: TimingEntries  # timing for each call to `run_command`
+
+
 JobReturn = typing.Optional[JobReturnData]
 JobRunMetadata = typing.Tuple[JobTiming, JobReturn]
 JobRunTimesByPhase = typing.Dict[PhaseName, typing.List[JobTiming]]