mpylab.env.script_cli module

Shared command-line helpers for the MSC measurement scripts.

class mpylab.env.script_cli.ConfigChange(path: tuple[str | int, ...], operation: str)

Bases: object

One value changed while resolving a configuration chain.

Parameters:

  • path (tuple of str or int) – Location inside the effective configuration.

  • operation ({"added", "changed", "removed"}) – Kind of change made by the source.

operation: str
path: tuple[str | int, ...]
exception mpylab.env.script_cli.ConfigError

Bases: Exception

Raised when a command-line configuration cannot be loaded.

class mpylab.env.script_cli.ConfigSourceTrace(name: str, kind: str, changes: tuple[ConfigChange, ...])

Bases: object

Changes attributed to one configuration source.

Parameters:

  • name (str) – Human-readable source name.

  • kind (str) – Source category such as "script", "file", or "literal".

  • changes (tuple of ConfigChange) – Effective changes made by this source.

changes: tuple[ConfigChange, ...]
kind: str
name: str
class mpylab.env.script_cli.ConfigTrace(sources: tuple[ConfigSourceTrace, ...])

Bases: object

Ordered provenance of an effective measurement configuration.

Parameters:

sources (tuple of ConfigSourceTrace) – Sources in the order in which they were applied.

source_for(path)

Return the last source that changed a configuration path.

Parameters:

path (sequence of str or int) – Location inside the effective configuration.

Returns:

Source name, or None when no source can be attributed.

Return type:

str or None

sources: tuple[ConfigSourceTrace, ...]
mpylab.env.script_cli.build_parser(script_name=None)

Create the common parser used by text-based measurement scripts.

Parameters:

script_name (str or None, optional) – Program name shown in command-line help.

Returns:

Parser accepting zero or more configuration overrides.

Return type:

argparse.ArgumentParser

mpylab.env.script_cli.load_config_module(name)

Load a configuration module from a file path or module name.

Parameters:

name (str or path-like) – Python filename or importable module name.

Returns:

Loaded configuration module.

Return type:

module

mpylab.env.script_cli.merge_config(config, override)

Recursively merge a configuration override into a configuration.

Nested dictionaries are merged recursively. All other values, including lists and tuples, replace the existing value. Replacement values are deep copied so a later update_config hook cannot mutate the imported configuration module.

Parameters:

  • config (dict) – Configuration updated in place.

  • override (dict) – Configuration values to merge.

Returns:

The updated config mapping.

Return type:

dict

Raises:

TypeError – If config or override is not a dictionary.

mpylab.env.script_cli.resolve_autosave_resume(measurement, command, expected_measurement, expected_method)

Validate autosave restart metadata and return its description.

Structured autosave_resume metadata is preferred. Older pickles remain usable when autosave_info identifies the measurement or ascmd calls the expected public measurement method.

Parameters:

  • measurement (object) – Restored measurement instance containing restart metadata.

  • command (str or None) – Legacy ascmd restart command.

  • expected_measurement (str) – Expected measurement identifier.

  • expected_method (str) – Expected public measurement method name.

Returns:

Measurement description stored in the autosave metadata.

Return type:

str or None

Raises:

ValueError – If restart metadata is inconsistent, unsupported, or does not match the expected measurement method.

mpylab.env.script_cli.resolve_config_chain(cdict, argv=None, script_name=None, base_source=None)

Update a configuration and return its ordered source provenance.

Configuration arguments are applied from left to right. Nested dictionaries from cdict are merged recursively; all other values are replaced. A configuration module may additionally or alternatively define update_config(config) for targeted in-place updates. The hook runs after the module’s cdict and must return None.

Parameters:

  • cdict (dict) – Configuration mapping to update in place.

  • argv (sequence of str or None, optional) – Command-line arguments. None uses sys.argv.

  • script_name (str or None, optional) – Program name shown in command-line help.

  • base_source (str or None, optional) – Name attributed to values already present in cdict. If omitted, those values are not included as a separate trace source.

Returns:

Ordered sources and the effective paths changed by each source.

Return type:

ConfigTrace

Raises:

ConfigError – If a configuration source or its update hook is invalid.

mpylab.env.script_cli.update_conf(cdict, argv=None, script_name=None)

Update a configuration from defaults and ordered overrides.

Configuration arguments are applied from left to right. Nested dictionaries from cdict are merged recursively; all other values are replaced. A configuration module may additionally or alternatively define update_config(config) for targeted in-place updates. The hook runs after the module’s cdict and must return None.

This compatibility entry point intentionally returns None. Use resolve_config_chain() when source provenance is required.

Parameters:

  • cdict (dict) – Configuration mapping to update in place.

  • argv (sequence of str or None, optional) – Command-line arguments. None uses sys.argv.

  • script_name (str or None, optional) – Program name shown in command-line help.

Raises:

ConfigError – If a configuration source or its update hook is invalid.