Source code for scm.plams.core.settings

import textwrap
import contextlib
import re
from functools import wraps

__all__ = ['Settings']


[docs]class Settings(dict): """Automatic multi-level dictionary. Subclass of built-in class :class:`dict`. The shortcut dot notation (``s.basis`` instead of ``s['basis']``) can be used for keys that: * are strings * don't contain whitespaces * begin with a letter or an underscore * don't both begin and end with two or more underscores. Iteration follows lexicographical order (via :func:`sorted` function) Methods for displaying content (:meth:`~object.__str__` and :meth:`~object.__repr__`) are overridden to recursively show nested instances in easy-readable format. Regular dictionaries (also multi-level ones) used as values (or passed to the constructor) are automatically transformed to |Settings| instances:: >>> s = Settings({'a': {1: 'a1', 2: 'a2'}, 'b': {1: 'b1', 2: 'b2'}}) >>> s.a[3] = {'x': {12: 'q', 34: 'w'}, 'y': 7} >>> print(s) a: 1: a1 2: a2 3: x: 12: q 34: w y: 7 b: 1: b1 2: b2 """
[docs] def __init__(self, *args, **kwargs): dict.__init__(self, *args, **kwargs) cls = type(self) for k, v in self.items(): if isinstance(v, dict) and type(v) is not cls: self[k] = cls(v) if isinstance(v, list): self[k] = [cls(i) if (isinstance(i, dict) and type(i) is not cls) else i for i in v]
[docs] def copy(self): """Return a new instance that is a copy of this one. Nested |Settings| instances are copied recursively, not linked. In practice this method works as a shallow copy: all "proper values" (leaf nodes) in the returned copy point to the same objects as the original instance (unless they are immutable, like ``int`` or ``tuple``). However, nested |Settings| instances (internal nodes) are copied in a deep-copy fashion. In other words, copying a |Settings| instance creates a brand new "tree skeleton" and populates its leaf nodes with values taken directly from the original instance. This behavior is illustrated by the following example:: >>> s = Settings() >>> s.a = 'string' >>> s.b = ['l','i','s','t'] >>> s.x.y = 12 >>> s.x.z = {'s','e','t'} >>> c = s.copy() >>> s.a += 'word' >>> s.b += [3] >>> s.x.u = 'new' >>> s.x.y += 10 >>> s.x.z.add(1) >>> print(c) a: string b: ['l', 'i', 's', 't', 3] x: y: 12 z: set([1, 's', 'e', 't']) >>> print(s) a: stringword b: ['l', 'i', 's', 't', 3] x: u: new y: 22 z: set([1, 's', 'e', 't']) This method is also used when :func:`python3:copy.copy` is called. """ cls = type(self) ret = cls() for name in self: if isinstance(self[name], Settings): ret[name] = self[name].copy() else: ret[name] = self[name] return ret
[docs] def soft_update(self, other): """Update this instance with data from *other*, but do not overwrite existing keys. Nested |Settings| instances are soft-updated recursively. In the following example ``s`` and ``o`` are previously prepared |Settings| instances:: >>> print(s) a: AA b: BB x: y1: XY1 y2: XY2 >>> print(o) a: O_AA c: O_CC x: y1: O_XY1 y3: O_XY3 >>> s.soft_update(o) >>> print(s) a: AA #original value s.a not overwritten by o.a b: BB c: O_CC x: y1: XY1 #original value s.x.y1 not overwritten by o.x.y1 y2: XY2 y3: O_XY3 *Other* can also be a regular dictionary. Of course in that case only top level keys are updated. Shortcut ``A += B`` can be used instead of ``A.soft_update(B)``. """ for name in other: if isinstance(other[name], Settings): if name not in self: self[name] = other[name].copy() elif isinstance(self[name], Settings): self[name].soft_update(other[name]) elif name not in self: self[name] = other[name] return self
[docs] def update(self, other): """Update this instance with data from *other*, overwriting existing keys. Nested |Settings| instances are updated recursively. In the following example ``s`` and ``o`` are previously prepared |Settings| instances:: >>> print(s) a: AA b: BB x: y1: XY1 y2: XY2 >>> print(o) a: O_AA c: O_CC x: y1: O_XY1 y3: O_XY3 >>> s.update(o) >>> print(s) a: O_AA #original value s.a overwritten by o.a b: BB c: O_CC x: y1: O_XY1 #original value s.x.y1 overwritten by o.x.y1 y2: XY2 y3: O_XY3 *Other* can also be a regular dictionary. Of course in that case only top level keys are updated. """ for name in other: if isinstance(other[name], Settings): if name not in self or not isinstance(self[name], Settings): self[name] = other[name].copy() else: self[name].update(other[name]) else: self[name] = other[name]
[docs] def merge(self, other): """Return new instance of |Settings| that is a copy of this instance soft-updated with *other*. Shortcut ``A + B`` can be used instead of ``A.merge(B)``. """ ret = self.copy() ret.soft_update(other) return ret
[docs] def find_case(self, key): """Check if this instance contains a key consisting of the same letters as *key*, but possibly with different case. If found, return such a key. If not, return *key*. """ if not isinstance(key, str): return key lowkey = key.lower() for k in self: try: if k.lower() == lowkey: return k except (AttributeError, TypeError): pass return key
[docs] def get(self, key, default=None): """Like regular ``get``, but ignore the case.""" return dict.get(self, self.find_case(key), default)
[docs] def pop(self, key, *args): """Like regular ``pop``, but ignore the case.""" # A single positional argument can be supplied `*args`, # functioning as a default return value in case `key` is not present in this instance return dict.pop(self, self.find_case(key), *args)
[docs] def popitem(self, key): """Like regular ``popitem``, but ignore the case.""" return dict.popitem(self, self.find_case(key))
[docs] def setdefault(self, key, default=None): """Like regular ``setdefault``, but ignore the case and if the value is a dict, convert it to |Settings|.""" cls = type(self) if isinstance(default, dict) and type(default) is not cls: default = cls(default) return dict.setdefault(self, self.find_case(key), default)
[docs] def as_dict(self): """Return a copy of this instance with all |Settings| replaced by regular Python dictionaries. """ d = {} for k, v in self.items(): if isinstance(v, Settings): d[k] = v.as_dict() elif isinstance(v, list): d[k] = [i.as_dict() if isinstance(i, Settings) else i for i in v] else: d[k] = v return d
[docs] @classmethod def suppress_missing(cls): """A context manager for temporary disabling the :meth:`.Settings.__missing__` magic method: all calls now raising a :exc:`KeyError`. As a results, attempting to access keys absent from an arbitrary |Settings| instance will raise a :exc:`KeyError`, thus reverting to the default dictionary behaviour. .. note:: The :meth:`.Settings.__missing__` method is (temporary) suppressed at the class level to ensure consistent invocation by the Python interpreter. See also `special method lookup`_. Example: .. code:: python >>> s = Settings() >>> with s.suppress_missing(): ... s.a.b.c = True KeyError: 'a' >>> s.a.b.c = True >>> print(s.a.b.c) True .. _`special method lookup`: https://docs.python.org/3/reference/datamodel.html#special-method-lookup """ return SuppressMissing(cls)
[docs] def get_nested(self, key_tuple, suppress_missing=False): """Retrieve a nested value by, recursively, iterating through this instance using the keys in *key_tuple*. The :meth:`.Settings.__getitem__` method is called recursively on this instance until all keys in key_tuple are exhausted. Setting *suppress_missing* to ``True`` will internally open the :meth:`.Settings.suppress_missing` context manager, thus raising a :exc:`KeyError` if a key in *key_tuple* is absent from this instance. .. code:: python >>> s = Settings() >>> s.a.b.c = True >>> value = s.get_nested(('a', 'b', 'c')) >>> print(value) True """ s = self with contextlib.suppress() if not suppress_missing else s.suppress_missing(): for k in key_tuple: s = s[k] return s
[docs] def set_nested(self, key_tuple, value, suppress_missing=False): """Set a nested value by, recursively, iterating through this instance using the keys in *key_tuple*. The :meth:`.Settings.__getitem__` method is called recursively on this instance, followed by :meth:`.Settings.__setitem__`, until all keys in key_tuple are exhausted. Setting *suppress_missing* to ``True`` will internally open the :meth:`.Settings.suppress_missing` context manager, thus raising a :exc:`KeyError` if a key in *key_tuple* is absent from this instance. .. code:: python >>> s = Settings() >>> s.set_nested(('a', 'b', 'c'), True) >>> print(s) a: b: c: True """ s = self with contextlib.suppress() if not suppress_missing else s.suppress_missing(): for k in key_tuple[:-1]: s = s[k] s[key_tuple[-1]] = value
[docs] def flatten(self, flatten_list=True): """Return a flattened copy of this instance. New keys are constructed by concatenating the (nested) keys of this instance into tuples. Opposite of the :meth:`.Settings.unflatten` method. If *flatten_list* is ``True``, all nested lists will be flattened as well. Dictionary keys are replaced with list indices in such case. .. code-block:: python >>> s = Settings() >>> s.a.b.c = True >>> print(s) a: b: c: True >>> s_flat = s.flatten() >>> print(s_flat) ('a', 'b', 'c'): True """ if flatten_list: nested_type = (Settings, list) iter_type = lambda x: x.items() if isinstance(x, Settings) else enumerate(x) else: nested_type = Settings iter_type = Settings.items def _concatenate(key_ret, sequence): # Switch from Settings.items() to enumerate() if a list is encountered for k, v in iter_type(sequence): k = key_ret + (k, ) if isinstance(v, nested_type) and v: # Empty lists or Settings instances will return ``False`` _concatenate(k, v) else: ret[k] = v # Changes keys into tuples cls = type(self) ret = cls() _concatenate((), self) return ret
[docs] def unflatten(self, unflatten_list=True): """Return a nested copy of this instance. New keys are constructed by expanding the keys of this instance (*e.g.* tuples) into new nested |Settings| instances. If *unflatten_list* is ``True``, integers will be interpretted as list indices and are used for creating nested lists. Opposite of the :meth:`.Settings.flatten` method. .. code-block:: python >>> s = Settings() >>> s[('a', 'b', 'c')] = True >>> print(s) ('a', 'b', 'c'): True >>> s_nested = s.unflatten() >>> print(s_nested) a: b: c: True """ cls = type(self) ret = cls() for key, value in self.items(): s = ret for k1, k2 in zip(key[:-1], key[1:]): if not unflatten_list: s = s[k1] continue if isinstance(k2, int) and not isinstance(s[k1], list): s[k1] = [] if isinstance(k1, int): # Apply padding to s s += [Settings()] * (k1 - len(s) + 1) s = s[k1] s[key[-1]] = value return ret
#=======================================================================
[docs] def __iter__(self): """Iteration through keys follows lexicographical order. All keys are sorted as if they were strings.""" return iter(sorted(self.keys(), key=str))
[docs] def __missing__(self, name): """When requested key is not present, add it with an empty |Settings| instance as a value. This method is essential for automatic insertions in deeper levels. Without it things like:: >>> s = Settings() >>> s.a.b.c = 12 will not work. The behaviour of this method can be suppressed by initializing the :class:`.Settings.suppress_missing` context manager. """ cls = type(self) self[name] = cls() return self[name]
[docs] def __contains__(self, name): """Like regular ``__contains`__``, but ignore the case.""" return dict.__contains__(self, self.find_case(name))
[docs] def __getitem__(self, name): """Like regular ``__getitem__``, but ignore the case.""" return dict.__getitem__(self, self.find_case(name))
[docs] def __setitem__(self, name, value): """Like regular ``__setitem__``, but ignore the case and if the value is a dict, convert it to |Settings|.""" cls = type(self) if isinstance(value, dict) and type(value) is not cls: value = cls(value) dict.__setitem__(self, self.find_case(name), value)
[docs] def __delitem__(self, name): """Like regular ``__detitem__``, but ignore the case.""" return dict.__delitem__(self, self.find_case(name))
[docs] def __getattr__(self, name): """If name is not a magic method, redirect it to ``__getitem__``.""" if (name.startswith('__') and name.endswith('__')): return dict.__getattribute__(self, name) return self[name]
[docs] def __setattr__(self, name, value): """If name is not a magic method, redirect it to ``__setitem__``.""" if name.startswith('__') and name.endswith('__'): dict.__setattr__(self, name, value) else: self[name] = value
[docs] def __delattr__(self, name): """If name is not a magic method, redirect it to ``__delitem__``.""" if name.startswith('__') and name.endswith('__'): dict.__delattr__(self, name) else: del self[name]
[docs] def _str(self, indent): """Print contents with *indent* spaces of indentation. Recursively used for printing nested |Settings| instances with proper indentation.""" ret = '' for key, value in self.items(): ret += ' '*indent + str(key) + ': \t' if isinstance(value, Settings): if len(value) == 0: ret += '<empty Settings>\n' else: ret += '\n' + value._str(indent+len(str(key))+1) else: # Apply consistent indentation at every '\n' character indent_str = ' ' * (2 + indent + len(str(key))) + '\t' ret += textwrap.indent(str(value), indent_str)[len(indent_str):] + '\n' return ret if ret else '<empty Settings>'
[docs] def __str__(self): return self._str(0)
__repr__ = __str__ __iadd__ = soft_update __add__ = merge __copy__ = copy
class SuppressMissing(contextlib.AbstractContextManager): """A context manager for temporary disabling the :meth:`.Settings.__missing__` magic method. See :meth:`Settings.suppress_missing` for more details.""" def __init__(self, obj: type): """Initialize the :class:`SuppressMissing` context manager.""" # Ensure that obj is a class, not a class instance self.obj = obj if isinstance(obj, type) else type(obj) self.missing = obj.__missing__ def __enter__(self): """Enter the :class:`SuppressMissing` context manager: delete :meth:`.Settings.__missing__` at the class level.""" @wraps(self.missing) def __missing__(self, name): raise KeyError(name) # The __missing__ method is replaced for as long as the context manager is open setattr(self.obj, '__missing__', __missing__) def __exit__(self, exc_type, exc_value, traceback): """Exit the :class:`SuppressMissing` context manager: reenable :meth:`.Settings.__missing__` at the class level.""" setattr(self.obj, '__missing__', self.missing)