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

exception ConfigFileNotFoundError

Bases: FileNotFoundError

Custom exception raised when the configuration file is not found.

exception InvalidTomlSyntaxError

Bases: ValueError

Custom exception raised for invalid TOML syntax.

process_config(toml_path, config_keys, warn_mismatch=False, override=None, conf_specs_t=<class 'lightwin.config.full_specs.ConfSpec'>)

Load and test the configuration file.

Parameters:

• toml_path (pathlib.Path | str | importlib.resources.abc.Traversable) – Path to the configuration file. It can be path to a real file or a resource reference.

• 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(toml_path)

Load the TOML and extract the dicts asked by user.

Parameters:

toml_path (pathlib.Path | str | importlib.resources.abc.Traversable) – Path to the configuration file. It can be path to a real file or a resource reference.

Returns:

raw_toml – Dictionary holding the whole TOML file.

Return type:

dict[str, dict[str, Any]]

_process_toml(raw_toml, config_keys, *, warn_mismatch, override)

Extract the dicts asked by user. Override some keys if requested.

Parameters:

• raw_toml (dict[str, dict[str, Any]]) – Dictionary holding the whole TOML 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:

toml_fulldict – 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, warn_mismatch, **override)

Override some entries before testing.

Parameters:

• toml_fulldict (dict[str, dict[str, Any]])

• warn_mismatch (bool)

• override (dict[str, Any])

Return type:

None

dict_to_toml(toml_fulldict, toml_path, conf_specs, allow_overwrite=False, original_toml_folder=None, **kwargs)

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.

Return type:

None

_indue_overwritting(toml_path, allow_overwrite=False)

Ensure that TOML will not be overwritten if not wanted.

Parameters:

• toml_path (Path)

• allow_overwrite (bool, default: False)

Return type:

bool