Configuration

class ase2sprkkr.common.configuration.Configuration(definition, container=None)[source]

The common base class for all configurations values and containers. I.e. for Options and Sections.

Class hierarchy

Inheritance diagram of ase2sprkkr.common.configuration.Configuration


Constructor

__init__(definition, container=None)[source]

Create the object. Just sets the two properties from the parameters.

Parameters:
_definition

The “definition” of the option or section. The definition determines the name(s), value type(s) etc… contained in the configuration object. Instance of ase2sprkkr.common.configuration_definitions.BaseDefinition

_container

The parent container. I.e. the container that holds this object (e.g. for a value it is the section that owns the value) Instance of ase2sprkkr.common.configuration_containers.ConfigurationContainer

_get_path(include_root=False)[source]

Return the dot-delimited path to the item in the configuration tree.

E.g. the ENERGY option in the CONTROL section has the path CONTROL.ENERGY

_get_root_container()[source]

Return the root object of the configuration tree.

I.E. the object, that represents the whole configuration or problem-definition file

clear()[source]

Transactionally clear this item and validate the resulting tree.

Return type:

None

property name

Return the name of the option/section. The name is defined by the definition of the object.

Returns:

  • name (str)

  • The name of the object.

_as_dict(get)[source]
static as_dict_getter(only_changed='default', generated=False, copy=False)[source]
Parameters:

only_changed (bool | str)

as_dict(only_changed='basic', generated=False, copy=False, getter=None)[source]

Return the value of self, in the case of container as a dictionary. To be redefined in the descendants.

Parameters:

only_changed (bool | str) – Return only changed values, or all of them? If True, return only the values, that differ from the defaults. If False, return all the values. The default value basic means, return all non-expert values and all the changed expert values. explicit means just the values, that were explicitly set (even if they are the same as the default value)

to_dict(only_changed='basic', generated=False, copy=False, getter=None)

Return the value of self, in the case of container as a dictionary. To be redefined in the descendants.

Parameters:

only_changed (bool | str) – Return only changed values, or all of them? If True, return only the values, that differ from the defaults. If False, return all the values. The default value basic means, return all non-expert values and all the changed expert values. explicit means just the values, that were explicitly set (even if they are the same as the default value)

show()[source]

Print the configuration, as it will be saved into the configuration/problem definition file.

property info
property doc
help(verbose=False, show_hidden=False)[source]
check_for_errors(why='save', print=True)[source]

Return validation warnings for phase why and optionally print them.

Parameters:
  • why (str)

  • print (bool)

Return type:

List[_py_warnings.WarningMessage]

validate(why='save', report_invalid=None)[source]

Validate this configuration.

Parameters:
  • why (Literal['set', 'parse', 'save']) – Validation phase: set, parse or save.

  • report_invalid (Literal['raise', 'warn', 'ignore'] | None) – "raise", "warn" or "ignore". By default, errors warn after parsing and raise while setting or saving.

Return type:

List[ase2sprkkr.common.warnings.ValidationResult]

_mutation(why, retain_invalid=None, report_invalid=None)[source]

Stage, validate and finish one policy-controlled mutation.

why is the validation phase. retain_invalid and report_invalid have the values documented by InvalidValuePolicy.

Parameters:
  • why (Literal['set', 'parse', 'save'])

  • retain_invalid (Literal['none', 'typed', 'all'] | None)

  • report_invalid (Literal['raise', 'warn', 'ignore'] | None)

Return type:

Generator[Tuple[ase2sprkkr.common.configuration_transaction.ConfigurationTransaction, ase2sprkkr.common.warnings.InvalidValuePolicy], None, None]

save_to_file(file, *, validate='save')[source]

Save the configuration to a file in a given format.

This routine do some basic stuff and then call _save_to_file routine, that contains the implementation specific for the type of the configuration container/value.

Parameters:
  • file (str or file) – File to read the data from

  • validate (str | bool) – Validation mode. True and "save" perform strict save validation, False skips validation, and "warning" performs save validation without raising DataValidityError results. "set" can be used to allow values that are only required when saving.

to_string(*, validate='warning')[source]

Return the configuration (problem definition) in a string.

Parameters:
  • method (Validate. How to validate before retrieving. See the)

  • validate.

  • 'save' (Default 'warning' means the same as)

  • warning. (but only throw a)

  • validate (str | bool)

Returns:

  • configuration (str)

  • The configuration, as it should be saved in a configuration/problem definition file.