ValueDefinition

class ase2sprkkr.common.value_definitions.ValueDefinition(name, type=None, default_value=None, default_value_from_container=None, written_name=None, fixed_value=None, init_by_default=False, result_is_visible=False, info=None, description=None, is_stored=None, is_hidden=False, is_optional=None, is_required=None, is_expert=False, experimental=False, is_repeated=False, repeated_delimiter=None, repeated_count=None, is_always_added=None, name_in_grammar=None, name_format=None, expert=None, write_condition=None, condition=None, warning_condition=None, validators=(), result_class=None, delimiter=None, delimiter_grammar=None, indent=None, value_mapping=None)[source]

Class hierarchy

Inheritance diagram of ase2sprkkr.common.value_definitions.ValueDefinition


Constructor

Parameters:
__init__(name, type=None, default_value=None, default_value_from_container=None, written_name=None, fixed_value=None, init_by_default=False, result_is_visible=False, info=None, description=None, is_stored=None, is_hidden=False, is_optional=None, is_required=None, is_expert=False, experimental=False, is_repeated=False, repeated_delimiter=None, repeated_count=None, is_always_added=None, name_in_grammar=None, name_format=None, expert=None, write_condition=None, condition=None, warning_condition=None, validators=(), result_class=None, delimiter=None, delimiter_grammar=None, indent=None, value_mapping=None)[source]

Definition of a configuration value.

Parameters:
  • name (str | Tuple(str)) – Name of the configuration value

  • type (Optional[GrammarType|mixed]) – Configuration value data type. If it is set to anyting what is not derived from GrammarType, the given value is used as the default value and the data type is derived from it. If it is None, the default value have to be set using expert parameter.

  • default (mixed) – Default value for the configuration option. Can accept callable (with option instance as an argument) - then the value will be determined at ‘runtime’ (possibly according to the other values of the section)

  • written_name (str) – Name of the configuration value in the input file

  • fixed_value (mixed) – If it is given, this option have a fixed_value value (provided by this parameter), that can not be changed by an user. #TODO - currently, callback (as in default_value) is not supported

  • init_by_default (bool) – If the value is not set, init it by default

  • result_is_visible (bool) –

    If True, the result (see the result property of Option) assigned to the option is visible if the value is get as its default value - in this mode the result can be used as a kind of default value, specific for given configuration object.

    If False, the result is visible to the user just using the result property and it should be some transformation of the value of the object (e.g. relative path of the given absolute path, id of assigned object etc.)

  • is_stored (bool) – If True, the value is readed/writed from the output file. If None, inherit the definition class default (normally True, False for non-stored generated definitions).

  • is_optional (bool or callable or None) – If True, the value may be omitted from the input. A callable receives the runtime Option and is evaluated after parsing, when the entire configuration is available. During grammar construction callable optionality is treated as optional. None means True if is_required is False (or inferred to be False).

  • is_required (bool or callable or str) –

    Required options must have a value when parsing or saving (however, a required option can still be optional in the grammar if it has a default value). Callable requiredness is also checked while setting, so changing a selector cannot leave its dependent option invalid. If required = None, it is set to True if both the conditions are met:

    • the value is not expert

    • the optional is not True and the option has not a default_value

    If required is str, it means the same as True, the string will be used as error message.

    If it is callable, it is evaluated on demand with the Option as its argument. The runtime section is available as option._container.

  • is_hidden (bool) – The value is hidden from the user (no container.name access to the value).

  • experimental (bool) – Mark an experimental value in the metadata and help text.

  • is_expert (Union[bool,mixed]) – Expert values are somewhat hidden (e.g. listed at end) from the user. Expert values are not exported to the result, if they are set to the default value.

  • is_repeated (bool | str | ase2sprkkr.common.repetition.Repeated) – Whether the value can apper more than once in the output. The result can be then (dense) array or (sparse) dict, see ValueDefinition.Repeated.

  • repeated_delimiter (string) – The delimiter used between repeated instances of self, if not repeated_with_name

  • repeated_count (string or int or callable) – The number of repetitions. If string, the repetition is given from the parsed value at that exact path; .. selects the parent section (for example ..NPAN). If callable, the function is called on the values of the local options named by its parameters.

  • repeated_with_name (bool) – If True, the whole value-name pair is repeated

  • is_always_added (bool)

  • validators (Callable[[Any, Any, str], Any] | Iterable[Callable[[Any, Any, str], Any]] | None)

is_always_added

If False, add the value, only if its value is not the default value. Default None means False for expert values, True for the others.

validators: callable or iterable of callables

Semantic validators receiving the option, its runtime section and validation reason.

name_in_grammar: bool or None

The value in the conf file is prefixed by <name><name_value_delimiter> If None, the default type value (type.name_in_grammar) is used

name_format: str or None

The way how the name is written

expert: Optional[mixed]

If not None, set is_expert to True, default_value to the given value and required to False. Note, that also type can be determined from such given default_value.

write_condition

If defined, write the value, only if write_condition(the option) is True.

condition
If defined, the condition
  • the condition.parse_condition() is invoked, when given grammar element should be parsed. If it is False, the element is skipped

  • the condition() is invoked, when the elements of the container is listed to hide the inactive members

result_class

Redefine the class that holds data for this option/section

delimiter

If not None, use the specified name_value_delimiter instead of common one

value_mapping

The set value is transformed by given callback before validation and/or writing

result_class

alias of ase2sprkkr.common.options.Option

intrinsic_validators = (<function _validate_warning_condition>, <function _validate_required>, <function _validate_numbering>)
is_generated = False

Whether the runtime option computes its value from other values.

_resolve_is_optional(is_optional)[source]
is_validated = None
item_type = 'value'
value_mapping = None
delimiter
Parameters:

name (Optional[str])

Return type:

ParserElement

configuration_type_name = 'OPTION'
default_repeated_type = (Type.LIST, <class fRepeatedKey>)
type_from_type_map = {}

Redefine this in descendants, if you need to create different types that the defaults to be ‘guessed’ from the default values

property name_in_grammar[source]
property default_value
allow_duplication()[source]

Can be the item repeated in the output file

property is_independent_on_the_predecessor

Some value have to be positioned just after their predecessor in the output.

enrich(option)[source]

The Option can be enriched by the definition, e.g. the docsting can be extended.

option_attribute_index(name)[source]

Return the named value index exposed as option.<name>.

data_description(verbose=False, show_hidden=False, prefix='')[source]

Return the description of the contained data type and their type.

Parameters:
  • verbose (bool | str) – If False, return only one-line string with a basic info. If True, return more detailed informations. ‘verbose’ means here the same thing as True

  • show_hidden – If False`, do not show hidden members… which has no meaning for Values.

  • prefix (str) – The string, with with each line will begin (commonly the spaces for the indentation).

additional_data_description(verbose=False, show_hidden=False, prefix='')[source]

Return the additional runtime-documentation for the configuration value. E.g. return the possible choices for the value, etc…

Parameters:
  • verbose – This parameter has no effect here. See RealItemDefinition.data_description() for its explanation.

  • show_hidden – This parameter has no effect here. See RealItemDefinition.data_description() for its explanation.

  • prefix (str) – Prefix for the indentation of the description.

Returns:

An additional description of the values accepted by this configuration option, retrieved from the documentation type.

Return type:

additional_data_description

added_to_container(container)[source]

Hook called, when the object is assigned to the container (currently from the container constructor)

validate_type(item)[source]

Return the DataType against which should be data validated.

Parameters:

item (if True, not the whole value is set, but only item of an array) – (in the case of repeated option, or e.g. the one with ase2sprkkr.common.grammar_types.Array type)

validate(opt, value, why='set', item=False)[source]
numbering_issue(opt, value)[source]

Return an error for invalid conditional numbering, if any.

Parameters:
Return type:

ase2sprkkr.common.warnings.DataValidityError | None

convert_value(opt, value, item=False)[source]

Convert value for opt; item selects element conversion.

Parameters:
Return type:

Any

validate_converted(opt, value, why='set', item=False)[source]

Validate converted value for opt and phase why.

item selects element validation rather than whole-value validation.

Parameters:
Return type:

List[ase2sprkkr.common.warnings.ValidationResult]

convert_and_validate(opt, value, why='set', item=False)[source]

Strictly convert and validate value using the supplied arguments.

Parameters:
Return type:

Any

property value_name_format
_grammar_of_value(delimiter, allow_dangerous=False)[source]

Return grammar for the (possible optional) value pair

property _grammar
_create_grammar(allow_dangerous=False, name_in_grammar=None, name_value_delimiter=None, original=False, *, allow_incomplete=False)[source]

Return a grammar for the name-value pair

get_value(option=None)[source]

Return the default or fixed value of this option.

The function can accept the Option (which of the definition is): if the default value is given by callable, this argument is passed to it. (E.g. to set the default value using some properties obtained from the configuration objects.

_save_to_file(file, option, always=False, name_in_grammar=None, delimiter='')[source]
write(file, option, value, name_in_grammar=None, delimiter='')[source]

Write the option to the open file

Parameters:
  • file – The file to write to.

  • value – The value to write. It can be instance of DangerousValue, in such case It’s own type is used to write the value.

write_value(file, option, value, delimiter='')[source]

Write given value and a given delimiter before the value to a file

write_name(file, name, delimiter='')[source]
remove(name)[source]
_generic_info()[source]
_get_init_args_for_copy(**kwargs)[source]

Compute the values for creating the copy.

Returns:

copy – The returning dictionary has this structure: { name of the argument of the __init__ function : name of the object attribute }

Return type:

Dict

_copy_excluded_args = ['container', 'grammar_hooks', 'expert', 'indent', 'fixed_value', 'result_is_visible', 'delimiter', 'delimiter_grammar']
copy_value(value, all_values=False)[source]

Creates the copy of the value

Parameters:
  • values – The value to copy

  • all_values – Wheter, for a numbered array, a whole dict is supplied

check_array_access()[source]

Check, whether the option is array type (or repeated) and thus it can be accessed as array using []