"""The classes for storing one configuration value."""
from __future__ import annotations
import copy
import numpy as np
import pyparsing as pp
from typing import Any, Optional, Union
from collections.abc import Mapping
from ..common.grammar_types import mixed
from .configuration import Configuration, UnknownMemberPolicy
from ..common.misc import as_integer
from .dangerous_values import DangerousValue
from .configuration_transaction import ConfigurationTransaction
from .warnings import (
DataValidityError,
InvalidValuePolicy,
ReportInvalidPolicy,
RetainInvalidPolicy,
ValidationResult,
)
[docs]
class _DiscardInvalidValue(Exception):
"""The proposed value was reported but must not be staged."""
[docs]
class BaseOption(Configuration):
"""A base placeholder for a leaf element of a grammar file,
both the a-value-holding ones (:class:`Option`) and
dummy ones (Dummy)
"""
[docs]
def _save_to_file(self, file, always=False, name_in_grammar=None, delimiter=""):
"""Write the name-value pair to the given file, if the value
is set."""
return self._definition.output_definition._save_to_file(file, self, always, name_in_grammar, delimiter)
[docs]
def _find_members(self, name, is_option=None, lower_case=True):
if self._definition.has_name(name, lower_case) and is_option is not False:
yield self
[docs]
def get_path(self):
return self._get_path()
[docs]
def _as_dict(self, get):
return None
[docs]
def stage_clear(
self,
transaction: ConfigurationTransaction,
*,
check_required: bool = True,
) -> bool:
"""Return false because a placeholder has no state to stage."""
return False
[docs]
class Dummy(BaseOption):
[docs]
def _validate(self, why: str) -> bool:
"""Accept validation phase ``why`` because a dummy has no value."""
return True
[docs]
def has_any_value(self):
return False
def __repr__(self):
return f"<DUMMY {self._definition.name}>"
[docs]
class DummyStub(Dummy):
[docs]
def _as_dict(self, get):
if not self._definition.allowed(self._container):
return None
return get(self._container[self._definition.item])
[docs]
class Option(BaseOption):
"""Class for one option (a configuration value) of SPRKKR - either to
be used as a part of InputParameters or Potential configuration.
Usage:
>>> from ase2sprkkr.sprkkr.calculator import SPRKKR
>>> calculator = SPRKKR()
>>> conf = calculator.input_parameters
>>> conf.ENERGY.ImE = 5.0
>>> conf.ENERGY.ImE()
unyt_quantity(5., 'Ry')
>>> conf.ENERGY.ImE.info
'Configuration value ImE'
>>> conf.ENERGY.ImE.help() # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
Configuration value ImE
<BLANKLINE>
ImE : Energy (<Real> [Ry|eV]) ≝ 0.0 Ry (optional)
>>> conf.ENERGY.ImE.set_dangerous("1J")
>>> conf.ENERGY.ImE()
'1J'
"""
[docs]
class Change:
"""Original state and finalization of a staged option value."""
_MISSING_RESULT = object()
def __init__(self, option: "Option") -> None:
"""Capture the current state and hook of ``option``."""
self.option = option
self.hook = option._hook
self.old_value = option._value
self.old_result = getattr(
option, "_result", self._MISSING_RESULT
)
[docs]
def commit(self) -> Any:
if self.hook:
return self.option, self.hook
[docs]
def rollback(self) -> None:
self.option._value = self.old_value
if self.old_result is self._MISSING_RESULT:
self.option.__dict__.pop("_result", None)
else:
self.option._result = self.old_result
[docs]
class IndexedChange(Change):
"""Rollback state for an in-place indexed value change."""
def __init__(self, option: "Option", key: Any) -> None:
"""Capture ``key`` and the surrounding state of ``option``."""
super().__init__(option)
self.key = key
self.target = option(unpack=False, all_values=True)
self.old_item = copy.deepcopy(self.target[key])
[docs]
def rollback(self) -> None:
self.target[self.key] = self.old_item
super().rollback()
_NO_KEY = object()
def __getattr__(self, name):
try:
definition = object.__getattribute__(self, "_definition")
except AttributeError:
raise AttributeError(name) from None
index = definition.option_attribute_index(name)
if index is None:
raise AttributeError(
f"{type(self).__name__!s} has no attribute {name!r}"
)
return self[index]
def __setattr__(self, name, value):
if not name.startswith("_"):
try:
definition = object.__getattribute__(self, "_definition")
except AttributeError:
pass
else:
index = definition.option_attribute_index(name)
if index is not None:
self[index] = value
return
object.__setattr__(self, name, value)
[docs]
def __init__(self, definition, container=None, value=None):
""" "
Parameters
----------
definition: ValueDefinition
The value type of the option and its format (in potential and/or task file)
container:
The container, that owns the object
value: mixed
The value of the option.
"""
super().__init__(definition, container)
self._hook = None
self._definition.enrich(self)
self._value = value
[docs]
def _value_or_default(self):
d = self._definition
if d.is_generated:
return d.get_generated(self)
if hasattr(self, "_result"):
return self._result
if self._value is not None:
return self._value
value = self.default_value
if self._definition.is_repeated.is_dict and value is not None:
return {"def": value}
return value
def __call__(self, all_values: bool = False, unpack=True):
"""
Return the value of the option.
Parameters
----------
all_values: Control the behavior for the dict_like repeated values
(see `is_repeated` attribute of :class:`ConfigurationDefinition`).
Pass True as this argument to obtain dictionary
of all values. If False (the default) is given, only the 'wildcard' value
(i.e. the one without array index, which is used for the all values not explicitly specified)
is returned.
"""
d = self._definition
value = self._value_or_default()
if not d.is_generated and d.init_by_default and self._value is None:
self._value = self._pack_value(value)
if isinstance(value, DangerousValue) and unpack:
value = value()
if d.is_repeated.is_dict and not all_values:
value = (
value.get("def", self.default_value)
if value is not None
else self.default_value
)
if unpack:
value = self._unpack_value(value)
return value
[docs]
def is_dangerous(self):
"""Return, whether the option is set to a dangerous value, i.e. a value
that bypass the validation."""
return isinstance(self._value, DangerousValue)
[docs]
def set_dangerous(self, value, index=None):
"""Set the option to a dangerous value - i.e. to a value that bypass the
type and value checks and enforcing.
However, the type of such value is still checked by the proper mixed type.
To completly bypass the check, set the value to an instance of DangerousValue
class directly.
"""
value = self._create_dangerous_value(value)
if index is not None:
self[index] = value
else:
self.set(value)
[docs]
def _create_dangerous_value(self, value):
return DangerousValue(value, self._definition.type_of_dangerous)
@property
def default_value(self):
"""Return default value for the option.
The function is here, and not in the definition, since the default value can be given
by callable, that accepts the Option as argument. This possibility is used in ase2sprkkr,
when the default values of some options are generated from the underlined Atoms object
"""
return self._definition.get_value(self)
[docs]
def set(
self,
value: Any,
*,
unknown: UnknownMemberPolicy = None,
retain_invalid: Optional[RetainInvalidPolicy] = None,
report_invalid: Optional[ReportInvalidPolicy] = None,
) -> None:
"""Set a value using independent retention and reporting policies.
``retain_invalid`` accepts ``"none"``, ``"typed"`` or ``"all"``.
The latter stores unconvertible values as :class:`DangerousValue`.
``report_invalid`` accepts ``"raise"``, ``"warn"`` or ``"ignore"``.
``unknown`` is accepted for the common container/option assignment
interface; leaf options do not perform member lookup.
"""
with self._mutation(
"set", retain_invalid, report_invalid
) as (transaction, _policy):
if value is None and not self._definition.is_generated:
self.stage_clear(transaction)
else:
self.stage(
transaction, value, unknown=unknown
)
[docs]
def stage(
self,
transaction: ConfigurationTransaction,
value: Any,
*,
unknown: UnknownMemberPolicy = None,
key: Any = _NO_KEY,
) -> bool:
"""Stage ``value`` or indexed ``key`` in ``transaction``.
Conversion and validation issues are recorded in the policy owned by
``transaction``. ``unknown`` is accepted for compatibility with
container staging.
"""
policy = transaction.policy
definition = self._definition
if definition.is_generated:
if key is self._NO_KEY:
definition.stage_generated(self, transaction, value)
else:
definition.stage_generated(self, transaction, value, key)
transaction._finish_stage()
return True
if key is not self._NO_KEY:
return self._stage_item(transaction, key, value)
def pack(item: Any) -> Any:
return self._pack_proposed_value(item, policy)
try:
if value is None:
converted = None
elif definition.is_repeated.is_dict:
if isinstance(value, Mapping):
converted = {}
rejected = False
for item_key, item in value.items():
try:
converted[item_key] = pack(item)
except _DiscardInvalidValue:
rejected = True
if rejected:
raise _DiscardInvalidValue
else:
current = self(unpack=False, all_values=True)
converted = dict(current) if isinstance(current, dict) else {}
try:
converted["def"] = pack(value)
except (TypeError, ValueError):
converted.update(
(index, pack(item))
for index, item in enumerate(value, 1)
)
elif definition.is_repeated:
if isinstance(value, Mapping):
raise ValueError('Mapping not allowed in Array-like repeated options')
if isinstance(value, (str, bytes)):
value = (value,)
else:
try:
iter(value)
except TypeError:
value = (value,)
converted_items = [pack(item) for item in value]
if (
isinstance(value, np.ndarray)
or definition.type.array_access
or len(converted_items) > 1
):
converted = np.asarray(converted_items)
else:
converted = converted_items
else:
converted = pack(value)
except _DiscardInvalidValue:
transaction._finish_stage()
return False
change = self.Change(self)
self._value = converted
self.__dict__.pop("_result", None)
transaction.push(change)
transaction._finish_stage()
return True
[docs]
def _stage_item(
self, transaction: ConfigurationTransaction,
key: Any,
value: Any,
) -> bool:
"""Stage converted ``value`` at ``key`` in ``transaction``."""
definition = self._definition
policy = transaction.policy
try:
converted = self._pack_proposed_value(
value,
policy,
item=not definition.is_repeated and definition.type.array_access,
)
except _DiscardInvalidValue:
transaction._finish_stage()
return False
if self._value is None or hasattr(self, "_result"):
current = copy.deepcopy(self._value_or_default())
current = self._unpack_value(current)
change = self.Change(self)
self._value = self._pack_value(current)
self.__dict__.pop("_result", None)
target = self._value
else:
change = self.IndexedChange(self, key)
target = self._value
try:
target[key] = converted
except Exception:
change.rollback()
raise
transaction.push(change)
self.__dict__.pop("_result", None)
transaction._finish_stage()
return True
[docs]
def add_hook(self, hook):
self._hook = hook
[docs]
def _check_array_access(self):
"""Check, whether the option is array type (or repeated) and thus it can be accessed as array using []"""
return self._definition.check_array_acces(self)
[docs]
def _set_indexed_value(self, key, value):
with self._mutation("set") as (transaction, _policy):
self.stage(transaction, value, key=key)
def __setitem__(self, name, value):
"""Set an item of a numbered array. If the Option is not a numbered array, throw an Exception."""
d = self._definition
if d.is_generated:
with self._mutation("set") as (transaction, _policy):
self.stage(transaction, value, key=name)
return
d.check_array_access()
if not d.is_repeated.is_dict:
return d.type.set_option_index(self, name, value)
current = self(unpack=False, all_values=True)
proposed = {} if current is None else d.copy_value(current, all_values=True)
def set_item(key: Any, item: Any) -> None:
if not (d.is_repeated.is_numbered.has_default and key == "def"):
try:
key = as_integer(key)
except TypeError as exc:
raise KeyError("Numbered array indexes can be only integers, lists or slices") from exc
if key < 1:
raise KeyError("Numbered array indexes has to be greater than zero")
if item is None:
proposed.pop(key, None)
else:
proposed[key] = item
if isinstance(name, (list, tuple)):
for key in name:
set_item(key, value)
elif isinstance(name, slice):
try:
count = len(value)
step = name.step or 1
start = name.start or 1
stop = name.stop or start + step * count
for key, item in zip(range(start, stop, step), value):
set_item(key, item)
except (TypeError, ValueError):
if name.stop is None:
raise KeyError(
"To set a numbered array slice to one value, the slice end has to be specified"
)
for key in range(name.start or 1, name.stop, name.step or 1):
set_item(key, value)
else:
set_item(name, value)
self.set(proposed or None)
def __getitem__(self, name):
"""Get an item of a numbered array. If the Option is not a numbered array, throw an Exception."""
d = self._definition
if d.is_generated:
return d.get_generated(self, name)
d.check_array_access()
if not d.is_repeated.is_dict:
return d.type.get_option_index(self, name)
if isinstance(name, (list, tuple)):
return [self._getitem(n) for n in name]
elif isinstance(name, slice):
if name.stop is None:
if self._value is None:
stop = 2
else:
try:
stop = max(i for i in self._value if i != "def") + 1
except ValueError:
stop = 2
name = slice(max(1, name.start or 1), stop, name.step)
return [self._getitem(n) for n in range(name.start, name.stop, name.step or 1)]
return self._getitem(name)
[docs]
def _getitem(self, name):
"""Get a single item from a numbered array. For internal use - so no sanity checks"""
if name != "def":
try:
name = as_integer(name)
except TypeError as e:
raise KeyError("Numbered array indexes can be only integers, lists or slices") from e
if self._value is None:
return self.default_value
if name in self._value:
out = self._value[name]
elif "def" in self._value:
out = self._value["def"]
else:
return self.default_value
return self._unpack_value(out)
[docs]
def _unpack_value(self, value):
"""Unpack potentionally dangerous values."""
if isinstance(value, DangerousValue):
value = value()
r = self._definition.is_repeated
if r:
if r.is_dict and isinstance(value, dict):
value = {i: v() if isinstance(v, DangerousValue) else v for i, v in value.items()}
elif isinstance(value, list):
value = [v() if isinstance(v, DangerousValue) else v for v in value]
return value
[docs]
def _pack_value(self, value):
"""Validate the value, if it's to be."""
if isinstance(value, DangerousValue):
""" The dangerous value is immutable, checked during its creation """
return value
return self._definition.convert_and_validate(self, value)
[docs]
def _pack_proposed_value(
self,
value: Any,
policy: InvalidValuePolicy,
*,
item: bool = False,
) -> Any:
"""Pack ``value`` according to the transaction's policy."""
if isinstance(value, DangerousValue):
return value
definition = self._definition
try:
converted = definition.convert_value(self, value, item=item)
except DataValidityError as issue:
if policy.retain_all:
policy.add(issue)
return DangerousValue(
value,
getattr(definition, "type_of_dangerous", None),
validate=False,
)
policy.discard(issue)
raise _DiscardInvalidValue from issue
issues = definition.validate_converted(self, converted, item=item)
retain = policy.retain_typed or not any(
isinstance(issue, DataValidityError) for issue in issues
)
record = policy.add if retain else policy.discard
for issue in issues:
record(issue)
if not retain:
raise _DiscardInvalidValue
return converted
def __contains__(self, name):
d = self._definition
d.check_array_access()
if not d.is_repeated.is_dict:
return name in self()
if self._value is None:
return False
value = self._unpack_value(self._value)
return name in value
[docs]
def get(self):
"""Return the value of self"""
return self()
@property
def result(self):
"""Return the result value.
In some cases, the value of an option have to be translated for the output.
E.g. the site can be given as site object, but the integer index is
required in the output.
In a such case, this property can be utilized: the value of the option is
retained as is and the transformed value is stored in the result.
"""
if hasattr(self, "_result"):
if isinstance(self._result, DangerousValue):
return self._result.value
return self._result
return self(all_values=True)
@result.setter
def result(self, value):
self._result = value
[docs]
def clear_result(self):
if hasattr(self, "_result"):
del self._result
[docs]
def stage_clear(
self,
transaction: ConfigurationTransaction,
*,
check_required: bool = True,
) -> bool:
"""Stage clearing in ``transaction`` without global validation.
``check_required`` rejects clearing a required option without a default.
"""
policy = transaction.policy
if self._definition.is_generated:
return self.stage(transaction, None)
if not self._definition.type.has_value:
return False
if (
self._definition.default_value is None
and check_required
and self.is_required()
):
issue = DataValidityError(
f"Option {self._get_path()} must have a value."
)
if policy.retain_typed:
policy.add(issue)
return self.stage(transaction, None)
policy.discard(issue)
transaction._finish_stage()
return False
return self.stage(transaction, None)
[docs]
def is_changed(self) -> bool:
"""True, if the value is set and the value differs from the default"""
return self.value_and_changed()[1]
[docs]
def is_set(self) -> bool:
"""True, if the value is set (even equal to the default value)"""
return self._value is not None
[docs]
def _written_value(self, always=False):
"""
Parameters
----------
always:
Skip all condition checking
Returns
-------
write value: Any
The value to be written
write: bool,
Whether to write the value or not
"""
d = self._definition
if not d.is_stored:
return None, False
if not always:
if not d.allowed(self._container):
return None, False
if not d.write_condition(self):
return None, False
if not d.type.has_value:
return None, True
if self.is_dangerous():
return self._value, self._value() is not None
value = self.result
missing, _, np = d.type.missing_value()
if np.__class__ is value.__class__ and np == value:
return value, False
if value is None or (not d.is_always_added and self.is_it_the_default_value(value)):
return value, False
return value, True
[docs]
def is_required(self) -> Union[bool, str]:
"""Return requiredness for this option."""
r = self._definition.is_required
if not r:
return False
if callable(r):
return r(self)
return r
[docs]
def _validate(self, why: str) -> None:
"""Validate this option for phase ``why``."""
d = self._definition
container = self._container
if why == "parse":
if d.validate_parsed:
d.validate_parsed(self)
parsed = getattr(container, "_parsed_values", None)
if (
parsed is not None
and d.is_stored
and d.allowed(container)
and not d.is_optional_for(self)
and self.name not in parsed
and self.name not in getattr(parsed, "checks", ())
):
# Conditions and callable optionality are resolved here, once
# all sections have been staged. Absence is a parse error,
# unlike semantic validation of an explicitly supplied value.
message = f"Missing non-optional input item {self._get_path()}"
if not getattr(parsed, "allow_incomplete", False):
raise pp.ParseException(message)
# The grammar already reported unconditional omissions.
# Runtime-dependent presence is resolved only at this stage.
if d.condition is not None or callable(d.is_optional):
DataValidityError.warn(message)
if not d.allowed(container):
return
has_stored_value = (
not d.is_generated
and d.type.has_value
)
validate_value = (
has_stored_value and
why == 'save' and (
d.is_validated
if d.is_validated is not None
else True )
)
if has_stored_value and (validate_value or d.is_repeated):
value = self(unpack=False, all_values=True)
else:
value = None
if validate_value:
if d.is_repeated:
if value is None:
validation_items = (value,)
elif isinstance(value, DangerousValue):
validation_items = ()
elif d.is_repeated.is_dict:
validation_items = tuple(value.values())
else:
validation_items = value
else:
validation_items = (value,)
for item in validation_items:
if not isinstance(item, DangerousValue):
d.validate(self, item, why)
else:
value = None
if d.is_repeated and value is not None:
ValidationResult.emit(
d.repeated_count.validate(self, len(value), why)
)
d.run_validators(self, container, why)
@property
def name(self):
return self._definition.name
[docs]
def _as_dict(self, get):
if not self._definition.allowed(self._container):
return None
return get(self)
[docs]
def value_and_changed(self):
"""Return value and whether the value was changed
Returns
-------
value:mixed
The value of the options (return all values for 'numbered array')
changed:bool
Whether the value is the same as the default value or not
"""
d = self._definition
if d.is_generated:
return self(), False
value = self._unpack_value(self._value)
if value is not None:
return value, not self.is_it_the_default_value(value)
if d.is_repeated.is_numbered.has_default and self.default_value is not None:
return {"def": self.default_value}, False
else:
return self.default_value, False
[docs]
def is_it_the_default_value(self, value):
"""Return, whether the given value is the default value. For
numbered array, only the wildcard value can be set and this value
have to be the same as the default."""
d = self._definition
if d.is_generated:
return True
default = self.default_value
if d.is_repeated.is_numbered.has_default:
return "def" in value and len(value) == 1 and d.type.is_the_same_value(value["def"], default)
else:
return d.type.is_the_same_value(value, default)
[docs]
def has_any_value(self):
return self.result is not None
def __len__(self):
return len(self())
def __iter__(self):
return iter(self())
def __bool__(self):
return True
def __repr__(self):
if self._definition.is_generated:
return f"<Generated value {self._get_path()}>"
else:
v = self._value
o = None
if o is None and v is None:
v = self.default_value
if callable(v):
v = "fn()"
if v is not None:
o = " (default)"
if v is None:
if o:
o = "out" + o
else:
o = "out"
v = ""
else:
o = ""
v = " = " + str(v)
if len(v) > 20:
v = f"{v[:10]}...{v[-10:]}"
type = "(generated)" if self._definition.is_generated else f"of type {self._definition.type}"
return f"<Option {self._get_path()} {type} with{o} value{v}>"
[docs]
class CustomOption(Option):
"""An user-added option (configuration value). It can be removed from the section."""
[docs]
def remove(self):
"""Remove me from my "parent" section"""
self._container.remove_member(self._definition.name)
[docs]
@classmethod
def factory(cls, value_definition, type=mixed):
"""Returns factory function for the given value definition"""
def create(name, section):
definition = value_definition(name, type)
definition.removable = True
return cls(definition, section)
create.grammar_type = type
return create