config_manager module

Load, validate and post-process the configuration.

Todo

Method to generate the .csv files of documentation from the tables, i.e. docs/manual/configuration_entries

process_config(toml_path: ~pathlib.Path, config_keys: dict[str, str], warn_mismatch: bool = False, override: dict[str, dict[str, ~typing.Any]] | None = None, conf_specs_t: type[~lightwin.config.full_specs.ConfSpec] = <class 'lightwin.config.full_specs.ConfSpec'>) → dict[str, dict[str, Any]]

Load and test the configuration file.

Parameters:

  • toml_path (pathlib.Path) – Path to the configuration file. It must be a TOML file.

  • config_keys (dict[str, str]) – Associate the name of LightWin’s group of parameters to the entry in the configuration file.

  • warn_mismatch (bool, optional) – Raise a warning if a key in a override sub-dict is not found.

  • override (dict[str, dict[str, Any]] | None, optional) – To override entries in the TOML. If not provided, we keep defaults.

  • conf_specs_t (type[ConfSpec], optional) – The specifications that the TOML must match to be accepted. If not provided, we take a default.

Returns:

toml_fulldict – A dictionary holding all the keyword arguments that will be passed to LightWin objects, eg beam_calculator will be passed to BeamCalculator.

Return type:

dict[str, dict[str, Any]]

load_toml(config_path: Path, config_keys: dict[str, str], warn_mismatch: bool, override: dict[str, dict[str, Any]] | None) → dict[str, dict[str, Any]]

Load the TOML and extract the dicts asked by user.

Parameters:

  • config_path (pathlib.Path) – Path to the configuration file.

  • config_keys (dict[str, str]) – Keys will be the keys of the output. Values are the name of the tables in the configuration file. If config_keys = {"beam": "proton_beam"} , the output will look like {"beam": {<content of [proton_beam]>}}.

  • warn_mismatch (bool) – Check if there are discrepancies between override and the keys or dicts to override in config_keys.

  • override (dict[str, dict[str, Any]] | None) – To override some entries of the output dictionary, before even testing it.

Returns:

A dictionary which keys are the keys of config_keys, and the values are dictionaries holding corresponding table entries from the configuration file.

Return type:

dict[str, dict[str, Any]]

_override_some_toml_entries(toml_fulldict: dict[str, dict[str, Any]], warn_mismatch: bool, **override: dict[str, Any]) → None

Override some entries before testing.

dict_to_toml(toml_fulldict: dict[str, dict[str, Any]], toml_path: Path, conf_specs: ConfSpec, allow_overwrite: bool = False, original_toml_folder: Path | None = None, **kwargs) → None

Write the provided configuration dict to a TOML file.

Parameters:

  • toml_fulldict (dict[str, dict[str, Any]]) – The configuration as a nested dictionary. The keys will be used as table entries.

  • toml_path (pathlib.Path) – Where to save the TOML.

  • conf_specs (ConfSpec) – Holds the template to be respected. In particular, the type of the values in the different tables.

  • allow_overwrite (bool, optional) – If a pre-existing TOML can be overwritten. The default is False, in which case an error will be raised.

  • original_toml_folder (pathlib.Path | None, optional) – Where the original TOML was; this is used to resolve paths relative to this location.

_indue_overwritting(toml_path: Path, allow_overwrite: bool = False) → bool

Ensure that TOML will not be overwritten if not wanted.