Configuration file I/O

Module to read and write HADDOCK3 configuration files.

HADDOCK3 user configuration files follow TOML syntax plus additional features required for HADDOCK3. Therefore, we have implemented our own TOML-like parser to accommodate the extra features needed for HADDOCK3. However, HADDOCK3 can also read pure TOML files.

The most relevant features of HADDOCK3 user configuration files are the hability to prepare TOML-like files but with repeated header names, for example:

[topoaa]
# parameters here...

[rigidbody]
# parameters here...

[caprieval]
# parameters here...

[flexref]
# parameters here...

[caprieval]
# parameters here...

From the user perspective, everything else just behaves as in TOML. Actually, HADDOCK3 uses TOML to finally read the configuration files. Users can also provide pure TOML compatible files, for example:

[topoaa]
# parameters here...

[rigidbody]
# parameters here...

[caprieval]
# parameters here...

[flexref]
# parameters here...

['caprieval.1']
# parameters here...

Because HADDOCK3 uses TOML in the end to read the configuration files, all TOML rules apply regarding defining parameter = value pairs.

Read more about TOML for Python here: https://pypi.org/project/toml/

exception haddock.gear.config.ConfigFormatError[source]

Bases: Exception

Exception if there is a format error.

haddock.gear.config.convert_to_path(value: str | Path) → Path | EmptyPath[source]

Convert a variable to Path if variable evaluates to true.

haddock.gear.config.convert_variables_to_paths(cfg: ParamMapT) → ParamMapT[source]

Convert config variables to paths.

Applies only to those variables HADDOCK3 needs as paths.

Parameters:

  • cfg (dictionary) – A dictionary containing the HADDOCK3 parameters.

  • .. see-also:: – match_path_criteria()

haddock.gear.config.get_module_name(name: str) → str[source]

Get the module name according to the config parser.

Get the name without the integer suffix.

haddock.gear.config.load(fpath: str | Path) → dict[str, Any][source]

Load an HADDOCK3 configuration file to a dictionary.

Accepts HADDOCK3 cfg files or pure toml files.

Parameters:

fpath (str or pathlib.Path) – Path to user configuration file.

Returns:

  • dictionary – Representing the user configuration file where first level of keys are the module names. Step keys will have a numeric suffix, for example: module.1.

  • .. see-also:: –

haddock.gear.config.loads(cfg_str: str) → dict[str, Any][source]

Read a string representing a config file to a dictionary.

Config strings are converted to toml-compatible format and finally read by the toml library.

All headers (dictionary keys) will be suffixed by an integer starting at 1. For example: topoaa.1. If the key is repeated, 2 is appended, and so forth. Even if specific integers are provided by the user, the suffix integers will be normalized.

Parameters:

cfg_str (str) – The string representing the config file. Accepted formats are the HADDOCK3 config file or pure toml syntax.

Returns:

all_configs (dict) – A dictionary holding all the configuration file steps:

  • ’raw_input’: Original input file as provided by user.

  • ’cleaned_input’: Regex cleaned input file.

  • ’loaded_cleaned_input’: Dict of toml loaded cleaned input.

  • ’final_cfg’: The config in the form of a dictionary. In which the order of the keys matters as it defines the order of the steps in the workflow.

haddock.gear.config.match_path_criteria(param: str) → bool[source]

Confirm a parameter should be converted to path.

This function contains the rules defining which parameter need to be converted to Path before be sent to HADDOCK3.

haddock.gear.config.save(params: MutableMapping[str, Any], path: str | Path, pure_toml: bool = False) → None[source]

Write a dictionary to a HADDOCK3 config file.

Write the HADDOCK3 parameter dictionary to a .cfg file. There is also the option to write in pure TOML format. Both are compatible with HADDOCK3.

Parameters:

  • params (dict) – The dictionary containing the parameters.

  • path (str or pathlib.Path) – File name where to save the configuration file.

  • pure_toml (bool) – Save config in pure toml format.