ConfigurationContainer

class ase2sprkkr.common.configuration_containers.ConfigurationContainer(definition, container=None)[source]

A container for configuration (problem-definition) options and/or sections.

Options in the configuration (problem-definition) files are grouped to sections, sections are then grouped in a configuration file object. This is a base class for these containers.

Class hierarchy

Inheritance diagram of ase2sprkkr.common.configuration_containers.ConfigurationContainer


Constructor

__init__(definition, container=None)[source]

Create the container and its members, according to the definition

class MemberChange(container, member)[source]

Attachment of a custom member staged on a container.

Parameters:
commit()[source]
Return type:

None

rollback()[source]
Return type:

None

class ParsedValuesChange(container, values)[source]

Temporary record of the values explicitly present in parsed input.

Parameters:
_MISSING = <object object>
commit()[source]
Return type:

None

rollback()[source]
Return type:

None

_restore()[source]
Return type:

None

_init_members_from_the_definition()[source]
items()[source]

Members of the container. I.e. the options of the section, or sections of the configuration file e.t.c.

Returns:

  • members (dict)

  • A dictionary of the shape { name : member }

_get_attribute_member(name)[source]

Return a directly accessible member for attribute access.

Search both the original and sanitized interactive names, and reject members which are hidden or disabled by their condition.

Parameters:

name (str)

Return type:

ase2sprkkr.common.configuration.Configuration

_get(name, default=None)[source]
stage_clear(transaction, *, check_required=True)[source]

Stage descendant clearing in transaction without validation.

check_required is forwarded to descendant options.

Parameters:
Return type:

bool

_get_members(name, unknown, is_option, lower_case, *, accept)[source]

Get all the members of given name. According to unknown parameter, either only from self, or from any child containers, too.

Parameters:
  • name (str) – Name or dotted path of the requested member.

  • unknown (str or None) – If unknown == ‘find’ and there is no member with a given name, try to find the first such-named item (case insensitive) in the descendant conainers.

  • is_option (bool) – If set, limit to either Option or non-option items

  • lower_case (bool) – If true, try to search for the lower-cased name

  • accept (callable) – If given, return only members for which this predicate is true. A rejected direct member does not prevent searching descendants.

Returns:

value

Return type:

mixed

get(name=None, unknown='find', is_option=True)[source]

Get the value, either of self or of a child of a given name.

Parameters:
  • name (None or str) – If None, return contained values as a dictionary. Otherwise, return the value of the member with the given name.

  • unknown (str or None) – If unknown == ‘find’ and there is no member with a given name, try to find the first such-named item (case insensitive) in the descendant conainers. unknown == ‘find_exact’ do the same, case sensitive.

Returns:

value

Return type:

mixed

set(values=None, value=None, *, unknown='find', validation_reason='set', retain_invalid=None, report_invalid=None, **kwargs)[source]

Set values using independent retention and reporting policies.

retain_invalid accepts "none", "typed" or "all"; report_invalid accepts "raise", "warn" or "ignore". Parsing defaults to retaining typed invalid values and warning. Other assignments default to discarding invalid values and raising.

values is a mapping or one member name paired with value; unknown selects lookup, addition, ignoring or failure behavior. validation_reason is "set" or "parse". Additional keyword arguments are treated as member assignments.

Parameters:
  • values (Mapping[str, Any] | str | None)

  • value (Any)

  • unknown (Literal['find', 'add', 'ignore', 'fail'] | None)

  • validation_reason (Literal['set', 'parse', 'save'])

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

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

  • kwargs (Any)

Return type:

None

stage(transaction, values=None, value=None, *, unknown='find', **kwargs)[source]

Stage values in a transaction. This is the sole assignment-routing implementation for configuration containers.

Usage:

> input_parameters.set({‘NITER’: 5, ‘NE’: [10]}) or > input_parameters.set(NITER=5, NE=[10])

Parameters:
  • values (Mapping[str, Any] | str | None) – Dictionary of values to be set, or the name of the value, if the value is given.

  • value (Any) – Value to be set. Setting this argument require to pass string name to the values argument.

  • unknown ('add', 'find' or None) – How to handle unknown (not known by the definition) parameters. If ‘find’, try to find the values in descendant containers. If ‘add’, add unknown values as custom values. If None, throw an exception. Keyword only argument.

  • transaction (ConfigurationTransaction) – Transaction receiving the staged changes.

  • **kwargs (dict) – The values to be set (an alternative syntax as syntactical sugar)

Return type:

bool

stage_value(transaction, name, value, *, unknown='find')[source]

Resolve name and stage value using the supplied policies.

Parameters:
Return type:

bool

add(name, value=None)[source]

Add custom value to the container

Parameters:
  • name (str) – Name of the added value

  • value (value) – Value of the added value

stage_member(name)[source]

Attach custom member name and return its rollback change.

Parameters:

name (str)

Return type:

ase2sprkkr.common.configuration_containers.ConfigurationContainer.MemberChange

remove_member(name)[source]

Remove a (previously added) custom value from the container

Parameters:

name (str)

values()[source]

Return the contained configuration values.

_values()[source]

Iterate over all members of the container

_as_dict(get)[source]

Return the content of the container as a dictionary. Nested containers will be transformed to dictionaries as well.

Parameters:

get – This function will be applied to the options to (possible) obtain the values

_find_members(name, is_option=None, lower=False)[source]

Iterates over a value of a given name in self or in any of owned subcontainers.

Parameters:
  • name (str)

  • options (find only)

  • is_option (bool)

  • True (If)

  • options

  • False (if)

  • others. (find only the)

  • lower (bool)

  • True

  • insensitive) (find an option with given lowercased name (case)

Returns:

  • value (typing.Optional[ase2sprkkr.common.options.Option])

  • The first option of the given name, if such exists. None otherwise.

_add(member)[source]
is_changed()[source]
_save_to_file(file, always=False, name_in_grammar=None, delimiter='')[source]

Save the content of the container to the file (according to the definition)

Parameters:
  • file (file) – File object (open for writing), where the data should be written

  • always – Do not consider conditions

Returns:

If any value have been written return True, otherwise return False.

Return type:

something_have_been_written

_validate(why)[source]

Validate the configuration data. Raise an exception, if the validation fail.

Parameters:

why (str) – Type of the validation. Possible values save - Full validation, during save. set - Validation on user input. Allow required values not to be set. parse - Validation during parsing - some check, that are enforced by the parser, can be skipped.

_abc_impl = <_abc._abc_data object>