key_val_conf_spec module

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

class KeyValConfSpec(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)

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, optional) – A set of allowed values, or range of allowed values. The default is None, in which case no checking is performed.

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

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

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

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

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

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

  • derived (bool, optional) – 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__() → None

Force self.types to be a tuple of types.

validate(toml_value: Any, **kwargs) → bool

Check that the given toml line is valid.

is_valid_type(toml_value: Any, **kwargs) → bool

Check that the value has the proper typing.

is_valid_value(toml_value: Any, **kwargs) → bool

Check that the value is accepted.

path_exists(toml_value: Any, toml_folder: Path | None = None, **kwargs) → bool

Check that the given path exists if necessary.

to_toml_string(toml_value: Any | None = None, original_toml_folder: Path | None = None, **kwargs) → str

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

Parameters:

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

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

Returns:

The .toml line corresponding to current object.

Return type:

str

to_csv_line() → tuple[str, str, str, str, str] | None

Convert object to a line for the documentation CSV.

Returns:

  • key (str) – Name of variable.

  • types (str) – List of allowed types.

  • description (str) – Description of the input.

  • allowed_values (str) – List of allowed values if relatable.

  • is_mandatory (str) – If the variable is mandatory or not.

__init__(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) → None