nested-mapping 0.10.2__py3-none-any.whl

nested_mapping/__init__.py

@@ -0,0 +1,2 @@
+from .nested_mapping import NestedMapping, walkitems, walkkeys, walkvalues
+from .nested_mapping_access import NestedMappingAccess

nested_mapping/class_wrapper.py

@@ -0,0 +1,53 @@
+from typing import Any
+
+
+class ClassWrapper:
+    __slots__ = ("_object", "_types", "_wrapper_class")
+    _object: Any
+    _types: Any
+    _wrapper_class: Any
+
+    def __init__(self, obj, *, types=None):
+        self._object = obj
+        self._types = type(obj) if types is None else types
+        self._wrapper_class = type(self)
+
+    @property
+    def object(self) -> Any:
+        return self._object
+
+    def __str__(self) -> str:
+        return str(self._object)
+
+    def __repr__(self) -> str:
+        return repr(self._object)
+
+    def __dir__(self) -> list[str]:
+        return dir(self._object)
+
+    def __len__(self) -> int:
+        return len(self._object)
+
+    def __bool__(self) -> bool:
+        return bool(self._object)
+
+    def __contains__(self, v) -> bool:
+        return v in self._object
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, ClassWrapper):
+            return self._object == other._object
+
+        return self._object == other
+
+    def _wrap(self, obj, **kwargs) -> Any:
+        if isinstance(obj, ClassWrapper):
+            return obj
+
+        if isinstance(obj, self._types):
+            return self._wrapper_class(obj, **kwargs)
+
+        return obj
+
+    def _wrap_(self, obj, **kwargs) -> Any:
+        return self._wrapper_class(obj, **kwargs)

nested_mapping/ipython.py

@@ -0,0 +1,3 @@
+def repr_pretty(self, p, cycle):
+    """Pretty repr for IPython. To be used as __repr__ method"""
+    p.text("..." if cycle else str(self))

nested_mapping/nested_mapping.py

@@ -0,0 +1,611 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping, Sequence
+from contextlib import suppress
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any, Self
+    from collections.abc import Generator, Iterable
+
+from .class_wrapper import ClassWrapper
+from .ipython import repr_pretty
+from .nested_mapping_access import NestedMappingAccess
+from .typing import KeyLike
+from .visitor import MakeNestedMappingVisitor, NestedMappingVisitor
+
+
+class NestedMapping(ClassWrapper):
+    """Dictionary wrapper managing nested dictionaries.
+
+    The following functionality is implemented:
+    - Tuple keys are treated to access nested dictionaries ('key1', 'key2', 'key3')
+    - Optionally sep symbol may be set to automatically split string keys into tuple keys:
+      'key1.key2.key3' will be treated as a nested key if '.' is set for the sep symbol
+    - self._ may be used to access nested dictionaries via attributes: dw.key1.key2.key3
+    """
+
+    __slots__ = ("_sep", "_parent", "_types", "_not_recursive_to_others")
+    _sep: str | None
+    _parent: Any
+    _not_recursive_to_others: bool
+
+    def __new__(cls, dic: MutableMapping = {}, *args, **kwargs):
+        if not isinstance(dic, (MutableMapping, NestedMapping)):
+            return dic
+        return ClassWrapper.__new__(cls)
+
+    def __init__(
+        self,
+        dic: MutableMapping | None = None,
+        *,
+        sep: str | None = None,
+        parent: Any | None = None,
+        recursive_to_others: bool = False,
+    ):
+        if dic is None:
+            dic = {}
+        if isinstance(dic, NestedMapping):
+            if sep is None:
+                sep = dic._sep
+            recursive_to_others = not dic._not_recursive_to_others
+            dic = dic._object
+        super().__init__(dic, types=type(dic))
+
+        self._sep = sep
+        self._not_recursive_to_others = not recursive_to_others
+        self._parent = parent
+        if parent:
+            if sep and sep != parent._sep:
+                raise ValueError(
+                    f"Inconsistent separators: {sep} (self) and {parent._sep} (parent)"
+                )
+
+            self._sep = parent._sep
+            self._types = parent._types
+            self._not_recursive_to_others = parent._not_recursive_to_others
+
+    def __str__(self):
+        return f"NestedMapping({list(self.keys())})"
+
+    def __repr__(self):
+        return object.__repr__(self)
+
+    _repr_pretty_ = repr_pretty
+
+    def _ipython_key_completions_(self) -> list[str]:
+        return list(self.walkjoinedkeys(include_dicts=True))
+
+    @classmethod
+    def from_flatdict(
+        cls,
+        dct: Mapping[KeyLike, Any] | Iterable[tuple[KeyLike, Any]],
+        *args,
+        **kwargs,
+    ) -> Self:
+        """Make a nested dictionary from a flat dictionary."""
+        ret = cls({}, *args, **kwargs)
+        iterable = dct.items() if isinstance(dct, Mapping) else dct
+        for key, value in iterable:
+            ret[key] = value
+        return ret
+
+    @property
+    def _(self):
+        return NestedMappingAccess(self)
+
+    @property
+    def parent(self) -> Self | None:
+        return self._parent
+
+    @property
+    def parent_key(self):
+        if not self._parent:
+            return None
+        for key, value in self._parent.items():
+            if isinstance(value, NestedMapping) and value.object is self.object:
+                return key
+
+        raise RuntimeError("Parent key not identified")
+
+    def get_parent(self, level: int = 1) -> Self | None:
+        if level == 0:
+            return self
+        elif level < 0:
+            raise ValueError("get_parent: level should be >=0")
+
+        current = self
+        for _ in range(level):
+            newcurrent = current.parent
+            if newcurrent is None:
+                return current
+            current = newcurrent
+
+        return current
+
+    def create_child(self, key, *args, type=None, **kwargs) -> Self:
+        try:
+            ret = self(key)
+        except KeyError:
+            if type is None:
+                type = self._types
+            self[key] = (ret := type(*args, **kwargs))
+            return self._wrap(ret, parent=self)
+
+        if not isinstance(ret, self._wrapper_class):
+            raise KeyError(f"Child {key!s} is not NestedMapping")
+
+        return ret
+
+    def get_dict(self, key, *, unwrap: bool = False) -> Self:
+        if key == ():
+            return self
+        head, rest = self.splitkey(key)
+
+        try:
+            sub = self._object[head]
+        except KeyError as e:
+            raise KeyError(key) from e
+
+        if rest:
+            sub = self._wrap(sub, parent=self)
+            if self._not_recursive_to_others and not isinstance(sub, NestedMapping):
+                raise TypeError(
+                    f"Expect nested dictionary as value for {key}, got {type(sub).__name__}"
+                )
+
+            try:
+                return sub.get_dict(rest, unwrap=unwrap)
+            except KeyError as e:
+                raise KeyError(key) from e
+
+        if not isinstance(sub, (ClassWrapper, self._types)):
+            raise TypeError(
+                f"Invalid value type {type(sub)} for key ({key}). Expect non-mapping. Perhaps, one should use [{key}] or .get_any({key})..."
+            )
+
+        if unwrap:
+            return sub
+
+        return self._wrap_(sub, parent=self)
+
+    __call__ = get_dict
+
+    def keys(self):
+        return self._object.keys()
+
+    def iterkey(self, key):
+        if isinstance(key, str):
+            if self._sep:
+                yield from key.split(self._sep)
+            else:
+                yield key
+        elif isinstance(key, Sequence):
+            for sk in key:
+                yield from self.iterkey(sk)
+        else:
+            yield key
+
+    def splitkey(self, key) -> Any:
+        it = self.iterkey(key)
+        try:
+            return next(it), tuple(it)
+        except StopIteration:
+            return None, None
+
+    def joinkey(self, key: KeyLike) -> str:
+        if isinstance(key, str):
+            return key
+        elif isinstance(key, Sequence):
+            if self._sep is None:
+                raise ValueError("sep is None")
+            return self._sep.join(key)
+
+        raise ValueError(f"Invalid key: {key}")
+
+    def get(self, key, default=None):
+        if key == ():
+            raise TypeError("May not return self")
+
+        head, rest = self.splitkey(key)
+
+        if head not in self._object:
+            if rest:
+                raise KeyError(key)
+            else:
+                return default
+
+        sub = self._object.get(head)
+        if rest:
+            sub = self._wrap(sub, parent=self)
+            if self._not_recursive_to_others and not isinstance(sub, NestedMapping):
+                raise TypeError(
+                    f"Expect non-mapping as value for {key}, got {type(sub).__name__}"
+                )
+
+            return sub.get(rest, default)
+
+        if isinstance(sub, (ClassWrapper, self._types)):
+            raise TypeError(
+                f"Invalid value type {type(sub)} for key [{key}]. Expect non-mapping. Perhaps, one should use ({key}) or .get_any({key})..."
+            )
+
+        return sub
+
+    def get_value(self, key) -> Any:
+        if key == ():
+            raise TypeError("May not return self")
+
+        head, rest = self.splitkey(key)
+
+        try:
+            sub = self._object.__getitem__(head)
+        except KeyError as e:
+            raise KeyError(f"{key}: {head}") from e
+
+        if rest:
+            sub = self._wrap(sub, parent=self)
+            if self._not_recursive_to_others and not isinstance(sub, NestedMapping):
+                raise TypeError(
+                    f"Expect non-mapping as value for {key}, got {type(sub).__name__}"
+                )
+
+            try:
+                return sub.get_value(rest)
+            except KeyError as e:
+                failed_rest = getattr(e, "rest", rest)
+                error = KeyError(f"{key}: {failed_rest}")
+                with suppress(RuntimeError):
+                    error.rest = (  # pyright: ignore [reportAttributeAccessIssue]
+                        failed_rest
+                    )
+                raise error from e
+
+        if isinstance(sub, (ClassWrapper, self._types)):
+            raise TypeError(
+                f"Invalid value type {type(sub)} for key {key}. Expect non-mapping."
+            )
+        return sub
+
+    def get_any(self, key, *, unwrap: bool = False) -> Any:
+        if key == ():
+            return self
+        head, rest = self.splitkey(key)
+
+        try:
+            sub = self._object.__getitem__(head)
+        except KeyError as e:
+            raise KeyError(f"No nested key '{key}'") from e
+
+        if not rest:
+            if unwrap:
+                return sub
+            sub = self._wrap(sub, parent=self)
+            return sub
+
+        sub = self._wrap(sub, parent=self)
+        if self._not_recursive_to_others and not isinstance(sub, NestedMapping):
+            raise TypeError(f"Nested value for {key} has wrong type")
+
+        try:
+            return sub.get_any(rest, unwrap=unwrap) if unwrap else sub[rest]
+        except KeyError as e:
+            raise KeyError(key) from e
+
+    __getitem__ = get_any
+
+    def pop(self, key, *, delete_parents: bool = False):
+        if key == ():
+            raise ValueError("May not delete itself")
+        key, rest = self.splitkey(key)
+
+        sub = self._wrap(self._object.__getitem__(key), parent=self)
+        if not rest:
+            return self._object.pop(key)
+
+        if self._not_recursive_to_others and not isinstance(sub, NestedMapping):
+            raise TypeError(f"Nested value for {key} has wrong type")
+
+        ret = sub.pop(rest, delete_parents=delete_parents)
+        if delete_parents and not sub:
+            del self._object[key]
+        return ret
+
+    def delete_with_parents(self, key):
+        self.pop(key, delete_parents=True)
+
+    def __delitem__(self, key):
+        if key == ():
+            raise ValueError("May not delete itself")
+        key, rest = self.splitkey(key)
+
+        if not rest:
+            del self._object[key]
+            return
+
+        if key not in self:
+            raise KeyError(key)
+
+        sub = self._wrap(self._object.__getitem__(key), parent=self)
+        if isinstance(sub, NestedMapping):
+            sub.__delitem__(rest)
+            return
+
+        if self._not_recursive_to_others:
+            raise TypeError(f"Nested value for {key} (sub: {rest}) has wrong type")
+
+        sub.__delitem__(rest)
+
+    def setdefault(self, key, value) -> Any:
+        key, rest = self.splitkey(key)
+
+        if not rest:
+            ret = self._object.setdefault(key, value)
+            return self._wrap(ret, parent=self)
+
+        if key in self:
+            sub = self._wrap(self._object.get(key), parent=self)
+        else:
+            sub = self._object[key] = self._types()
+            sub = self._wrap(sub, parent=self)
+            # # cfg._set_parent( self )
+
+        if self._not_recursive_to_others and not isinstance(sub, NestedMapping):
+            raise TypeError(f"Nested value for {key} has wrong type")
+
+        return sub.setdefault(rest, value)
+
+    def _set(self, key, value):
+        key, rest = self.splitkey(key)
+
+        if not rest:
+            self._object[key] = value
+            return value
+
+        if key in self:
+            sub = self._wrap(self._object.get(key), parent=self)
+        else:
+            sub = self._object[key] = self._types()
+            sub = self._wrap(sub, parent=self)
+            # # cfg._set_parent( self )
+
+        if isinstance(sub, NestedMapping):
+            return sub._set(rest, value)
+
+        if self._not_recursive_to_others:
+            raise TypeError(f"Nested value for {key} (sub: {rest}) has wrong type")
+
+        return sub.__setitem__(rest, value)
+
+    def set(self, key, value):
+        return self._set(key, value)
+
+    __setitem__ = set
+
+    def __contains__(self, key):
+        if key == ():
+            return True
+        key, rest = self.splitkey(key)
+
+        if key not in self._object:
+            return False
+
+        if rest:
+            sub = self._wrap(self._object.get(key), parent=self)
+
+            if self._not_recursive_to_others and not isinstance(sub, NestedMapping):
+                raise TypeError(f"Nested value for {key} is not a nested dictionary")
+
+            return rest in sub
+
+        return True
+
+    def items(self):
+        for k, v in self._object.items():
+            yield k, self._wrap(v, parent=self)
+
+    def values(self):
+        for v in self._object.values():
+            yield self._wrap(v, parent=self)
+
+    def copy(self) -> Self:
+        cls = type(self)
+        return cls(
+            self.object.copy(),
+            parent=self._parent,
+            sep=self._sep,
+            recursive_to_others=not self._not_recursive_to_others,
+        )
+
+    def deepcopy(self) -> Self:
+        cls = type(self)
+        new = cls(
+            self._types(),
+            parent=self._parent,
+            sep=self._sep,
+            recursive_to_others=not self._not_recursive_to_others,
+        )
+        for k, v in self.items():
+            k = (k,)
+            if isinstance(v, self._wrapper_class):
+                new[k] = v.deepcopy()._object
+            else:
+                new[k] = v
+
+        new._sep = self._sep
+
+        return new
+
+    def flatten(self, sep: str | None = None) -> dict[str, Any]:
+        return dict(self.walkjoineditems(sep=sep))
+
+    def walkitems(
+        self,
+        startfromkey=(),
+        *,
+        include_dicts: bool = False,
+        appendstartkey: bool = False,
+        maxdepth: int | None = None,
+    ):
+        v0 = self.get_any(startfromkey)
+        k0 = tuple(self.iterkey(startfromkey))
+
+        if maxdepth is None:
+            nextdepth = None
+        else:
+            nextdepth = max(maxdepth - len(k0) - 1, 0)
+
+        if maxdepth == 0 or not isinstance(v0, self._wrapper_class):
+            if appendstartkey:
+                yield k0, v0
+            else:
+                yield (), v0
+            return
+
+        if not appendstartkey:
+            k0 = ()
+
+        for k, v in v0.items():
+            k = k0 + (k,)
+            if isinstance(v, self._wrapper_class):
+                if include_dicts:
+                    yield k, v
+                for k1, v1 in v.walkitems(
+                    include_dicts=include_dicts, maxdepth=nextdepth
+                ):
+                    yield k + k1, v1
+            elif not self._not_recursive_to_others and isinstance(v, Mapping):
+                if include_dicts:
+                    yield k, v
+                for k1, v1 in v.items():
+                    if isinstance(k1, tuple):
+                        yield k + k1, v1
+                    else:
+                        yield k + (k1,), v1
+            else:
+                yield k, v
+
+    def walkdicts(self, *, yieldself=False, ignorekeys: Sequence = ()):
+        for k, v in self.items():
+            if k in ignorekeys:
+                continue
+            k = (k,)
+            if isinstance(v, self._wrapper_class):
+                yieldself = False
+                for k1, v1 in v.walkdicts(yieldself=True, ignorekeys=ignorekeys):
+                    yield k + k1, v1
+        if yieldself:
+            yield (), self
+
+    def keysmap(self) -> NestedMapping:
+        """Return a nested dictionary instance with similar structure, but
+        dictionaries are replaced with tuples of their keys."""
+        return NestedMapping.from_flatdict(
+            {k: tuple(dct.keys()) for k, dct in self.walkdicts()}
+        )
+
+    def unique_key_parts(self) -> set[str]:
+        """Return a set with all the unique set parts."""
+        ret = set()
+        for key in self.walkkeys():
+            ret.update(key)
+        return ret
+
+    def walkkeys(self, *args, **kwargs):
+        for k, _ in self.walkitems(*args, **kwargs):
+            yield k
+
+    def walkjoinedkeys(
+        self, *args, sep: str | None = None, **kwargs
+    ) -> Generator[str, None, None]:
+        if sep is None:
+            sep = self._sep
+        if sep is None:
+            sep = "."
+        for k, _ in self.walkitems(*args, **kwargs):
+            yield sep.join(k)
+
+    def walkjoineditems(
+        self, *args, sep: str | None = None, **kwargs
+    ) -> Generator[tuple[str, Any], None, None]:
+        if sep is None:
+            sep = self._sep
+        if sep is None:
+            sep = "."
+        for k, v in self.walkitems(*args, **kwargs):
+            yield sep.join(k), v
+
+    def walkvalues(self, *args, **kwargs):
+        for _, v in self.walkitems(*args, **kwargs):
+            yield v
+
+    def len_recursive(self, *args, **kwargs) -> int:
+        return sum(1 for _ in self.walkitems(*args, **kwargs))
+
+    def depth(self):
+        return max(len(k) for k, _ in self.walkitems())
+
+    def visit(self, visitor, parentkey=()) -> NestedMappingVisitor:
+        visitor = MakeNestedMappingVisitor(visitor)
+
+        if not parentkey:
+            visitor.start(self)
+
+        visitor.enterdict(parentkey, self)
+        for k, v in self.items():
+            key = parentkey + (k,)
+            if isinstance(v, self._wrapper_class):
+                v.visit(visitor, parentkey=key)
+            else:
+                visitor.visit(key, v)
+
+        visitor.exitdict(parentkey, self)
+
+        if not parentkey:
+            visitor.stop(self)
+
+        return visitor
+
+    def update(self, other) -> Self:
+        other = self._wrap(other)
+        for k, v in other.walkitems():
+            self[k] = v
+        return self
+
+    __ior__ = update
+
+    def update_missing(self, other) -> Self:
+        other = self._wrap(other)
+        for k, v in other.walkitems():
+            try:
+                key_already_present = k in self
+            except TypeError as e:
+                raise TypeError(f"Value for part({k}) is non nestable") from e
+            else:
+                if key_already_present:
+                    raise TypeError(f"Key {k} already present")
+            self[k] = v
+        return self
+
+    __ixor__ = update_missing
+
+
+def walkitems(obj: NestedMapping | Any, *args, **kwargs):
+    if isinstance(obj, NestedMapping):
+        yield from obj.walkitems(*args, **kwargs)
+    else:
+        yield (), obj
+
+
+def walkvalues(obj: NestedMapping | Any, *args, **kwargs):
+    if isinstance(obj, NestedMapping):
+        yield from obj.walkvalues(*args, **kwargs)
+    else:
+        yield obj
+
+
+def walkkeys(obj: NestedMapping | Any, *args, **kwargs):
+    if isinstance(obj, NestedMapping):
+        yield from obj.walkkeys(*args, **kwargs)
+    else:
+        yield ()

nested_mapping/nested_mapping_access.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .ipython import repr_pretty
+
+if TYPE_CHECKING:
+    from .nested_mapping import NestedMapping
+
+
+class NestedMappingAccess:
+    """NestedMapping wrapper. Enables attribute based access to nested dictionaries"""
+
+    __slots__ = ("_",)
+    _: NestedMapping
+
+    def __init__(self, dct: NestedMapping):
+        object.__setattr__(self, "_", dct)
+
+    def __str__(self):
+        return str(self._)
+
+    _repr_pretty_ = repr_pretty
+
+    def __call__(self, key):
+        return self._.create_child(key)._
+
+    def __getattr__(self, key):
+        if key.startswith("__") and key.endswith("__"):
+            # needed for proper operation of __dir__() and ipython completion
+            return object.__getattr__(self, key)
+
+        ret = self._[key]
+
+        if isinstance(ret, self._._wrapper_class):
+            return ret._
+
+        return ret
+
+    def __setattr__(self, key, value):
+        self._[key] = value
+
+    def __delattr__(self, key):
+        del self._[key]
+
+    def __dir__(self):
+        return list(self._.keys())

nested_mapping/tools/__init__.py

@@ -0,0 +1,4 @@
+from .filter import filter_items
+from .map import remap_items, mkmap
+from .match import match_keys
+from .reorder_key import reorder_key

nested_mapping/tools/filter.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..nested_mapping import NestedMapping
+
+from ..typing import Key
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+    from typing import Any, Generator
+
+
+def filter_items(
+    items: Iterable[tuple[Key, Any]], exclude: Sequence[Sequence[str] | str]
+) -> Generator[tuple[Key, Any]]:
+    _exclude = [{key} if isinstance(key, str) else set(key) for key in exclude]
+    for key, value in items:
+        if any(mask.issubset(key) for mask in _exclude):
+            continue
+
+        yield key, value
+
+
+def mkfilter_items(
+    mkdict: NestedMapping, exclude: Sequence[Sequence[str] | str]
+) -> NestedMapping:
+    ret = mkdict.__class__({}, sep=mkdict._sep)
+
+    for key, value in filter_items(mkdict.walkitems(), exclude):
+        ret[key] = value
+
+    return ret
+

nested_mapping/tools/map.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..nested_mapping import NestedMapping
+from ..typing import setkey
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+    from typing import Any
+
+    from ..typing import Key, KeyLike
+
+
+def mkmap(
+    fcn: Callable,
+    arg0: NestedMapping,
+    *args: NestedMapping,
+    sep: int | str | bool | None = None,
+) -> NestedMapping:
+    match sep:
+        case False:
+            # False matches case 0, but 0 does not match case False
+            sep = None
+        case 0 | True:
+            sep = arg0._sep
+        case int():
+            if sep > 0:
+                sep = args[sep - 1]._sep
+            elif sep >= -len(args):
+                sep = args[sep]._sep
+            else:
+                raise IndexError()
+        case str() | None:
+            pass
+        case _:
+            raise TypeError(f"Invalid sep: {sep}")
+    ret = NestedMapping({}, sep=sep)
+    for key, value0 in arg0.walkitems():
+        values = (arg[key] for arg in args)
+        ret[key] = fcn(value0, *values)
+    return ret
+
+
+def remap_items(
+    source: NestedMapping,
+    target: NestedMapping | None = None,
+    *,
+    rename_indices: Mapping[str, Sequence[str]] | None = None,
+    reorder_indices: (
+        tuple[int]
+        | tuple[tuple[str, ...], tuple[str, ...]]
+        | list[int]
+        | list[list[str]]
+        | Mapping[str, list[str] | tuple[str]]
+        | None
+    ) = None,
+    skip_indices_source: Sequence[KeyLike | set] | None = None,
+    skip_indices_target: Sequence[KeyLike | set] | None = None,
+    fcn: Callable[[Any], Any] | None = None,
+    verbose: bool = False,
+) -> NestedMapping:
+    from itertools import product
+
+    if target is None:
+        target = NestedMapping()
+
+    skip_source = _make_skip_fcn(skip_indices_source)
+    skip_target = _make_skip_fcn(skip_indices_target)
+    reorder = make_reorder_function(reorder_indices)
+
+    if fcn is None:
+        fcn = lambda o: o
+        has_fcn = False
+    else:
+        has_fcn = True
+
+    if rename_indices is not None:
+        for key, value in source.walkitems():
+            if skip_source(key):
+                continue
+            for newkey in product(
+                *tuple(rename_indices.get(skey, (skey,)) for skey in key)
+            ):
+                newkey_ordered = reorder(newkey)
+                if skip_target(newkey_ordered):
+                    if verbose:
+                        print(
+                            f"remap: skip {'.'.join(key)} → {'.'.join(newkey_ordered)}"
+                        )
+                    continue
+                if verbose:
+                    print(
+                        f"remap {'(fcn) ' if has_fcn else ''}{'.'.join(key)} → {'.'.join(newkey_ordered)}"
+                    )
+                target[newkey_ordered] = fcn(value)
+    else:
+        for key, value in source.walkitems():
+            newkey_ordered = reorder(key)
+            if skip_target(newkey_ordered):
+                if verbose:
+                    print(f"remap: skip {'.'.join(key)} → {'.'.join(newkey_ordered)}")
+                continue
+            if verbose:
+                print(
+                    f"remap {'(fcn) ' if has_fcn else ''}{'.'.join(key)} → {'.'.join(newkey_ordered)}"
+                )
+            target[newkey_ordered] = fcn(value)
+
+    return target
+
+
+def _make_skip_fcn(
+    skip_indices: Sequence[KeyLike | set] | None,
+) -> Callable[[Key], bool]:
+    if skip_indices is not None:
+        skip_sets: tuple[set[str], ...] = tuple(
+            sq if isinstance(sq, set) else setkey(sq) for sq in skip_indices
+        )
+        return lambda key: any(ss.issubset(key) for ss in skip_sets)
+
+    return lambda _: False
+
+
+def make_reorder_function(
+    reorder_indices: (
+        tuple[int]
+        | tuple[tuple[str, ...], tuple[str, ...]]
+        | Sequence[int]
+        | Sequence[Sequence[str]]
+        | Mapping[str, list[str] | tuple[str]]
+        | None
+    ),
+    *,
+    allow_skip_items: bool = False,
+) -> Callable:
+    match reorder_indices:
+        case [int(), *_]:
+            index_order = reorder_indices
+            len_from = len(index_order)
+        case [[str(), *_] as order_from, [str(), *_] as order_to] | {
+            "from": [str(), *_] as order_from,
+            "to": [str(), *_] as order_to,
+        }:
+            len_from = len(order_from)
+            try:
+                index_order = tuple(order_from.index(item) for item in order_to)
+            except ValueError:
+                raise ValueError(
+                    f"Inconsistent order definitions {order_from} and {order_to}"
+                )
+        case None:
+            len_from = None
+            allow_skip_items = True
+            return lambda key: key
+        case _:
+            raise ValueError(f"Invalid order specification: {reorder_indices}")
+
+    def reorder_indices(key: Sequence):
+        if not allow_skip_items and len(key) != len_from:
+            raise ValueError(
+                f"inconsistent index length: {len(index_order)} vs required {len(key)}"
+            )
+        return key.__class__(key[idx] for idx in index_order)
+
+    return reorder_indices

nested_mapping/tools/match.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import TYPE_CHECKING, Any
+
+from ordered_set import OrderedSet
+
+from ..typing import Key, KeyLike, TupleKey, properkey, setkey
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Sequence
+
+
+def match_keys(
+    keys_left_seq: Sequence[Sequence[KeyLike]],
+    keys_right: Iterable[KeyLike],
+    fcn: Callable[[int, TupleKey, TupleKey], Any],
+    *,
+    fcn_outer_before: Callable[[TupleKey], Any] | None = None,
+    fcn_outer_after: Callable[[TupleKey], Any] | None = None,
+    fcn_skip: Callable[[int, TupleKey, TupleKey], Any] | None = None,
+    left_in_right: bool = True,
+    right_in_left: bool = True,
+    require_all_right_keys_processed: bool = True,
+    require_all_left_keys_processed: bool = True,
+    skippable_left_keys_should_contain: Sequence[KeyLike] | None = None,
+) -> None:
+    if isinstance(keys_right, str):
+        raise RuntimeError("`keys_right` should be iterable, but not string")
+    if not keys_left_seq:
+        raise RuntimeError("Left sequence is empty")
+
+    if left_in_right and right_in_left:
+
+        def keys_consistent(left: set, right: set) -> bool:
+            return left.issubset(right) or right.issubset(left)
+
+    elif left_in_right:
+
+        def keys_consistent(left: set, right: set) -> bool:
+            return left.issubset(right)
+
+    elif right_in_left:
+
+        def keys_consistent(left: set, right: set) -> bool:
+            return right.issubset(left)
+
+    else:
+        raise RuntimeError("Either right_in_left or left_in_right should be True")
+
+    skipped_right_keys = []
+    processed_left_keys = set()
+    skipped_left_keys = set()
+
+    collect_skipped_left_keys = (
+        require_all_left_keys_processed or skippable_left_keys_should_contain
+    )
+
+    for key_right in keys_right:
+        key_right_proper = properkey(key_right)
+        setkey_right = OrderedSet(key_right_proper)
+        if fcn_outer_before is not None:
+            fcn_outer_before(key_right_proper)
+
+        right_processed = False
+        for i_left, keys_left in enumerate(keys_left_seq):
+            for key_left in keys_left:
+                if key_left:
+                    key_left_proper = properkey(key_left)
+                    setkey_left = OrderedSet(key_left_proper)
+                    if not keys_consistent(setkey_left, setkey_right):
+                        if (
+                            collect_skipped_left_keys
+                            and key_left_proper not in processed_left_keys
+                        ):
+                            skipped_left_keys.add(key_left_proper)
+                        if fcn_skip:
+                            fcn_skip(i_left, key_left_proper, key_right_proper)
+                        continue
+                else:
+                    key_left_proper = ()
+
+                fcn(i_left, key_left_proper, key_right_proper)
+                right_processed = True
+
+                if collect_skipped_left_keys:
+                    with suppress(KeyError):
+                        skipped_left_keys.remove(key_left_proper)
+                    processed_left_keys.add(key_left_proper)
+
+        if fcn_outer_after is not None:
+            fcn_outer_after(key_right_proper)
+
+        if not right_processed:
+            skipped_right_keys.append(key_right_proper)
+
+    if skipped_left_keys:
+        if require_all_left_keys_processed:
+            raise ValueError(
+                f"match_keys: there were unprocessed left keys {skipped_left_keys!s}"
+            )
+        failure, incorrectly_skipped_key = _check_skipped_keys_incorrect(
+            skipped_left_keys, skippable_left_keys_should_contain
+        )
+        if failure:
+            raise ValueError(
+                f"match_keys: there were unprocessed left keys {skipped_left_keys!s}. "
+                f"{incorrectly_skipped_key} should not have been skipped."
+            )
+
+    if require_all_right_keys_processed and skipped_right_keys:
+        raise ValueError(
+            f"match_keys: there were unprocessed right keys {skipped_right_keys!s}"
+        )
+
+
+def _check_skipped_keys_incorrect(
+    skipped_keys: Sequence[Key] | set[Key], should_contain: Sequence[KeyLike] | None
+) -> tuple[bool, Key | None]:
+    if not should_contain:
+        return False, None
+
+    setkeys = tuple(setkey(keypart) for keypart in should_contain)
+    for skipped_key in skipped_keys:
+        if not any(setkey.issubset(skipped_key) for setkey in setkeys):
+            return True, skipped_key
+
+    return False, None

nested_mapping/tools/reorder_key.py

@@ -0,0 +1,9 @@
+from collections.abc import Sequence
+
+from ..typing import TupleKey
+
+
+def reorder_key(key: TupleKey, key_order: Sequence[int] | None = None):
+    if key_order is None:
+        return key
+    return tuple(key[i] for i in key_order)

nested_mapping/typing.py

@@ -0,0 +1,41 @@
+from collections.abc import Sequence
+
+from ordered_set import OrderedSet
+
+TupleKey = tuple[str, ...]
+Key = str | tuple[str, ...]
+KeyLike = str | Sequence[str]
+
+
+def properkey(key: KeyLike, *, sep: str | bool | None = None) -> TupleKey:
+    if isinstance(key, str):
+        if isinstance(sep, str):
+            return tuple(key.split(sep))
+        elif sep is True:
+            return tuple(key.split("."))
+        return (key,)
+    if isinstance(key, tuple):
+        return key
+
+    return tuple(key)
+
+
+def orderedsetkey(key: KeyLike) -> OrderedSet[str]:
+    if isinstance(key, str):
+        return OrderedSet((key,))
+
+    return OrderedSet(key)
+
+
+def setkey(key: KeyLike) -> set[str]:
+    if isinstance(key, str):
+        return set((key,))
+
+    return set(key)
+
+
+def strkey(key: KeyLike, *, sep=".") -> str:
+    if isinstance(key, str):
+        return key
+
+    return sep.join(key)

nested_mapping/visitor.py

@@ -0,0 +1,65 @@
+class NestedMappingVisitor:
+    def start(self, d):
+        pass
+
+    def enterdict(self, k, d):
+        pass
+
+    def visit(self, k, v):
+        pass
+
+    def exitdict(self, k, d):
+        pass
+
+    def stop(self, d):
+        pass
+
+
+def MakeNestedMappingVisitor(fcn):
+    if isinstance(fcn, NestedMappingVisitor):
+        return fcn
+
+    if not callable(fcn):
+        raise TypeError(f"Expect function, got {type(fcn).__name__}")
+
+    ret = NestedMappingVisitor()
+    ret.visit = fcn
+    return ret
+
+
+class NestedMappingVisitorDemostrator(NestedMappingVisitor):
+    fmt = "{action:7s} {depth!s:>5s} {key!s:<{keylen}s} {vtype!s:<{typelen}s} {value}"
+    opts = dict(keylen=20, typelen=15)
+
+    def typestring(self, v):
+        return type(v).__name__
+
+    def start(self, d):
+        v = object.__repr__(d.object)
+        print("Start printing dictionary:", v)
+        self._print("Action", "Key", "Value", "Type", depth="Depth")
+
+    def stop(self, d):
+        print("Done printing dictionary")
+
+    def enterdict(self, k, d):
+        d = d.object
+        v = object.__repr__(d)
+        self._print("Enter", k, v, self.typestring(d))
+
+    def exitdict(self, k, d):
+        d = d.object
+        v = object.__repr__(d)
+        self._print("Exit", k, v, self.typestring(d))
+
+    def visit(self, k, v):
+        self._print("Visit", k, v, self.typestring(v))
+
+    def _print(self, action, k, v, vtype, *, depth=None):
+        if depth is None:
+            depth = len(k)
+        print(
+            self.fmt.format(
+                action=action, depth=depth, key=k, vtype=vtype, value=v, **self.opts
+            )
+        )

nested_mapping-0.10.2.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: nested-mapping
+Version: 0.10.2
+Summary: Package to work with nested dictionaries supporing list/set as keys
+Author-email: DAGModelling Team <dagflow@jinr.ru>
+Maintainer-email: DAGModelling Team <dagflow@jinr.ru>
+License-Expression: MIT
+Project-URL: Bug Tracker, https://github.com/dagflow-team/nested-mapping/issues
+Project-URL: DAGModelling Team, https://github.com/dagflow-team
+Project-URL: documentation, https://github.com/dagflow-team/nested-mapping/wiki
+Project-URL: homepage, https://github.com/dagflow-team/nested-mapping
+Project-URL: repository, https://github.com/dagflow-team/nested-mapping
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: ordered-set
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# Summary
+
+[![python](https://img.shields.io/badge/python-3.11-purple.svg)](https://www.python.org/)
+[![pipeline](https://git.jinr.ru/dagflow-team/nested-mapping/badges/master/pipeline.svg)](https://git.jinr.ru/dagflow-team/nested-mapping/commits/master)
+[![coverage report](https://git.jinr.ru/dagflow-team/nested-mapping/badges/master/coverage.svg)](https://git.jinr.ru/dagflow-team/nested-mapping/-/commits/master)
+<!--- Uncomment here after adding docs!
+[![pages](https://img.shields.io/badge/pages-link-white.svg)](http://dagflow-team.pages.jinr.ru/nested-mapping)
+-->
+
+A package to work with nested dictionaries.
+
+# Repositories
+
+- Development/CI: https://git.jinr.ru/dagflow-team/nested-mapping
+- Contact/pypi/mirror: https://github.com/dagflow-team/nested-mapping
+- PYPI: https://pypi.org/project/nested-mapping

nested_mapping-0.10.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+nested_mapping/__init__.py,sha256=7Gq8elq0zdqKY-057qHaqHgegUvKyfmHsrd6NG-VHlI,130
+nested_mapping/class_wrapper.py,sha256=Z3FCAgJRSvs_meJi1bhdmCWvhRSKhydsDUSbDqLRii4,1296
+nested_mapping/ipython.py,sha256=3NrXcLYrKD_kGxqwQp3m2BcQD7Z0AO8PTLWYB0PAaL8,140
+nested_mapping/nested_mapping.py,sha256=rJq-PV60ivoc9DIIW0q-sUMEByr_9u78LLEdY5F0zEA,18647
+nested_mapping/nested_mapping_access.py,sha256=tqZICim76cw2BCVYhHom8i7FdQHSOcqDM87lVxJ6baI,1097
+nested_mapping/typing.py,sha256=1tDcM7oTn84qNfYYqN-pmS1wteuv4G6iv3HCmSkYkuk,884
+nested_mapping/visitor.py,sha256=tWnC0AnaRTUqrh0KWyVkptfOMC92kk_JORgVtJIJAro,1620
+nested_mapping/tools/__init__.py,sha256=oIPmTYpkUX5wVvSQI5iWQM_AmC6fge_thx4mHXPpe_E,136
+nested_mapping/tools/filter.py,sha256=gfRzzB48iOFh38YkZfW1FNAS9EFVBTwSp_GHP4lw5eE,854
+nested_mapping/tools/map.py,sha256=VOVap62aTjo2iZ6AuEoyaJXlULeUZjNYoJSMkiDUpYs,5197
+nested_mapping/tools/match.py,sha256=jWaiETpkYMQ1NMUX5ngpnwBt7hlciO0C5RUG9Nmnk7k,4547
+nested_mapping/tools/reorder_key.py,sha256=OZ3ABamLbjPgZ-khhSn8bmT73udPDyuc8jjTqSjzsRU,231
+nested_mapping-0.10.2.dist-info/licenses/LICENSE,sha256=qtOApKX08hit4Gzn_0_WXOvdk55eFcw9AcWV_7ryXBQ,1088
+nested_mapping-0.10.2.dist-info/METADATA,sha256=vfEJbvDtoNLGdZA7xyvua6JQV8BF5X3yx57yG8azz18,1960
+nested_mapping-0.10.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nested_mapping-0.10.2.dist-info/top_level.txt,sha256=82tAUnkF7Kr5kXFDpsg49V_CcnjjjlP1TfnN4GUV-IY,15
+nested_mapping-0.10.2.dist-info/RECORD,,

nested_mapping-0.10.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nested_mapping-0.10.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gonchar Maxim, Tsegelnik Nikita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nested_mapping-0.10.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+nested_mapping