table_spec module

Define the base objects constraining values/types of config parameters.

class TableConfSpec(configured_object, table_entry, specs, is_mandatory=True, can_have_untested_keys=False, selectkey_n_default=None, monkey_patches=None)

Bases: object

Set specifications for a table, which holds several key-value pairs.

Note

This object can be subclassed for specific configuration needs, eg BeamTableConfSpec.

Parameters:

• configured_object (Literal['beam', 'beam_calculator', 'beam_calculator_post', 'design_space', 'evaluators', 'files', 'plots', 'wtf'])

• table_entry (str)

• specs (Collection[KeyValConfSpec] | dict[str, Collection[KeyValConfSpec]] | dict[bool, Collection[KeyValConfSpec]])

• is_mandatory (bool, default: True)

• can_have_untested_keys (bool, default: False)

• selectkey_n_default (tuple[str, str | bool] | None, default: None)

• monkey_patches (dict[str, dict[str, Callable]] | dict[bool, dict[str, Callable]] | None, default: None)

__init__(configured_object, table_entry, specs, is_mandatory=True, can_have_untested_keys=False, selectkey_n_default=None, monkey_patches=None)

Set a table of properties. Correspond to a [table] in the TOML.

Parameters:

• configured_object (Literal['beam', 'beam_calculator', 'beam_calculator_post', 'design_space', 'evaluators', 'files', 'plots', 'wtf']) – Name of the object that will receive associated parameters.

• table_entry (str) – Name of the table in the TOML file, without brackets.

• specs (Collection[KeyValConfSpec] | dict[str, Collection[KeyValConfSpec]] | dict[bool, Collection[KeyValConfSpec]]) – The KeyValConfSpec objects in the current table. When the format of the table depends on the value of a key, provide a dictionary linking every possible table with the corresponding value.

• is_mandatory (bool, default: True) – If the current table must be provided.

• can_have_untested_keys (bool, default: False) – If LightWin should remain calm when some keys are provided in the TOML but do not correspond to any KeyValConfSpec.

• selectkey_n_default (tuple[str, str | bool] | None, default: None) – Must be given if specs is a dict. First value is name of the spec, second value is default value. We will look for this spec in the configuration file and select the proper Collection of KeyValConfSpec accordingly.

• monkey_patches (dict[str, dict[str, Callable]] | dict[bool, dict[str, Callable]] | None, default: None) – Same keys as specs, to override some default methods.

Return type:

None

_selectkey_n_default

Selector used when specs is a dictionary. When specs is given as a dictionary (e.g. { "modeA": [...], "modeB": [...] }), the configuration format depends on the value of a specific key inside the TOML table. This argument tells TableConfSpec which TOML key to read and which default value to use if that key is absent. The tuple must contain:

• the name of the selector key (a key expected in the TOML table),

• the default value to fall back on if the selector key is not present.

Example

specs = {
  "Envelope1D": envelope_1d_specs,
  "TraceWin": tracewin_specs,
}
selectkey_n_default = ("beam_calculator", "Envelope1D")

then:

• the value of toml_table["beam_calculator"] determines whether envelope_1d_specs or tracewin_specs is used;

• if "beam_calculator" is not provided in the TOML, "Envelope1D" is used.

This parameter must be provided whenever specs is a dictionary. It must be None when specs is a flat collection.

_get_specs(toml_table=None)

Get the proper list of KeyValConfSpec.

Used when we need to read the value of _selectkey_n_default in the TOML to choose precisely which configuration we should match.

Parameters:

toml_table (dict[str, Any] | None, default: None) – A TOML table. We use it only if self._specs is not already a Collection. We look for the value of self._selectkey_n_default[0] and use it to select the proper table. If not provided, we fall back on a default value.

Return type:

list[KeyValConfSpec]

_set_specs_as_dict(toml_table=None)

Select and prepare KeyValConfSpec used to validate this table.

This method is responsible for determining which specification set applies to the current table, especially when the available specs depend on the value of a key inside the TOML table (via _selectkey_n_default).

The returned value is a dictionary mapping spec names to KeyValConfSpec instances. It performs the following steps:

1. Determine the correct list of KeyValConfSpec objects by calling _get_specs(toml_table). If specs was provided as a dictionary, this uses the selector key defined in _selectkey_n_default to choose the appropriate spec set. If specs is a flat collection, that collection is returned unchanged.

2. Apply override rules and remove any earlier specs that should be replaced (overrides_previously_defined=True) using _remove_overriden_keys().

3. Return the cleaned specifications as a {spec.key: spec} dictionary.

This method is called multiple times during TableConfSpec.prepare():

• once before validation, to build the spec set according to the raw TOML input;

• once after post-treatment, to ensure the final specs_as_dict reflects any modifications (e.g. inserted defaults, resolved paths, or monkey patches applied during spec selection).

Parameters:

toml_table (dict[str, Any] | None, default: None) – A table from the TOML configuration file. Required only when spec selection depends on user-provided values. When omitted, default values from _selectkey_n_default are used.

Returns:

The active specification dictionary for this table.

Return type:

dict[str, KeyValConfSpec]

_get_proper_spec(spec_name)

Get the specification for the property named spec_name.

Parameters:

spec_name (str)

Return type:

KeyValConfSpec | None

to_toml_strings(toml_table, original_toml_folder=None, **kwargs)

Convert the given dict in string that can be put in a TOML.

Parameters:

• toml_table (dict[str, Any]) – A dictionary corresponding to a TOML table.

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

Returns:

All the TOML lines corresponding to the table under study.

Return type:

list[str]

_pre_treat(toml_table, **kwargs)

Insert default values for missing keys.

You can inherit this method to perform additional pre-treating logic.

Parameters:

toml_table (dict[str, Any])

Return type:

None

_insert_defaults(toml_table, **kwargs)

Insert default values for missing keys.

Parameters:

toml_table (dict[str, Any])

Return type:

None

prepare(toml_table, **kwargs)

Validate the config dict and edit some values.

Parameters:

toml_table (dict[str, Any])

Return type:

bool

_validate(toml_table, **kwargs)

Check that key-values in toml_table are valid.

This method is defined to keep an implementation of the original method even when validate is overriden by a monkey patch.

Parameters:

toml_table (dict[str, Any])

Return type:

bool

_post_treat(toml_table, **kwargs)

Edit some values, create new ones. To call after validation.

Note

In general, the edited values will not be validated. To handle with care.

Parameters:

toml_table (dict[str, Any])

Return type:

None

_make_paths_absolute(toml_table, toml_folder=None, **kwargs)

Transform the paths to their absolute resolved version.

Parameters:

• toml_table (dict[str, Any])

• toml_folder (Path | None, default: None)

Return type:

None

_mandatory_keys_are_present(toml_keys)

Ensure that all the mandatory parameters are defined.

Parameters:

toml_keys (Collection[str])

Return type:

bool

generate_dummy_dict(only_mandatory=True)

Generate a default dummy dict that should let LightWin work.

Parameters:

only_mandatory (bool, default: True)

Return type:

dict[str, Any]

_apply_monkey_patches(monkey_patches)

Override the base methods.

Parameters:

monkey_patches (dict[str, Callable])

Return type:

None

_remove_overriden_keys(specs)

Remove the KeyValConfSpec objects to override.

Todo

Not Pythonic at all.

Parameters:

specs (Collection[KeyValConfSpec])

Return type:

list[KeyValConfSpec]