ialdev-core 0.1.0__py3-none-any.whl

iad/core/param/__init__.py

@@ -0,0 +1,17 @@
+from frozendict import frozendict as fzdict
+
+from . import paramaze as pa
+from .tbox import TBox
+
+__all__ = ['TBox', 'model_arguments', 'YamlModel', 'fzdict']
+
+
+def __getattr__(name: str):
+    """Lazy imports for YAML/Pydantic helpers shipped in ``iad.core.pydantools``."""
+    if name == 'YamlModel':
+        from iad.core.pydantools.models import YamlModel as _YamlModel
+        return _YamlModel
+    if name == 'model_arguments':
+        from iad.core.pydantools.models import model_arguments as _model_arguments
+        return _model_arguments
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

iad/core/param/confargparse.py

@@ -0,0 +1,55 @@
+import configargparse as cap
+
+
+class ArgumentParserYAML(cap.ArgumentParser):
+    def __init__(self, *, hash_groups=None, add_env_var_help=False, **kws):
+        super().__init__(config_file_parser_class=cap.YAMLConfigFileParser,
+                         add_env_var_help=add_env_var_help,
+                         **kws)
+        self.hash_groups = hash_groups or {}
+
+    def save_config(self, namespace, config_file):
+        if BUG_FIXED := False:  # TODO: write_config_file prints all values as str!
+            self.write_config_file(namespace, [str(config_file)])
+        else:
+            op_map = {op.dest: op.option_strings[-1] for op in self._get_optional_actions()}
+
+            def items_to_save():
+                for k, v in namespace.__dict__.items():
+                    if not (v is None or k in ('cmd', 'config')):
+                        yield op_map[k].strip('-'), v
+
+            file_contents = self._config_file_parser.serialize(items_to_save())
+            with self._config_file_open_func(config_file, "w") as output_file:
+                output_file.write(file_contents)
+                print(f"Config file saved: {config_file}")
+
+    def hashes(self, ns: cap.Namespace, length=4) -> dict:
+        """
+        Calculate hash values for the defined groups of arguments.
+        Return dict with hashes py group.
+        If groups are not defined the namespace is used and named 'cfg'.
+
+        :param ns: Namespace with parsed arguments
+        :param length: length of hash string tail to used (0 - all of it)
+
+        :return: dict {grp_name: hash_str}
+        """
+        from .tbox import TBox
+        groups = self.hash_groups or {'cfg': [*vars(ns)]}
+        ns = vars(ns)
+
+        def hash_group(names):
+            group_params = {name: ns[name] for name in names if name in ns}
+            return TBox(group_params).hash_str(length)
+
+        return {grp: hash_group(names) for grp, names in groups.items()}
+
+    def hash_stamp(self, ns: cap.Namespace, length=4) -> str:
+        """
+        Hash stamp string unique for the ns content by arguments groups.
+        :param ns:  namespace with arguments
+        :param length: length of hash strings
+        :return: "grp1_hash1_grp2_hash2_..."
+        """
+        return '_'.join(map(lambda it: f"{it[0]}_{it[1]}", self.hashes(ns, length).items()))

iad/core/param/paramaze.py

@@ -0,0 +1,339 @@
+import inspect
+from contextlib import contextmanager
+from enum import IntEnum, unique
+from typing import Union, Callable, Optional, Dict, Sequence
+
+from .. import as_list, fnctools as fnt, wrap
+from .tbox import TBox
+
+Rule = Union[Callable, str, None]
+
+
+def sub(*args, **kws):
+    func_defs = {f.paramaze.alias: f.paramaze.defaults for f in args}
+    return TBox(frozen_box=True, **func_defs, **kws)
+
+
+@unique
+class Validate(IntEnum):
+    OFF = 0         # no validation
+    REPORT = 1      # report about errors but not raise
+    RAISE = 2       # validate, but not report - only raise on errors
+    VERBOSE = 3     # raise on errors
+
+    @classmethod
+    @contextmanager
+    def level(cls, vld_level: Union['Validate', str]):
+        """
+        Create validation context to execute code with specific validation level
+        and restore the current one on exit
+        :param vld_level: as name str or `Validate` object
+        """
+        if isinstance(vld_level, str):
+            vld = Validate[vld_level]
+        old_vld = FuncPar.validation(vld)
+        try:
+            yield vld
+        finally:
+            FuncPar.validation(old_vld)
+
+
+class FuncPar:
+    """
+    Class cls::`FuncPar` treats arguments of a function as dictionary of
+    parameters with additional properties tools, like
+    - defaults
+    - validation conditions
+    - automatic or explicit validation
+    - automatic extraction of parameters found arbitrary processing flows
+    - and more
+    """
+
+    _validate = Validate.RAISE
+
+    @classmethod
+    def validation(cls, state: Optional[Validate] = None) -> Validate:
+        """Set new parameters validation level and return the previous one"""
+        if state is None:
+            return cls._validate
+        else:
+            old, cls._validate = cls._validate, Validate(state)
+            return old
+
+    class Tracker:
+        """Helper sub-class of cls::`FuncPar` to track nested calls of
+        parametrized functions."""
+
+        def __init__(self):
+            self._track = False
+            self._frame = None
+            self._depth = None
+            self._record = {}
+            self._stack = []
+
+        reset = __init__
+
+        def start(self):
+            """Start tracking of the execution flow for all nested calls"""
+            if self._frame is None:
+                st = inspect.stack()
+                self._frame = st[1].frame
+                self._depth = len(st)
+            self._track = True
+
+        def stop(self):
+            """Stop tracking - but keep collected record (unlike `reset`)"""
+            self._track = False
+
+        def restart(self):
+            """Clear context and restart the tracking from current frame"""
+            self.__init__()
+            self.start()
+
+        def report(self) -> Dict[str, 'FuncPar']:
+            """Produce dictionary of all calls to functions with `FuncPar`
+            with keys as dot separated names of nested called functions.
+            """
+            return self._record.copy()
+
+        def __bool__(self):
+            return self._track
+
+        def track_call(self, arg_par: 'FuncPar'):
+            """Track specific call provided its `FuncPar` context"""
+            func_name = arg_par.function.__qualname__
+            self._stack.append(func_name)
+            if self._track:
+                st = inspect.stack()
+                depth = len(st) - self._depth + 1
+                if depth > 0 and st[depth].frame is self._frame:
+                    self._record['.'.join(self._stack)] = arg_par
+
+    track = Tracker()
+
+    def __init__(self, func: Callable, *, alias: str = None,
+                 validate: Union[Rule, Sequence[Rule]] = None,
+                 directives: Dict[str, Union[Rule]]):
+        """Construct `FuncPar` instance for specific function using
+        provided validation rules and condition directives.
+
+        :param func: function object to associate with
+        :param alias: optional (short) version of name to associate with
+                      the parameters structure instead of the function name
+        :param validate: single or sequence of validation rules in form of
+            a python expression using variables named by the parameters
+            or callable accepting keywords arguments or those parameters.
+        :param directives: dictionary per parameter of validation conditions
+            in form of expression using single variable denoted as "{}" or
+            callable with a single argument to receive the parameter value.
+
+        Examples:
+            Associates conditions with function arguments.
+            >>> def func(x=10, y=20): pass
+            >>> p_func = FuncPar(func, validate='x < y',\
+                            directives={'y': "{} > 0"}).function
+            >>> assert p_func(20, 10)    # will fail on x < y
+            Traceback (most recent call last):
+                ...
+            AssertionError
+            >>> assert p_func(-10, -2)   # will fail on y > 0
+        """
+        from functools import wraps
+
+        self._name = func.__qualname__
+        self._params = TBox()    # arguments which are parameters with defaults
+        self._cond = {}          # parameters with assigned conditions
+        self._alias = alias or self._name
+
+        # First parse all the function's arguments to determine:
+        # - which have defaults - candidates to be parameters
+        # - which are mentioned in the special directives
+        all_defaults = {}  # default values for ALL the arguments
+        invalid_references = set(directives)   # ensure directives refer to existing arguments
+
+        pos_kws_start = 0  # location of first not position-only argument
+        pos_kws = []  # names (ordered) of all the pos_or_kw arguments
+        try:
+            for i, (name, arg) in enumerate(inspect.signature(func).parameters.items()):
+                if arg.kind is arg.VAR_POSITIONAL:
+                    raise NotImplementedError("Variadic positional arguments")
+                if arg.kind in (arg.POSITIONAL_ONLY, arg.VAR_KEYWORD):
+                    continue  # positional and variadic arguments are not parametrized!
+
+                # other kinds with provided default values are be turned in parameters
+                # unless explicitly excluded in directives
+                if arg.kind is arg.POSITIONAL_OR_KEYWORD:  # keep track on ambiguous arguments
+                    if not pos_kws:                  # to separate position-only when called
+                        pos_kws_start = i
+                    pos_kws.append(name)
+
+                if arg.default is not arg.empty:
+                    all_defaults[name] = arg.default  # to implement defaults logistics
+                    self._params[name] = arg.default        # may be exclude below
+                    if name in directives:  # either provides condition or excludes from params
+                        invalid_references.remove(name)     # remove valid names from the black list
+                        cond = directives[name]
+                        if cond:
+                            if isinstance(cond, str):
+                                cond = fnt.express_to_lambda(cond.format(name), name)
+                            self._cond[name] = cond
+                        else:  # exclude from params if explicitly set to False or None
+                            self._params.pop(name)
+
+            if invalid_references:
+                raise ReferenceError(f"Conditions defined for invalid arguments: {invalid_references}")
+
+            self._validators = [v if callable(v) else fnt.express_to_kw_func(v) for v in
+                                (as_list(validate) if validate else [])]
+        except SyntaxError as e:
+            e.msg = f"Invalid validation condition for function <{self._name}>"
+            raise e
+
+        def separate_kw_args(args):
+            """Separate variadic positional argument into position only and pos_or_kw."""
+            found_pos_kws = len(args) - pos_kws_start
+            if found_pos_kws > len(pos_kws):
+                raise SyntaxError(f"Positional args to <{self._name}> exceed  {len(pos_kws)}!")
+            if found_pos_kws < 0:
+                raise SyntaxError(f"Missing {-found_pos_kws} positional args in <{self._name}>!")
+            # create kw form of the args passed by position
+            silent_kw_arg = dict(zip(pos_kws[:found_pos_kws], args[-found_pos_kws:]))
+            return silent_kw_arg
+
+        def filter_keys_in(d, seq, *, keep_in=True):
+            """Filter dictionary by keys belonging or not to given sequence"""
+            seq = set(seq)
+            condition = (lambda x: x in seq) if keep_in else (lambda x: x not in seq)
+            return {k: v for k, v in d.items() if condition(k)}
+
+        @wraps(func)
+        def pz_func(*args, _par: dict = None, **kws):
+            # Responsibilities of the wrapper:
+            # 1. Optional validation of the parameters values
+            # 2. Inform the ArgPar.tracker about the call to collect flow information.
+            # 3. Automatically fetch parameters from repository through special argument _par
+            # 4. (No Harm) Maintain same syntax as the original function in spite of different signature
+            #    - make variadic argument behave like named in the original function
+            #    - support the additional (optional) _par argument
+            silent_kws = separate_kw_args(args)
+
+            # optionally keyword parameters may be passed inside special _par
+            if _par:  # automatic fetch of relevant parameters from the repo
+                # dict-like argument as item under the key `func.name` or `func.alias`
+                # which `dict`-like value would contain any subset of them.
+                _par = getattr(_par, self._name, getattr(_par, self._alias, {}))
+                # make sure no arguments are not passed twice from different sources
+                if self.validation() > Validate.RAISE:
+                    if twice := set(_par).intersection(set(silent_kws).union(kws)):
+                        from warnings import warn
+                        warn(f"Double {twice} in {self._name}: as args and (ignored) in _par")
+
+                kws = {**filter_keys_in(_par, silent_kws, keep_in=False), **kws}  # _par-silent-kws+kws
+
+            self.validate({**silent_kws, **kws})  # add silent to validation
+            FuncPar.track.track_call(self)
+            return func(*args, **kws)
+
+        self._func = pz_func
+        self.__call__ = pz_func
+
+        setattr(pz_func, 'paramaze', self)
+        setattr(pz_func, 'defaults', self.defaults)
+        setattr(pz_func, 'validate', self.validate)
+
+    def __repr__(self):
+        return f'Params in function `{self.name}`:\n' \
+               f'{self._params.to_yaml()}'
+
+    @property
+    def function(self):
+        return self._func
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def alias(self):
+        return self._alias
+
+    @property
+    def defaults(self):
+        """Return editable copy of the default parameters"""
+        return TBox(self._params, frozen_box=False)
+
+    def validate(self, par, throw=True):
+        vld = self.validation()
+        if vld is Validate.OFF:
+            return True
+        if vld is Validate.VERBOSE:
+            print(f'Validating {self.name} parameters: {tuple(par)}...', end='')
+
+        def try_cond(context, cond, *args, **kws):
+            try:
+                return cond(*args, **kws)
+            except Exception as e:
+                raise SyntaxError("Invalid validation condition for function "
+                                  f"<{self._func.__qualname__}>\n"
+                                  f"{context} {cond.__qualname__}\n{e}")
+
+        failed_pars = [f"{k}={v} fails condition: {self._cond[k].__qualname__}"
+                       for k, v in par.items() if k in self._cond and
+                       not try_cond(f"for parameter {k}", self._cond[k], v)]
+
+        merged_par = {**self._params, **par}
+        failed_rules = [rule.__qualname__ for rule in self._validators if
+                        not try_cond("in validation rule", rule, **merged_par)]
+
+        msg = '\n\t'.join(['Invalid Parameters:', *failed_pars]) + '\n' if failed_pars else ''
+        msg += '\n\t'.join(['Failed rules:', *failed_rules]) if failed_rules else ''
+        if msg:
+            msg = f'Failed parameters validation for <{self.name}>:\n{msg}'
+            vld is Validate.VERBOSE and print()  # additional line in verbose case
+            print(msg, repr(TBox(par)))
+            if throw and vld is not Validate.REPORT:
+                raise ValueError(msg)
+            return False
+        if vld is not Validate.RAISE:
+            print('OK!')
+        return True
+
+
+@wrap.double_wrap
+def paramaze(func, _alias: str = None,
+             _validate: Union[Rule, Sequence[Rule]] = None,
+             **kws: Rule):
+    """
+    Decorator wrapping function to associate it with `FuncPar` and
+    provide all the related functionality: arguments as parameters with
+    defaults, validation conditions, automatic collection of flow parameters,...
+
+    By default all keyword arguments with defaults are considered parameters.
+    Decorator mau be used with or without arguments, then no conditions or
+    alias is associated with the function, but parameters collections is
+    still available.
+
+    :param func: function to wrap
+    :param _alias: optional (short) version of name to associate with
+                  the parameters structure instead of the function name
+    :param _validate: single or sequence of validation rules in form of
+        a python expression using variables named by the parameters
+        or callable accepting keywords arguments or those parameters.
+    :param kws: dictionary per parameter of validation conditions
+        in form of expression using single variable denoted as "{}" or
+        callable with a single argument to receive the parameter value.
+
+    :return: wrapped function
+
+    Example:
+
+    >>> @paramaze
+    >>> def func(x=10, y=20): pass
+    >>> assert func.defaults == {'x': 10, 'y': 20}
+
+    >>> @paramaze(y="{} > 0",
+    >>>           _validate_type=['x < y', 'x**2 + y**2 < 100'])
+    >>> def func(x=10, y=20): pass
+    >>> assert func.parz.validate(x=2, y=3)
+    """
+    return FuncPar(func, alias=_alias, validate=_validate, directives=kws).function

iad/core/param/tbox.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+from typing import Iterable, Any
+
+import pandas as pd
+import pydantic.v1 as pydantic
+from box import Box
+
+from ..datatools import complete_missing, UndefCond, UndefTypes
+from ..strings import compact_repr, hash_str
+from ..wrap import name_tuple
+
+__all__ = ['TBox', 'UndefCond']
+
+_intact_types = (tuple, list, pd.DataFrame, pd.Series)
+UND_EMPTY = UndefCond(empty_dict=True)
+
+
+class TBox(Box):
+    _protected_keys = Box._protected_keys + [
+        "_flatten",
+        "_repr_json_",
+        "diff",
+        "issubset",
+        "issuperset",
+        "find_key",
+        "remove",
+        "discard",
+        "hash_str"
+    ]
+
+    def __init__(self, *args: pydantic.BaseModel | dict | Iterable[tuple[str, Any]],
+                 undef: UndefTypes = UND_EMPTY, **kw_box):
+        """
+        Initialize hierarchical dict-like structure.
+
+        Note, that argument ``undef`` controlling behavior of ``setdefault``method
+        may be provided in various forms, but is eventually converted into
+        the most complete one: instance of ``UndefCond``:
+         - Collection of undef objects
+         - Callable -> bool
+         - UndefCond (allows to control empty_dict)
+
+        :param args: dicts to initialize with
+        :param kw_box: either key=value pairs as a data items, or Box kw args
+        :param undef: describes condition to consider a node undefined
+        """
+        kw_box.setdefault('box_intact_types', _intact_types)
+        kw_box.setdefault('box_dots', True)  # dotted - default behaviour for TBox !
+
+        if args:  # special conversions
+            args = tuple(arg.dict() if isinstance(arg, pydantic.BaseModel) else arg for arg in args)
+
+        if len(args) > 1:  # Box supports only 1 positional argument, so for more than that
+            dict_arg = {}  # convert all the args into dicts and then merge them into one
+            for arg in args:  # here we deal with dict and Iterable[tuple[k, v]]
+                dict_arg.update(arg)
+            args = (dict_arg,)
+
+        super().__init__(*args, **kw_box)
+        self._box_config['undef'] = undef if isinstance(undef, UndefCond) else UndefCond(undef=undef)
+
+    def __setitem__(self, key, value):
+        # ToDo risky - what about '1.32' or 'file.ext' or relative annotation ..
+        if isinstance(key, str) and '.' in key:
+            node, tail = key.split('.', 1)
+            if node not in self:
+                super().__setitem__(node, {})
+            self[node].__setitem__(tail, value)
+        else:
+            super().__setitem__(key, value)
+
+    def flatten(self):
+        res = []
+        for key, val in self.items():
+            if isinstance(val, Box) and val:
+                for subs, v in val.flatten():
+                    res.append((f'{key}.{subs}', v))
+            else:
+                res.append((key, val))
+        return res
+
+    def _repr_json_(self):
+        jbox = TBox(default_box=True)
+        is_basic = lambda x: x is None or isinstance(x, (str, int, float))
+        for k, v in self.items(True):
+            jbox[k] = v if is_basic(v) or (
+                    isinstance(v, (list, set, tuple))
+                    and len(v) < 5 and all(map(is_basic, v))
+            ) else compact_repr(v)
+        return TBox(jbox)
+
+    def __repr__(self):
+        if not self: return f"{type(self).__name__}()"
+        return '\n'.join(f'{k}: {compact_repr(v)}' for k, v in self.flatten())
+
+    def hash_str(self, length: int = None):
+        """Return hex hash string as unique id of the content.
+
+        :param len: if provided limit string to this length (keep tail)
+        """
+        s = ''
+        for k, v in sorted(self.items(True), key=lambda _: _[0]):
+            if isinstance(v, list):
+                v = [TBox(x).hash_str(length=1000)
+                     if isinstance(x, dict) else x
+                     for x in v]
+            s += f"{k}:{str(v)}\n"
+
+        return hash_str(s, length)
+
+    def __copy__(self, **kws):
+        old_kws = {k: v for k, v in self._box_config.items() if not k.startswith('_')}
+        assert set(kws).issubset(old_kws), "copy only accepts Box standard arguments"
+        old_kws.update(kws)
+        return self.__class__(self.to_dict(), **old_kws)
+
+    # def __deepcopy__(self, memodict={}):
+    #     return self.__copy__()
+
+    def copy(self, **kws):
+        from copy import deepcopy
+        return deepcopy(self)
+
+    def diff(self, other: 'TBox'):
+        """ Difference between two tree forms as tuple of
+         - keys missing in the other,
+         - keys missing in self,
+         - keys of incomparable or not equal values
+        :returns tuple(dif_keys, dif_values)
+
+        """
+
+        def not_same_value(k):
+            try:
+                v1, v2 = other[k], self[k]
+                same = (v1 == v2)
+                if type(same) is not bool:
+                    import numpy as np
+                    same = np.allclose(v1, v2)
+            except Exception:
+                same = False
+            return not same
+
+        other = other if isinstance(other, TBox) else TBox(other)
+        my_keys, other_keys = set(self.keys(True)), set(other.keys(True))
+        missing = my_keys.difference(other_keys)
+        extra = other_keys.difference(my_keys)
+        unequal = {*filter(not_same_value, my_keys.intersection(other_keys))}
+        return name_tuple('TBoxDiffKeys', missing=missing, extra=extra, unequal=unequal)
+
+    def to_yaml(self, filename=None, *, default_flow_style=False,
+                encoding="utf-8", errors="strict", **yaml_kwargs):
+        from ..filesproc import prepare_parent_folder, Path
+
+        par = self.copy()  # type: TBox
+        for k, v in par.items(True):
+            if isinstance(v, Path):
+                par[k] = str(v)
+            if hasattr(v, '__qualname__'):
+                par[k] = v.__qualname__
+
+        if filename:
+            prepare_parent_folder(filename)
+            filename = str(filename)
+
+        return Box.to_yaml(par, filename=filename, default_flow_style=default_flow_style,
+                           encoding=encoding, errors=errors, **yaml_kwargs)
+
+    def setdefault(self, key: str, default: dict | Any, *, undef: UndefTypes = None):
+        """
+        Include support for dotted (nested) keys for `key` arg,
+        and dict-like (also nested) structure for default argument.
+
+        If key is None - setting default for the entire tree, in which case
+        default must be nested dict as well.
+
+        May include check that mandatory fields (values set as TBox.REQUIRED
+        in the default dict) are already defined in self, or raise ValueError.
+
+        :param key: name (also nested) of the field or None for entire tree.
+        :param default: a value to set to specified key
+                        or dict (nested) if key points to a subtree
+        :param undef: override TBox.undef
+        :return: the value been set (or the (sub)tree if default dict is dict
+        """
+        if (sep := '.') in key:
+            assert sep not in (key[0], key[-1]), f"Invalid dotted {key=}!"
+            node = self  # Ensure dotted key node exists and not a leaf
+            for k in key.split(sep):
+                if not isinstance(node, dict):  # every next level must be a dict
+                    raise KeyError(f'Position {k} in {key=} must be a node!')
+                node = Box.setdefault(node, k, {})  # existed or just created
+
+            if isinstance(node, dict) and not node:  # don't consider empty node as set!
+                self[key] = default
+                return self[key]
+
+        default = TBox({key: default} if key else default)
+        undef = getattr(self, '_box_config')['undef'] if undef is None else undef
+        return complete_missing(self, default, undef=undef)
+
+    def issubset(self, other: dict):
+        if not isinstance(other, self.__class__):
+            other = self.__class__(other)
+        return set(self.keys(True)).issubset(other.keys(True))
+
+    def issuperset(self, other: dict):
+        if not isinstance(other, self.__class__):
+            other = self.__class__(other)
+        return set(other.keys(True)).issuperset(self.keys(True))
+
+    def find_key(self, name, *, part='any', multi=False) -> str | list:
+        """
+        Find key(s) with deep (dotted) naming matching given name.
+
+        Return full (dotted) key found or '' if not.
+
+        If multiple matching keys are found return depending on *multi*:
+         - list of them if ``True``
+         - only the first if ``None``
+         - raise ``KeyError`` if ``False``
+
+        :param name: may include dots inside:  "x.y"
+        :param part: key's part to match: ['any'] | 'start' | 'end'
+        :param multi: allow multiple keys to return
+
+        :return: a string or list of strings (keys found)
+        """
+        import re
+        if not re.fullmatch(r'(\w+(\.\w+)?)+', name):
+            return [] if multi else ''
+
+        reg = re.compile({'any': rf'\b{name}\b',
+                          'start': rf'^{name}\b',
+                          'end': rf'\b{name}$'
+                          }[part])
+
+        found = [*filter(reg.search, self.keys(True))]
+        if multi:
+            return found
+        elif len(found) > 1:
+            raise KeyError(f"Multiple matches to {name=} been {found=}!")
+        else:
+            return found[0]
+
+    def remove(self, keys: Iterable[str], *, strict=True):
+        """Remove nodes addressed by the keys (dotted).
+        :param keys: iterable over dotted keys to remove
+        :param strict: if True - raise KeyError if any of keys is missing
+                       otherwise - ignore and remove only found
+        :return: a new TBox with keys removed
+        """
+        if isinstance(keys, str): keys = [keys]
+        res = self.copy()
+        for key in keys:
+            try:
+                del res[key]
+            except KeyError as ex:
+                if strict: raise ex
+        return res
+
+    def discard(self, keys: Iterable[str], *, strict=True):
+        """Discard from this box nodes addressed by given keys (dotted).
+        :param keys: iterable over dotted keys to remove
+        :param strict: if True - raise KeyError if any of keys is missing
+                       otherwise - ignore and remove only found
+        :return: None
+        """
+        if isinstance(keys, str): keys = [keys]
+        if not hasattr(keys, '__len__'):
+            keys = [*keys]
+        valid = [*filter(self.__contains__, keys)]
+        if strict and len(valid) < len(keys):
+            raise KeyError(f"Missing keys: {set(self.keys(True)).difference(valid)}")
+        for key in valid:
+            del self[key]