Source code for ase2sprkkr.common.configuration

"""This module contains just a base class for both configuration values - :class:`Options<ase2sprkkr.common.options.Option>`
and configuration containers - :class:`Sections<ase2sprkkr.common.configuration_containers.Section>`.
"""

from contextlib import contextmanager
from typing import Generator, List, Literal, Optional, Tuple, Union
from .configuration_transaction import (
    ConfigurationTransaction,
    PostChangeHookError,
)
from .warnings import (
    DataValidityError,
    DataValidityErrors,
    DataValidityWarning,
    InvalidValuePolicy,
    ReportInvalidPolicy,
    RetainInvalidPolicy,
    ValidationReason,
    ValidationResult,
)
import warnings


UnknownMemberPolicy = Optional[Literal["find", "add", "ignore", "fail"]]


[docs] class Configuration: """The common base class for all configurations values and containers. I.e. for :class:`Options<ase2sprkkr.common.options.Option>` and :class:`Sections<ase2sprkkr.common.configuration_containers.Section>`. """
[docs] def __init__(self, definition, container=None): """ Create the object. Just sets the two properties from the parameters. Parameters ---------- definition: ase2sprkkr.common.configuration_definitions.BaseDefinition Definition of this configuration object. container: ase2sprkkr.common.configuration_containers.ConfigurationContainer The container, that owns this configuration object. """ self._definition = 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 :class:`ase2sprkkr.common.configuration_definitions.BaseDefinition` """ self._container = 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 :class:`ase2sprkkr.common.configuration_containers.ConfigurationContainer` """
[docs] def _get_path(self, include_root=False): """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`` """ name = self.name if self._container and (include_root or self._container._container): return f"{self._container._get_path()}.{name}" return name
[docs] def _get_root_container(self): """Return the root object of the configuration tree. I.E. the object, that represents the whole configuration or problem-definition file """ return self._container._get_root_container() if self._container else self
[docs] def clear(self) -> None: """Transactionally clear this item and validate the resulting tree.""" with self._mutation("set") as (transaction, _invalid): self.stage_clear(transaction)
@property def name(self): """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. """ return self._definition.name
[docs] def _as_dict(self, get): raise NotImplementedError()
[docs] @staticmethod def as_dict_getter(only_changed: Union[bool, str] = "default", generated=False, copy=False): explicit = only_changed == "explicit" if only_changed == "default": def pick_only_changed(d): return not d.is_always_added elif only_changed == "basic": def pick_only_changed(d): return d.is_expert elif explicit: def pick_only_changed(_d): return False else: only_changed = bool(only_changed) def pick_only_changed(d): return only_changed def get(self): d = self._definition if d.is_generated and not generated: return None if explicit: v = self._unpack_value(self._value) elif pick_only_changed(d): v, c = self.value_and_changed() if not c: return None else: v = self(all_values=True) if v is not None: if copy: v = self._definition.copy_value(v, all_values=True) return v return get
[docs] def as_dict(self, only_changed: Union[bool, str] = "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 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) """ if not getter: getter = self.as_dict_getter(only_changed, generated, copy) return self._as_dict(getter)
to_dict = as_dict
[docs] def show(self): """Print the configuration, as it will be saved into the configuration/problem definition file.""" print(self.to_string())
@property def info(self): return self._definition.info() @property def doc(self): try: return self._definition.description() except AttributeError as e: raise Exception("Cannot retrieve documentation") from e
[docs] def help(self, verbose=False, show_hidden=False): if verbose is True: verbose = "all" elif verbose is False: verbose = True print(self._definition.description(verbose, show_hidden)) global _help_warning_printed if not _help_warning_printed: import __main__ as main if verbose is True and not hasattr(main, "__file__"): # I'm in repl print( "\n You can use <Configuration>.help(True) for a more detailed description of the possible configuration options. Enjoy ASE2SPRKKR!\n" ) _help_warning_printed = True
def __repr__(self): d = self._definition out = d.configuration_type_name out = out + " " + d.name.upper() return out
[docs] def check_for_errors( self, why: str = "save", print: bool = True ) -> List[warnings.WarningMessage]: """Return validation warnings for phase ``why`` and optionally print them.""" with warnings.catch_warnings(record=True) as found: warnings.simplefilter("always", DataValidityWarning) self.validate(why, report_invalid="warn") if print: for warning in found: warnings.showwarning( message=warning.message, category=warning.category, filename=warning.filename, lineno=warning.lineno, ) return found
[docs] def validate( self, why: ValidationReason = "save", report_invalid: Optional[ReportInvalidPolicy] = None, ) -> List[ValidationResult]: """Validate this configuration. Parameters ---------- why Validation phase: ``set``, ``parse`` or ``save``. report_invalid ``"raise"``, ``"warn"`` or ``"ignore"``. By default, errors warn after parsing and raise while setting or saving. """ if why not in ("set", "parse", "save"): raise ValueError(f"Unknown validation reason: {why!r}") if report_invalid is None: report_invalid = "warn" if why == "parse" else "raise" results = ValidationResult.collect(self._validate, why) ValidationResult.report(results, report_invalid) return results
[docs] @contextmanager def _mutation( self, why: ValidationReason, retain_invalid: Optional[RetainInvalidPolicy] = None, report_invalid: Optional[ReportInvalidPolicy] = None, ) -> Generator[ Tuple[ConfigurationTransaction, InvalidValuePolicy], None, None ]: """Stage, validate and finish one policy-controlled mutation. ``why`` is the validation phase. ``retain_invalid`` and ``report_invalid`` have the values documented by :class:`InvalidValuePolicy`. """ policy = InvalidValuePolicy(why, retain_invalid, report_invalid) hook_error = None try: with ConfigurationTransaction.use(self, policy) as transaction: policy = transaction.policy yield transaction, policy root = self._get_root_container() policy.add_semantic( ValidationResult.collect(root._validate, why) ) if policy.rollback: transaction.abort() except PostChangeHookError as error: hook_error = error try: policy.report() except DataValidityError as validation_error: if hook_error is not None: raise DataValidityErrors( "Configuration validation and post-change hooks failed", (validation_error, hook_error), ) from None raise if hook_error is not None: raise hook_error
[docs] def save_to_file(self, file, *, validate: Union[str, bool] = "save"): """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 Validation mode. ``True`` and ``"save"`` perform strict save validation, ``False`` skips validation, and ``"warning"`` performs save validation without raising :class:`DataValidityError` results. ``"set"`` can be used to allow values that are only required when saving. """ if validate is True: self.validate("save") elif validate is False: pass elif validate == "warning": self.validate("save", report_invalid="warn") else: self.validate(validate) if not hasattr(file, "write"): with open(file, "w") as file: out = self._save_to_file(file) file.flush() else: out = self._save_to_file(file) file.flush() return out
[docs] def to_string(self, *, validate: Union[str, bool] = "warning"): """ Return the configuration (problem definition) in a string. Parameters ---------- Validate. How to validate before retrieving. See the method validate. Default 'warning' means the same as 'save', but only throw a warning. Returns ------- configuration:str The configuration, as it should be saved in a configuration/problem definition file. """ from io import StringIO s = StringIO() self.save_to_file(s, validate=validate) return s.getvalue()
_help_warning_printed = False