key_val_conf_spec module

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

class KeyValConfSpec(key, types, description, default_value, allowed_values=None, is_mandatory=True, is_a_path_that_must_exists=False, action=None, warning_message=None, error_message=None, overrides_previously_defined=False, derived=False)

Bases: object

Set specifications for a single key-value pair.

Parameters:

• key (str) – Name of the attribute.

• types (tuple[type, ...]) – Allowed types for the value. Used to check validity of input. When creating a config TOML file, the first type of the tuple is used for proper formatting. Prefer giving a tuple of types, even if there is only one possible type.

• description (str) – A markdown string to describe the property. Will be displayed in the documentation.

• default_value (Any) – A default value for the property. Used when generating dummy configurations; also used if the property is not mandatory and was not provided.

• allowed_values (Collection[Any] | None, default: None) – A set of allowed values, or range of allowed values. The default is None, in which case no checking is performed.

• is_mandatory (bool, default: True) – If the property must be given.

• is_a_path_that_must_exists (bool, default: False) – If the property is a string/path and its existence must be checked before running the code.

• action (Literal['store_true', 'store_false'] | None, default: None) – on/off flag, also check the argparse documentation. Will skip testing over type and allowed values.

• warning_message (str | None, default: None) – If provided, using current key will print a warning with this message.

• error_message (str | None, default: None) – If provided, using current key will raise an IOError with this error message.

• overrides_previously_defined (bool, default: False) – If the current object should remove a previously defined KeyValConfSpec with the same name.

• derived (bool, default: False) – If the property is calculated from other properties. The default is False, in which case it must be set by the user. Note that derived keys will not appear in the TOML output strings.

key: str

types: tuple[type, ...]

description: str

default_value: Any

allowed_values: Collection[Any] | None = None

is_mandatory: bool = True

is_a_path_that_must_exists: bool = False

action: Literal['store_true', 'store_false'] | None = None

warning_message: str | None = None

error_message: str | None = None

overrides_previously_defined: bool = False

derived: bool = False

__post_init__()

Force self.types to be a tuple of types.

Return type:

None

validate(toml_value, **kwargs)

Check that the given toml line is valid.

Parameters:

toml_value (Any)

Return type:

bool

is_valid_type(toml_value, **kwargs)

Check that the value has the proper typing.

Parameters:

toml_value (Any)

Return type:

bool

is_valid_value(toml_value, **kwargs)

Check that the value is accepted.

Parameters:

toml_value (Any)

Return type:

bool

path_exists(toml_value, toml_folder=None, **kwargs)

Check that the given path exists if necessary.

Parameters:

• toml_value (Any)

• toml_folder (Path | None, default: None)

Return type:

bool

to_toml_string(toml_value=None, original_toml_folder=None, **kwargs)

Convert the value into a line that can be put in a TOML.

Parameters:

• toml_value (Any | None, default: None) – The value to put in the file. If not provided, we issue a warning and set at default value.

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

Return type:

str

Returns:

The TOML line corresponding to current object.

to_csv_line()

Convert object to a line for the documentation CSV.

Todo

Better display of allowed values

Return type:

list[str] | None

Returns:

• key – Name of variable.

• types – list of allowed types.

• description – Description of the input.

• allowed_values – list of allowed values if relatable.

• is_mandatory – If the variable is mandatory or not.

__init__(key, types, description, default_value, allowed_values=None, is_mandatory=True, is_a_path_that_must_exists=False, action=None, warning_message=None, error_message=None, overrides_previously_defined=False, derived=False)

Parameters:

• key (str)

• types (tuple[type, ...])

• description (str)

• default_value (Any)

• allowed_values (Collection[Any] | None, default: None)

• is_mandatory (bool, default: True)

• is_a_path_that_must_exists (bool, default: False)

• action (Literal['store_true', 'store_false'] | None, default: None)

• warning_message (str | None, default: None)

• error_message (str | None, default: None)

• overrides_previously_defined (bool, default: False)

• derived (bool, default: False)

Return type:

None