runem 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

runem/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

runem/command_line.py

@@ -8,7 +8,9 @@ from runem.config_metadata import ConfigMetadata
 from runem.informative_dict import InformativeDict
 from runem.log import error, log
 from runem.runem_version import get_runem_version
-from runem.types import JobNames, OptionConfig, OptionsWritable
+from runem.types.common import JobNames
+from runem.types.options import OptionsWritable
+from runem.types.runem_config import OptionConfig
 from runem.utils import printable_set
 
 

runem/config.py

@@ -7,7 +7,12 @@ from packaging.version import Version
 
 from runem.log import error, log
 from runem.runem_version import get_runem_version
-from runem.types import Config, GlobalConfig, GlobalSerialisedConfig, UserConfigMetadata
+from runem.types.runem_config import (
+    Config,
+    GlobalConfig,
+    GlobalSerialisedConfig,
+    UserConfigMetadata,
+)
 
 CFG_FILE_YAML = pathlib.Path(".runem.yml")
 

runem/config_metadata.py

@@ -3,16 +3,10 @@ import pathlib
 import typing
 
 from runem.informative_dict import InformativeDict
-from runem.types import (
-    JobNames,
-    JobPhases,
-    JobTags,
-    OptionConfigs,
-    OptionsWritable,
-    OrderedPhases,
-    PhaseGroupedJobs,
-    TagFileFilters,
-)
+from runem.types.common import JobNames, JobPhases, JobTags, OrderedPhases
+from runem.types.filters import TagFileFilters
+from runem.types.options import OptionsWritable
+from runem.types.runem_config import OptionConfigs, PhaseGroupedJobs
 
 if typing.TYPE_CHECKING:  # pragma: no cover
     from runem.hook_manager import HookManager

runem/config_parse.py

@@ -10,28 +10,23 @@ from runem.hook_manager import HookManager
 from runem.job import Job
 from runem.job_wrapper import get_job_wrapper
 from runem.log import error, log, warn
-from runem.types import (
+from runem.types.common import JobNames, JobPhases, JobTags, OrderedPhases, PhaseName
+from runem.types.errors import FunctionNotFound
+from runem.types.filters import TagFileFilter, TagFileFilters
+from runem.types.hooks import HookName
+from runem.types.runem_config import (
     Config,
     ConfigNodes,
-    FunctionNotFound,
     GlobalConfig,
     GlobalSerialisedConfig,
     HookConfig,
-    HookName,
     Hooks,
     HookSerialisedConfig,
     JobConfig,
-    JobNames,
-    JobPhases,
     JobSerialisedConfig,
-    JobTags,
     JobWhen,
     OptionConfigs,
-    OrderedPhases,
     PhaseGroupedJobs,
-    PhaseName,
-    TagFileFilter,
-    TagFileFilters,
     TagFileFilterSerialised,
 )
 

runem/files.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from subprocess import check_output as subprocess_check_output
 
 from runem.config_metadata import ConfigMetadata
-from runem.types import FilePathListLookup
+from runem.types.filters import FilePathListLookup
 
 
 def find_files(config_metadata: ConfigMetadata) -> FilePathListLookup:

runem/hook_manager.py

@@ -7,15 +7,10 @@ from runem.config_metadata import ConfigMetadata
 from runem.job import Job
 from runem.job_execute import job_execute
 from runem.log import log
-from runem.types import (
-    FilePathListLookup,
-    HookConfig,
-    HookName,
-    Hooks,
-    HookSpecificKwargs,
-    HooksStore,
-    JobConfig,
-)
+from runem.types.filters import FilePathListLookup
+from runem.types.hooks import HookName
+from runem.types.runem_config import HookConfig, Hooks, HooksStore, JobConfig
+from runem.types.types_jobs import HookSpecificKwargs
 
 
 class HookManager:

runem/job.py

@@ -1,6 +1,8 @@
 import typing
 
-from runem.types import FilePathList, FilePathListLookup, JobConfig, JobTags, JobWhen
+from runem.types.common import FilePathList, JobTags
+from runem.types.filters import FilePathListLookup
+from runem.types.runem_config import JobConfig, JobWhen
 
 
 class NoJobName(ValueError):

runem/job_execute.py

@@ -12,14 +12,15 @@ 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.types import (
-    FilePathList,
-    FilePathListLookup,
+from runem.types.common import FilePathList, JobTags
+from runem.types.filters import FilePathListLookup
+from runem.types.runem_config import JobConfig
+from runem.types.types_jobs import (
+    AllKwargs,
     HookSpecificKwargs,
-    JobConfig,
     JobFunction,
+    JobKwargs,
     JobReturn,
-    JobTags,
     JobTiming,
     TimingEntries,
     TimingEntry,
@@ -80,19 +81,27 @@ def job_execute_inner(
         log(f"job: running: '{Job.get_job_name(job_config)}'")
     reports: JobReturn
     try:
-        assert isinstance(function, JobFunction)
-        reports = function(
-            options=ReadOnlyInformativeDict(config_metadata.options),
-            file_list=file_list,
-            procs=config_metadata.args.procs,
-            root_path=root_path,
-            verbose=config_metadata.args.verbose,
-            # 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,
+        # Define the common args for all jobs and hooks.
+        job_k_args: JobKwargs = {
+            "config_metadata": config_metadata,
+            "file_list": file_list,
+            "job": job_config,
+            "label": Job.get_job_name(job_config),
+            "options": ReadOnlyInformativeDict(config_metadata.options),
+            "procs": config_metadata.args.procs,
+            "record_sub_job_time": _record_sub_job_time,
+            "root_path": root_path,
+            "verbose": config_metadata.args.verbose,
+        }
+        # Merge in the hook-specific kwargs (if any) for situations where we are
+        # calling hooks.
+        all_k_args: AllKwargs = {
+            **job_k_args,
             **kwargs,
-        )
+        }
+
+        assert isinstance(function, JobFunction)
+        reports = function(**all_k_args)
     except BaseException:  # pylint: disable=broad-exception-caught
         # log that we hit an error on this job and re-raise
         log(decorate=False)

runem/job_filter.py

@@ -4,14 +4,8 @@ from collections import defaultdict
 from runem.config_metadata import ConfigMetadata
 from runem.job import Job
 from runem.log import log
-from runem.types import (
-    JobConfig,
-    JobNames,
-    JobPhases,
-    JobTags,
-    PhaseGroupedJobs,
-    PhaseName,
-)
+from runem.types.common import JobNames, JobPhases, JobTags, PhaseName
+from runem.types.runem_config import JobConfig, PhaseGroupedJobs
 from runem.utils import printable_set
 
 

runem/job_runner_simple_command.py

@@ -2,7 +2,7 @@ import shlex
 import typing
 
 from runem.run_command import run_command
-from runem.types import JobConfig
+from runem.types.runem_config import JobConfig
 
 
 def validate_simple_command(command_string: str) -> typing.List[str]:

runem/job_wrapper.py

@@ -5,7 +5,8 @@ from runem.job_runner_simple_command import (
     validate_simple_command,
 )
 from runem.job_wrapper_python import get_job_wrapper_py_func
-from runem.types import JobFunction, JobWrapper
+from runem.types.runem_config import JobWrapper
+from runem.types.types_jobs import JobFunction
 
 
 def get_job_wrapper(job_wrapper: JobWrapper, cfg_filepath: pathlib.Path) -> JobFunction:

runem/job_wrapper_python.py

@@ -3,7 +3,9 @@ import sys
 from importlib.util import module_from_spec
 from importlib.util import spec_from_file_location as module_spec_from_file_location
 
-from runem.types import FunctionNotFound, JobFunction, JobWrapper
+from runem.types.errors import FunctionNotFound
+from runem.types.runem_config import JobWrapper
+from runem.types.types_jobs import JobFunction
 
 
 def _load_python_function_from_module(

runem/report.py

@@ -4,14 +4,13 @@ from collections import defaultdict
 from datetime import timedelta
 
 from runem.log import log
-from runem.types import (
+from runem.types.common import OrderedPhases, PhaseName
+from runem.types.types_jobs import (
     JobReturn,
     JobRunMetadatasByPhase,
     JobRunReportByPhase,
     JobRunTimesByPhase,
     JobTiming,
-    OrderedPhases,
-    PhaseName,
     ReportUrlInfo,
     ReportUrls,
     TimingEntries,

runem/runem.py

@@ -45,18 +45,15 @@ 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.types import (
-    Config,
-    FilePathListLookup,
-    HookName,
+from runem.types.common import OrderedPhases, PhaseName
+from runem.types.filters import FilePathListLookup
+from runem.types.hooks import HookName
+from runem.types.runem_config import Config, Jobs, PhaseGroupedJobs
+from runem.types.types_jobs import (
     JobReturn,
     JobRunMetadata,
     JobRunMetadatasByPhase,
-    Jobs,
     JobTiming,
-    OrderedPhases,
-    PhaseGroupedJobs,
-    PhaseName,
 )
 from runem.utils import printable_set
 

runem/types/__init__.py

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

runem/types/common.py

@@ -0,0 +1,12 @@
+import typing
+
+# meta-data types
+JobName = str
+JobTag = str
+JobNames = typing.Set[JobName]
+JobPhases = typing.Set[str]
+JobTags = typing.Set[JobTag]
+PhaseName = str
+OrderedPhases = typing.Tuple[PhaseName, ...]
+FilePathSerialise = str
+FilePathList = typing.List[FilePathSerialise]

runem/types/errors.py

@@ -0,0 +1,4 @@
+class FunctionNotFound(ValueError):
+    """Thrown when the test-function cannot be found."""
+
+    pass

runem/types/filters.py

@@ -0,0 +1,12 @@
+import typing
+
+from runem.types.common import FilePathList, JobTag
+
+
+class TagFileFilter(typing.TypedDict):
+    tag: JobTag
+    regex: str
+
+
+TagFileFilters = typing.Dict[JobTag, TagFileFilter]
+FilePathListLookup = typing.DefaultDict[JobTag, FilePathList]

runem/types/hooks.py

@@ -0,0 +1,15 @@
+import enum
+
+
+class HookName(enum.Enum):
+    """List supported hooks.
+
+    TODO:
+    - before all tasks are run, after config is read
+    - BEFORE_ALL = "before-all"
+    - after all tasks are done, before reporting
+    - AFTER_ALL = "after-all"
+    """
+
+    # at exit
+    ON_EXIT = "on-exit"

runem/types/options.py

@@ -0,0 +1,7 @@
+from runem.informative_dict import InformativeDict, ReadOnlyInformativeDict
+
+OptionName = str
+OptionValue = bool
+OptionsWritable = InformativeDict[OptionName, OptionValue]
+OptionsReadOnly = ReadOnlyInformativeDict[OptionName, OptionValue]
+Options = OptionsReadOnly

runem/types/runem_config.py

@@ -0,0 +1,164 @@
+import pathlib
+import typing
+
+from runem.types.common import JobName, JobTags, OrderedPhases, PhaseName
+from runem.types.filters import TagFileFilter
+from runem.types.hooks import HookName
+
+
+class OptionConfig(typing.TypedDict, total=False):
+    """Spec for configuring job option overrides."""
+
+    name: str
+    aliases: typing.Optional[typing.List[str]]
+    alias: typing.Optional[str]
+    default: bool
+    type: str
+    desc: typing.Optional[str]
+
+
+OptionConfigs = typing.Tuple[OptionConfig, ...]
+
+
+class OptionConfigSerialised(typing.TypedDict):
+    """Supports better serialisation of options."""
+
+    option: OptionConfig
+
+
+class JobParamConfig(typing.TypedDict):
+    """Configures what parameters are passed to the test-callable.
+
+    FIXME: this isn't actually used at all, yet
+    """
+
+    limitFilesToGroup: bool  # whether to limit file-set for the job
+
+
+class JobAddressConfig(typing.TypedDict):
+    """Configuration which described a callable to call."""
+
+    file: str  # the file-module where 'function' can be found
+    function: str  # the 'function' in module to run
+
+
+class JobContextConfig(typing.TypedDict, total=False):
+    # what parameters the job needs # DEFUNCT
+    params: typing.Optional[JobParamConfig]
+
+    # the path or paths to run the command in. If given a list the job will be
+    # duplicated for each given path.
+    cwd: typing.Optional[typing.Union[str, typing.List[str]]]
+
+
+class JobWhen(typing.TypedDict, total=False):
+    """Configures WHEN to call the callable i.e. priority."""
+
+    tags: JobTags  # the job tags - used for filtering job-types
+    phase: PhaseName  # the phase when the job should be run
+
+
+class JobWrapper(typing.TypedDict, total=False):
+    """A base-type for jobs, hooks, and things that can be invoked."""
+
+    addr: JobAddressConfig  # which callable to call
+    command: str  # a one-liner command to be run
+
+
+class JobConfig(JobWrapper, total=False):
+    """A dict that defines a job to be run.
+
+    It consists of the label, address, context and filter information
+
+    TODO: make a class variant of this
+    """
+
+    label: JobName  # the name of the job
+    ctx: typing.Optional[JobContextConfig]  # how to call the callable
+    when: JobWhen  # when to call the job
+
+
+Jobs = typing.List[JobConfig]
+
+
+class TagFileFilterSerialised(typing.TypedDict):
+    """Supports better serialisation of TagFileFilters."""
+
+    filter: TagFileFilter
+
+
+class GlobalConfig(typing.TypedDict):
+    """The config for the entire test run."""
+
+    # Phases control the order of jobs, jobs earlier in the stack get run earlier
+    # the core ide here is to ensure that certain types of job-dependencies,
+    # such as code-reformatting jobs run before analysis tools, therefore making
+    # any error messages about the code give consistent line numbers e..g if a
+    # re-formatter edits a file the error line will move and the analysis phase
+    # will report the wrong line.
+    phases: OrderedPhases
+
+    # Options control the extra flags that are optionally consumed by job.
+    # Options configured here are used to set command-line-options. All options
+    # and their current state are passed to each job.
+    options: typing.Optional[typing.List[OptionConfigSerialised]]
+
+    # File filters control which files will be passed to jobs for a given tags.
+    # Job will receive the super-set of files for all that job's tags.
+    files: typing.Optional[typing.List[TagFileFilterSerialised]]
+
+    # Which minimal version of runem does this config support?
+    min_version: typing.Optional[str]
+
+
+class GlobalSerialisedConfig(typing.TypedDict):
+    """Intended to make reading a config file easier.
+
+    Unlike JobSerialisedConfig, this type may not actually help readability.
+
+    An intermediary type for serialisation of the global config, the 'global' resides
+    inside a 'global' key and therefore is easier to find and reason about.
+    """
+
+    config: GlobalConfig
+
+
+class HookConfig(JobWrapper, total=False):
+    """Specification for hooks.
+
+    Like JobConfig with use addr or command to specify what to execute.
+    """
+
+    hook_name: HookName  # the hook for when this is called
+
+
+class HookSerialisedConfig(typing.TypedDict):
+    """Intended to make reading a config file easier.
+
+    Also, unlike JobSerialisedConfig, this type may not actually help readability.
+    """
+
+    hook: HookConfig
+
+
+class JobSerialisedConfig(typing.TypedDict):
+    """Makes serialised configs easier to read.
+
+    An intermediary typ for serialisation as each 'job' resides inside a 'job' key.
+
+    This makes formatting of YAML config _significantly_ easier to understand.
+    """
+
+    job: JobConfig
+
+
+ConfigNodes = typing.Union[
+    GlobalSerialisedConfig, JobSerialisedConfig, HookSerialisedConfig
+]
+# The config format as it is serialised to/from disk
+Config = typing.List[ConfigNodes]
+UserConfigMetadata = typing.List[typing.Tuple[Config, pathlib.Path]]
+Hooks = typing.DefaultDict[HookName, typing.List[HookConfig]]
+# A dictionary to hold hooks, with hook names as keys
+HooksStore = typing.Dict[HookName, typing.List[HookConfig]]
+PhaseGroupedJobs = typing.DefaultDict[PhaseName, Jobs]

runem/types/types_jobs.py

@@ -0,0 +1,156 @@
+"""
+
+Some note on Unpack and kwargs:
+    We *try* to strongly type `**kwargs` for clarity.
+    We have tried several ways to define a Generic type that encapsulates
+        `**kwargs: SingleType`
+    ... but none of the solutions worked with python 3.9 -> 3.12 and mypy 1.9.0,
+    so we have to recommend instead using:
+        `**kwargs: Unpack[KwArgsType]`
+
+    For this to work across versions of python where support for Unpack changes;
+    for example `Unpack` is a python 3.12 feature, but available in the
+    `typing_extensions` module.
+
+    So, for now, it looks like we get away with importing `Unpack` from the
+    `typing_extensions` module, even in python 3.12, so we will use, and
+    recommend using, the `typing_extensions` of `Unpack`, until it becomes
+    obsolete.
+
+    Alternatively, we can use the following, but it's unnecessarily verbose.
+
+    if sys.version_info >= (3, 12):  # pragma: no coverage
+        from typing import Unpack
+    else:  # pragma: no coverage
+        from typing_extensions import Unpack
+"""
+
+import pathlib
+import typing
+from datetime import timedelta
+
+from typing_extensions import Unpack
+
+from runem.types.common import FilePathList, PhaseName
+from runem.types.options import Options
+from runem.types.runem_config import JobConfig
+
+if typing.TYPE_CHECKING:  # pragma: no cover
+    from runem.config_metadata import ConfigMetadata
+
+ReportName = str
+ReportUrl = typing.Union[str, pathlib.Path]
+ReportUrlInfo = typing.Tuple[ReportName, ReportUrl]
+ReportUrls = typing.List[ReportUrlInfo]
+
+
+class JobReturnData(typing.TypedDict, total=False):
+    """A dict that defines job result to be reported to the user."""
+
+    reportUrls: ReportUrls  # urls containing reports for the user
+
+
+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]]
+JobRunReportByPhase = typing.Dict[PhaseName, ReportUrls]
+JobRunMetadatasByPhase = typing.Dict[PhaseName, typing.List[JobRunMetadata]]
+
+
+class CommonKwargs(
+    typing.TypedDict,
+    total=True,  # each of these are guaranteed to exist in jobs and hooks
+):
+    """Defines the base args that are passed to all jobs.
+
+    As we call hooks and job-task in the same manner, this defines the variables that we
+    can access from both hooks and job-tasks.
+    """
+
+    config_metadata: "ConfigMetadata"  # gives greater context to jobs and hooks
+    job: JobConfig  # the job or hook task spec ¢ TODO: rename this
+    label: str  # the name of the hook or the job-label
+    options: Options  # options passed in on the command line
+    procs: int  # the max number of concurrent procs to run
+    root_path: pathlib.Path  # the path where the .runem.yml file is
+    verbose: bool  # control log verbosity
+
+
+class HookSpecificKwargs(typing.TypedDict, total=False):
+    """Defines the args that are passed down to the hooks.
+
+    NOTE: that although these however
+     outside of the *hook* context, the data will not be present. Such is the
+     difficulty in dynamic programming.
+    """
+
+    wall_clock_time_saved: timedelta  # only on `HookName.ON_EXIT`
+
+
+class JobTaskKwargs(
+    typing.TypedDict,
+    total=False,  # for now, we don't enforce these types for job-context, but we should.
+):
+    """Defines the task-specific args for job-task functions."""
+
+    file_list: FilePathList
+    record_sub_job_time: typing.Optional[typing.Callable[[str, timedelta], None]]
+
+
+class HookKwargs(CommonKwargs, HookSpecificKwargs):
+    """A merged set of kwargs for runem-hooks."""
+
+    pass
+
+
+class JobKwargs(CommonKwargs, JobTaskKwargs):
+    """A merged set of kwargs for job-tasks."""
+
+    pass
+
+
+class AllKwargs(CommonKwargs, JobTaskKwargs, HookSpecificKwargs):
+    """A merged set of kwargs for al job-functions."""
+
+    pass
+
+
+@typing.runtime_checkable
+class JobFunction(typing.Protocol):
+    def __call__(self, **kwargs: Unpack[AllKwargs]) -> JobReturn:  # pragma: no cover
+        """Defines the call() protocol's abstract pattern for job-tasks."""
+
+    @property
+    def __name__(self) -> str:  # pragma: no cover
+        """Defines the name protocol for job-task functions.
+
+        This is primarily used for internal tests but can be useful for introspection.
+        """
+
+
+def _hook_example(
+    wall_clock_time_saved: timedelta,
+    **kwargs: typing.Any,
+) -> None:
+    """An example hook."""
+
+
+def _job_task_example(
+    **kwargs: Unpack[JobKwargs],
+) -> None:
+    """An example job-task function."""

{runem-0.1.1.dist-info → runem-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: runem
-Version: 0.1.1
+Version: 0.1.2
 Summary: Awesome runem created by lursight
 Home-page: https://github.com/lursight/runem/
 Author: lursight

runem-0.1.2.dist-info/RECORD

@@ -0,0 +1,42 @@
+runem/VERSION,sha256=KXtQ8IOG01Ifj9ry94642dCs30UtLmFZaQX7o3IIx5I,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/cli.py,sha256=wEt_Jnumhl8SiOdKdSJzLkJpWv6n3_Odhi_HeIixr1k,134
+runem/command_line.py,sha256=HsZjxJsVQZLfAeSRI6cpx6P1foeuqCYhHmeQ8Xg9RHY,13774
+runem/config.py,sha256=UiEU0Jyg5qjrNStvasWYjMOABQHhpZjbPiX3-sH_CMg,5969
+runem/config_metadata.py,sha256=krDomUcADsAeUQrxwNmOS58eeaNIlqmhWIKWv8mUH4A,3300
+runem/config_parse.py,sha256=sXPMA8HSUcaJoq0dUfphK181waZqnIrq20mpYOQ_XCo,13498
+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=LmNXDHxDxAwyJxAAdPHIv_0bwZy2btyTPHPGO_N7euI,2986
+runem/job_execute.py,sha256=BPkeTpeTGJs3QWa0-07DZvF1f0uKO79e4yMsTxq1UHk,4656
+runem/job_filter.py,sha256=7vgG4YWJ9gyGBFjV7QbSojG5ofYoszAmxXx9HnMLkHo,5384
+runem/job_runner_simple_command.py,sha256=OIfj7CrPy0fPszhubUsTzORMlMC62OiNSvH5DysYL-4,1104
+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/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_version.py,sha256=MbETwZO2Tb1Y3hX_OYZjKepEMKA1cjNvr-7Cqhz6e3s,271
+runem/utils.py,sha256=3N_kel9LsriiMq7kOjT14XhfxUOgz4hdDg97wlLKm3U,221
+runem/types/__init__.py,sha256=6TzF4KV9tDGuDTr2qAXmWWkfDU52WuVlQ8Hcz48aYDk,286
+runem/types/common.py,sha256=gPMSoJ3yRUYjHnoviRrpSg0gRwsGLFGWGpbTWkq4jX0,279
+runem/types/errors.py,sha256=rbM5BA6UhY1X7Q0OZLUNsG7JXAjgNFTG5KQuqPNuZm8,103
+runem/types/filters.py,sha256=8R5fyMssN0ISGBilJhEtbdHFl6OP7uI51WKkB5SH6EA,255
+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
+tests/test_types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_types/test_public_api.py,sha256=QHiwt7CetQur65JSbFRnOzQxhCJkX5MVLymHHVd_6yc,160
+runem-0.1.2.dist-info/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
+runem-0.1.2.dist-info/METADATA,sha256=UQCyI88PE3lJWibR7VmDFyIGi9xPpnykhp8QKmn9E-U,5842
+runem-0.1.2.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+runem-0.1.2.dist-info/entry_points.txt,sha256=nu0g_vBeuPihYtimbtlNusxWovylMppvJ8UxdJlJfvM,46
+runem-0.1.2.dist-info/top_level.txt,sha256=Zu65aVeDPh8WbChU4Mi7-Md4S3XJDPuqdQjEE3DSQno,12
+runem-0.1.2.dist-info/RECORD,,

{runem-0.1.1.dist-info → runem-0.1.2.dist-info}/top_level.txt

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

tests/test_types/test_public_api.py

@@ -0,0 +1,3 @@
+"""A really noddy file that documents which types are in the public API."""
+
+from runem.types import FilePathList  # noqa: F401 # pylint: disable=unused-import

runem/types.py

@@ -1,357 +0,0 @@
-"""
-
-Some note on Unpack and kwargs:
-    We *try* to strongly type `**kwargs` for clarity.
-    We have tried several ways to define a Generic type that encapsulates
-        `**kwargs: SingleType`
-    ... but none of the solutions worked with python 3.9 -> 3.12 and mypy 1.9.0,
-    so we have to recommend instead using:
-        `**kwargs: Unpack[KwArgsType]`
-
-    For this to work across versions of python where support for Unpack changes;
-    for example `Unpack` is a python 3.12 feature, but available in the
-    `typing_extensions` module.
-
-    So, for now, it looks like we get away with importing `Unpack` from the
-    `typing_extensions` module, even in python 3.12, so we will use, and
-    recommend using, the `typing_extensions` of `Unpack`, until it becomes
-    obsolete.
-
-    Alternatively, we can use the following, but it's unnecessarily verbose.
-
-    if sys.version_info >= (3, 12):  # pragma: no coverage
-        from typing import Unpack
-    else:  # pragma: no coverage
-        from typing_extensions import Unpack
-"""
-
-import pathlib
-import typing
-from datetime import timedelta
-from enum import Enum
-
-from typing_extensions import Unpack
-
-from runem.informative_dict import InformativeDict, ReadOnlyInformativeDict
-
-
-class FunctionNotFound(ValueError):
-    """Thrown when the test-function cannot be found."""
-
-    pass
-
-
-# meta-data types
-JobName = str
-JobTag = str
-JobNames = typing.Set[JobName]
-JobPhases = typing.Set[str]
-JobTags = typing.Set[JobTag]
-PhaseName = str
-OrderedPhases = typing.Tuple[PhaseName, ...]
-ReportName = str
-ReportUrl = typing.Union[str, pathlib.Path]
-ReportUrlInfo = typing.Tuple[ReportName, ReportUrl]
-ReportUrls = typing.List[ReportUrlInfo]
-
-
-class HookName(Enum):
-    # at exit
-    ON_EXIT = "on-exit"
-    # before all tasks are run, after config is read
-    # BEFORE_ALL = "before-all"
-    # after all tasks are done, before reporting
-    # AFTER_ALL = "after-all"
-
-
-class JobReturnData(typing.TypedDict, total=False):
-    """A dict that defines job result to be reported to the user."""
-
-    reportUrls: ReportUrls  # urls containing reports for the user
-
-
-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]]
-JobRunReportByPhase = typing.Dict[PhaseName, ReportUrls]
-JobRunMetadatasByPhase = typing.Dict[PhaseName, typing.List[JobRunMetadata]]
-
-
-class OptionConfig(typing.TypedDict, total=False):
-    """Spec for configuring job option overrides."""
-
-    name: str
-    aliases: typing.Optional[typing.List[str]]
-    alias: typing.Optional[str]
-    default: bool
-    type: str
-    desc: typing.Optional[str]
-
-
-OptionName = str
-OptionValue = bool
-
-OptionConfigs = typing.Tuple[OptionConfig, ...]
-OptionsWritable = InformativeDict[OptionName, OptionValue]
-OptionsReadOnly = ReadOnlyInformativeDict[OptionName, OptionValue]
-Options = OptionsReadOnly
-
-# P1: bool for verbose, P2: list of file paths to work on
-
-
-class TagFileFilter(typing.TypedDict):
-    tag: JobTag
-    regex: str
-
-
-TagFileFilters = typing.Dict[JobTag, TagFileFilter]
-FilePathSerialise = str
-FilePathList = typing.List[FilePathSerialise]
-FilePathListLookup = typing.DefaultDict[JobTag, FilePathList]
-
-
-class JobParamConfig(typing.TypedDict):
-    """Configures what parameters are passed to the test-callable.
-
-    FIXME: this isn't actually used at all, yet
-    """
-
-    limitFilesToGroup: bool  # whether to limit file-set for the job
-
-
-class JobAddressConfig(typing.TypedDict):
-    """Configuration which described a callable to call."""
-
-    file: str  # the file-module where 'function' can be found
-    function: str  # the 'function' in module to run
-
-
-class JobContextConfig(typing.TypedDict, total=False):
-    # what parameters the job needs # DEFUNCT
-    params: typing.Optional[JobParamConfig]
-
-    # the path or paths to run the command in. If given a list the job will be
-    # duplicated for each given path.
-    cwd: typing.Optional[typing.Union[str, typing.List[str]]]
-
-
-class JobWhen(typing.TypedDict, total=False):
-    """Configures WHEN to call the callable i.e. priority."""
-
-    tags: JobTags  # the job tags - used for filtering job-types
-    phase: PhaseName  # the phase when the job should be run
-
-
-class JobWrapper(typing.TypedDict, total=False):
-    """A base-type for jobs, hooks, and things that can be invoked."""
-
-    addr: JobAddressConfig  # which callable to call
-    command: str  # a one-liner command to be run
-
-
-class JobConfig(JobWrapper, total=False):
-    """A dict that defines a job to be run.
-
-    It consists of the label, address, context and filter information
-
-    TODO: make a class variant of this
-    """
-
-    label: JobName  # the name of the job
-    ctx: typing.Optional[JobContextConfig]  # how to call the callable
-    when: JobWhen  # when to call the job
-
-
-Jobs = typing.List[JobConfig]
-
-PhaseGroupedJobs = typing.DefaultDict[PhaseName, Jobs]
-
-
-class OptionConfigSerialised(typing.TypedDict):
-    """Supports better serialisation of options."""
-
-    option: OptionConfig
-
-
-class TagFileFilterSerialised(typing.TypedDict):
-    """Supports better serialisation of TagFileFilters."""
-
-    filter: TagFileFilter
-
-
-class GlobalConfig(typing.TypedDict):
-    """The config for the entire test run."""
-
-    # Phases control the order of jobs, jobs earlier in the stack get run earlier
-    # the core ide here is to ensure that certain types of job-dependencies,
-    # such as code-reformatting jobs run before analysis tools, therefore making
-    # any error messages about the code give consistent line numbers e..g if a
-    # re-formatter edits a file the error line will move and the analysis phase
-    # will report the wrong line.
-    phases: OrderedPhases
-
-    # Options control the extra flags that are optionally consumed by job.
-    # Options configured here are used to set command-line-options. All options
-    # and their current state are passed to each job.
-    options: typing.Optional[typing.List[OptionConfigSerialised]]
-
-    # File filters control which files will be passed to jobs for a given tags.
-    # Job will receive the super-set of files for all that job's tags.
-    files: typing.Optional[typing.List[TagFileFilterSerialised]]
-
-    # Which minimal version of runem does this config support?
-    min_version: typing.Optional[str]
-
-
-class GlobalSerialisedConfig(typing.TypedDict):
-    """Intended to make reading a config file easier.
-
-    Unlike JobSerialisedConfig, this type may not actually help readability.
-
-    An intermediary type for serialisation of the global config, the 'global' resides
-    inside a 'global' key and therefore is easier to find and reason about.
-    """
-
-    config: GlobalConfig
-
-
-class HookConfig(JobWrapper, total=False):
-    """Specification for hooks.
-
-    Like JobConfig with use addr or command to specify what to execute.
-    """
-
-    hook_name: HookName  # the hook for when this is called
-
-
-Hooks = typing.DefaultDict[HookName, typing.List[HookConfig]]
-
-# A dictionary to hold hooks, with hook names as keys
-HooksStore = typing.Dict[HookName, typing.List[HookConfig]]
-
-
-class HookSerialisedConfig(typing.TypedDict):
-    """Intended to make reading a config file easier.
-
-    Also, unlike JobSerialisedConfig, this type may not actually help readability.
-    """
-
-    hook: HookConfig
-
-
-class JobSerialisedConfig(typing.TypedDict):
-    """Makes serialised configs easier to read.
-
-    An intermediary typ for serialisation as each 'job' resides inside a 'job' key.
-
-    This makes formatting of YAML config _significantly_ easier to understand.
-    """
-
-    job: JobConfig
-
-
-ConfigNodes = typing.Union[
-    GlobalSerialisedConfig, JobSerialisedConfig, HookSerialisedConfig
-]
-# The config format as it is serialised to/from disk
-Config = typing.List[ConfigNodes]
-
-UserConfigMetadata = typing.List[typing.Tuple[Config, pathlib.Path]]
-
-
-class CommonKwargs(
-    typing.TypedDict,
-    total=True,  # each of these are guaranteed to exist in jobs and hooks
-):
-    """Defines the base args that are passed to all jobs.
-
-    As we call hooks and job-task in the same manner, this defines the variables that we
-    can access from both hooks and job-tasks.
-    """
-
-    root_path: pathlib.Path  # the path where the .runem.yml file is
-    job: JobConfig  # the job or hook task spec ¢ TODO: rename this
-    label: str  # the name of the hook or the job-label
-    options: Options  # options passed in on the command line
-    procs: int  # the max number of concurrent procs to run
-    verbose: bool  # control log verbosity
-
-
-class HookSpecificKwargs(typing.TypedDict, total=False):
-    """Defines the args that are passed down to the hooks.
-
-    NOTE: that although these however
-     outside of the *hook* context, the data will not be present. Such is the
-     difficulty in dynamic programming.
-    """
-
-    wall_clock_time_saved: timedelta  # only on `HookName.ON_EXIT`
-
-
-class JobTaskKwargs(
-    typing.TypedDict,
-    total=False,  # for now, we don't enforce these types for job-context, but we should.
-):
-    """Defines the task-specific args for job-task functions."""
-
-    file_list: FilePathList
-    record_sub_job_time: typing.Optional[typing.Callable[[str, timedelta], None]]
-
-
-class HookKwargs(CommonKwargs, HookSpecificKwargs):
-    """A merged set of kwargs for runem-hooks."""
-
-    pass
-
-
-class JobKwargs(CommonKwargs, JobTaskKwargs):
-    """A merged set of kwargs for job-tasks."""
-
-    pass
-
-
-class AllKwargs(CommonKwargs, JobTaskKwargs, HookSpecificKwargs):
-    """A merged set of kwargs for al job-functions."""
-
-    pass
-
-
-@typing.runtime_checkable
-class JobFunction(typing.Protocol):
-    def __call__(self, **kwargs: Unpack[AllKwargs]) -> JobReturn:  # pragma: no cover
-        """Defines the call() protocol's abstract pattern for job-tasks."""
-
-    @property
-    def __name__(self) -> str:  # pragma: no cover
-        """Defines the name protocol for job-task functions.
-
-        This is primarily used for internal tests but can be useful for introspection.
-        """
-
-
-def _hook_example(
-    wall_clock_time_saved: timedelta,
-    **kwargs: typing.Any,
-) -> None:
-    """An example hook."""
-
-
-def _job_task_example(
-    **kwargs: Unpack[JobKwargs],
-) -> None:
-    """An example job-task function."""

runem-0.1.1.dist-info/RECORD

@@ -1,33 +0,0 @@
-runem/VERSION,sha256=gERzFlKfxiAU-6oEf7Z8Uaww4ygwzaNwQFNJ2NZtGWw,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/cli.py,sha256=wEt_Jnumhl8SiOdKdSJzLkJpWv6n3_Odhi_HeIixr1k,134
-runem/command_line.py,sha256=mJbs7uUtAxSnbMxO3C08feOkVusK36x_LIQaeJHivzA,13700
-runem/config.py,sha256=y-e6j84FDiLSKKw9ShDzRlnS5t2e81MW8fKSKtxtJtg,5935
-runem/config_metadata.py,sha256=Vy7dx8F-Z5jEp16OP2y6vHHoGkyhoCaTG4KIVkMWR7M,3232
-runem/config_parse.py,sha256=6mCamzWu7HTotmqFJmLZg9FFE6qe1-rpmo8_v5ESPW8,13401
-runem/files.py,sha256=QZqPS7OA98lEwlhJNtnaSWlEeTlI8_yn-zjf3QAPoJk,4384
-runem/hook_manager.py,sha256=8zbMuY4FTSm4kDk2wLBa60zl9NfavnmcOR-qL5jhKTc,4276
-runem/informative_dict.py,sha256=U7p9z78UwOT4TAfng1iDXCEyeYz6C-XZlx9Z1pWNVrI,1548
-runem/job.py,sha256=QVXvzz67fJk__-h0womFQsB80-w41E3XRcHpxmRnv3o,2912
-runem/job_execute.py,sha256=eUyvmtjFdJ49AaIOtqJbRXinkF_UFuz20vBGVrYvt0U,4241
-runem/job_filter.py,sha256=fuxyKCHpTB4HlT_QagBk-IhhmWMlOr9Y9s5voP4yzYU,5370
-runem/job_runner_simple_command.py,sha256=jxBukPm9bTLNhfQCkqNG5VepvB2ysmWAZwhBPHoTA6o,1091
-runem/job_wrapper.py,sha256=H57b52Apcg3q3LyMxus6vNrlv615J4CXiWaQrv8vOgY,936
-runem/job_wrapper_python.py,sha256=m5xbWQxkDRtawjCcgxctzouv_Pny6bKiG2OPVE1hlgo,4226
-runem/log.py,sha256=dIrocigvIJs1ZGkAzTogXkAK-0ZW3q5FkjpDgLdeW-E,630
-runem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-runem/report.py,sha256=IBCtMgGwnvVbEEqDWbYBGUZmTIzBLnpXqYSK5uu3vgk,8987
-runem/run_command.py,sha256=Egl_j4bJ9mwi2JEFCsl0W6WH2IRgIdpMN7qdj8voClQ,6386
-runem/runem.py,sha256=TPBVLiZwEAmKNoQZVHBrrMVgHQfcsJM4uVY9lrrp8X8,13207
-runem/runem_version.py,sha256=MbETwZO2Tb1Y3hX_OYZjKepEMKA1cjNvr-7Cqhz6e3s,271
-runem/types.py,sha256=-RHnskpWEtvqNlrHx3mHrkx6ujEdkCxcU7hu3_lHrJU,10671
-runem/utils.py,sha256=3N_kel9LsriiMq7kOjT14XhfxUOgz4hdDg97wlLKm3U,221
-runem-0.1.1.dist-info/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
-runem-0.1.1.dist-info/METADATA,sha256=Eve8gICbiXMPHxQUUtXqB7hU7Dgjq5Gaq-whnLvzCtk,5842
-runem-0.1.1.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
-runem-0.1.1.dist-info/entry_points.txt,sha256=nu0g_vBeuPihYtimbtlNusxWovylMppvJ8UxdJlJfvM,46
-runem-0.1.1.dist-info/top_level.txt,sha256=gK6iqh9OfHDDpErioCC9ul_zx2Q5zWTALtcuGU7Vil4,6
-runem-0.1.1.dist-info/RECORD,,