Hesiod API

hesiod.get_cfg_copy() → Dict[str, Any]

Return a copy of the global configuration.

Returns

A copy of the global configuration.

hesiod.get_out_dir() → pathlib.Path

Get the path to the output directory for the current run.

Returns

The path to the output directory.

hesiod.get_run_name() → str

Get the name of the current run.

Raises

ValueError – If the current run has no name. If this happens, something went wrong in the Hesiod protocol. The most likely cause for this error is get_run_name() being called before that a function wrapped in hmain is called.

Returns

The name of the current run.

hesiod.hcfg(name: str, t: Optional[Type[hesiod.core.T]] = None) → hesiod.core.T

Get the requested parameter from the global configuration.

The name argument is used to identify the requested parameter. It can be a composition of keys and subkeys separated by dots (as in key.subkey.subsubkey...), if the requested parameter comes from nested config dictionaries.

The t argument is optional and represents the expected Type of the requested parameter. If given, it allows Hesiod to check that the requested parameter is of the expected type. Furthermore, it enables proper code completion, static type checking and similar stuff.

Parameters

  • name – The name of the required parameter.

  • t – The expected type of the required parameter (optional).

Raises

TypeError – If t is not None and the requested parameter is not of the expected type.

Returns

The requested parameter.

hesiod.hmain(base_cfg_dir: Union[str, pathlib.Path], template_cfg_file: Optional[Union[str, pathlib.Path]] = None, run_cfg_file: Optional[Union[str, pathlib.Path]] = None, create_out_dir: bool = True, out_dir_root: str = 'logs', run_name_strategy: Optional[str] = 'date', parse_cmd_line: bool = True) → Callable[[Callable[[...], Any]], Callable[[...], Any]]

Hesiod decorator for a given function (typically the main).

hmain should be used with only one between run_cfg_file and template_cfg_file. If run_cfg_file is passed, Hesiod will just load the given run file; otherwise, if template_cfg_file is passed, Hesiod will create a Text-based User Interface (TUI) to ask the user to fill/select the values in the given template config. If both run_cfg_file and template_cfg_file are None, then Hesiod will simply create an empty configuration for the current run.

The hmain decorator loads the configuration with the right parser (either using the TUI or not) and runs the decorated function.

Before giving the control back to the decorated function, Hesiod creates a directory named as the run inside out_dir_root and saves the loaded config in a single file in it. This can be disabled with the argument create_out_dir. The default value for out_dir_root is logs.

If the run has no name (either because it is not provided in the run file or it is not inserted by the user in the TUI), Hesiod will try to name it according to the run_name_strategy, if given. run_name_strategy default is “date”, meaning that runs will be named with the date and time formatted as “YYYY-MM-DD-hh-mm-ss”.

By default, Hesiod parses command line arguments to add/override config values. This can be disabled with the argument parse_cmd_line.

Parameters

  • base_cfg_dir – The path to the directory with all the base config files.

  • template_cfg_file – The path to the template config file (optional).

  • run_cfg_file – The path to the run config file created by the user for this run (optional).

  • create_out_dir – A flag that indicates whether hesiod should create an output directory for the run or not (default: True).

  • out_dir_root – The root for output directories (default: “logs”).

  • run_name_strategy – The strategy to assign a default run name if this is not specified by user (available options: “date”, default: “date”).

  • parse_cmd_line – A flag that indicates whether hesiod should parse args from the command line or not (default: True).

Raises

  • ValueError – If hesiod is asked to parse the command line and one of the args is in a not supported format.

  • ValueError – If the run name is not specified in the run file and no default strategy is specified.

Returns

The given function wrapped in hesiod decorator.

hesiod.set_cfg(key: str, value: Any) → None

Set a specific config to the given value.

The given key is expected to be a single config key or a sequence of subkeys separated by dots, as in key.subkey.subsubkey.subsubsubkey.... In the second case, each subkey corresponds to a config dictionary. If the given key (or one of the subkeys) doesn’t exist, Hesiod will create it properly.

Parameters

  • key – The name of the config to be set.

  • value – The value to set.