NestedDict¶

Bases: DefaultDict

NestedDict further extends DefaultDict object by introducing a nested structure with delimiter. By default, delimiter is ., but it could be modified in subclass or by calling dict.setattr('delimiter', D).

d = NestedDict({"a.b.c": 1}) is equivalent to d = NestedDict({"a": {"b": {"c": 1}}}), and you can access members either by d["a.b.c"] or more simply by d.a.b.c.

This behavior allows you to pass keyword arguments to other function as easy as func1(**d.func1).

Since NestedDict inherits from DefaultDict, it also supports default_factory. With default_factory, you can assign d.a.b.c = 1 without assign d.a = NestedDict() in the first place. Note that the constructor of NestedDict is different from DefaultDict, default_factory is not a positional argument, and must be set in a keyword argument.

NestedDict also introduce all_keys, all_values, all_items methods to get all keys, values, items respectively in the nested structure.

Attributes:

Name	Type	Description
`convert_mapping`	`bool`	bool = False If `True`, all new values with a type of `Mapping` will be converted to `default_factory`. If `default_factory` is `Null`, will create an empty instance via `self.empty` as `default_factory`.
`delimiter`	`str`	str = “.” Delimiter for nested structure.

Notes

When convert_mapping specified, all new values with type of Mapping will be converted to default_factory. If default_factory is Null, will create an empty instance via self.empty as default_factory.

convert_mapping is automatically applied to arguments during initialisation.

Examples:

Python Console Session

>>> NestedDict({"f.n": "chang"})
NestedDict(
  ('f'): NestedDict(
    ('n'): 'chang'
  )
)
>>> d = NestedDict({"f.n": "chang"}, default_factory=NestedDict)
>>> d.i.d = 1013
>>> d['i.d']
1013
>>> d.i.d
1013
>>> d.dict()
{'f': {'n': 'chang'}, 'i': {'d': 1013}}

Source code in chanfig/nested_dict.py

Python
class NestedDict(DefaultDict):
    r"""
    `NestedDict` further extends `DefaultDict` object by introducing a nested structure with `delimiter`.
    By default, `delimiter` is `.`, but it could be modified in subclass or by calling `dict.setattr('delimiter', D)`.

    `d = NestedDict({"a.b.c": 1})` is equivalent to `d = NestedDict({"a": {"b": {"c": 1}}})`,
    and you can access members either by `d["a.b.c"]` or more simply by `d.a.b.c`.

    This behavior allows you to pass keyword arguments to other function as easy as `func1(**d.func1)`.

    Since `NestedDict` inherits from `DefaultDict`, it also supports `default_factory`.
    With `default_factory`, you can assign `d.a.b.c = 1` without assign `d.a = NestedDict()` in the first place.
    Note that the constructor of `NestedDict` is different from `DefaultDict`, `default_factory` is not a positional
    argument, and must be set in a keyword argument.

    `NestedDict` also introduce `all_keys`, `all_values`, `all_items` methods to get all keys, values, items
    respectively in the nested structure.

    Attributes:
        convert_mapping: bool = False
            If `True`, all new values with a type of `Mapping` will be converted to `default_factory`.
                If `default_factory` is `Null`, will create an empty instance via `self.empty` as `default_factory`.
        delimiter: str = "."
            Delimiter for nested structure.

    Notes:
        When `convert_mapping` specified, all new values with type of `Mapping` will be converted to `default_factory`.
            If `default_factory` is `Null`, will create an empty instance via `self.empty` as `default_factory`.

        `convert_mapping` is automatically applied to arguments during initialisation.

    Examples:
        >>> NestedDict({"f.n": "chang"})
        NestedDict(
          ('f'): NestedDict(
            ('n'): 'chang'
          )
        )
        >>> d = NestedDict({"f.n": "chang"}, default_factory=NestedDict)
        >>> d.i.d = 1013
        >>> d['i.d']
        1013
        >>> d.i.d
        1013
        >>> d.dict()
        {'f': {'n': 'chang'}, 'i': {'d': 1013}}
    """

    convert_mapping: bool = False
    delimiter: str = "."

    def __init__(self, *args, default_factory: Optional[Callable] = None, **kwargs) -> None:
        super().__init__(default_factory, *args, **kwargs)

    def _init(self, *args, **kwargs) -> None:
        if len(args) == 1:
            args = args[0]
            if isinstance(args, Mapping):
                for key, value in args.items():
                    self.set(key, value, convert_mapping=True)
            elif isinstance(args, Iterable):
                for key, value in args:
                    self.set(key, value, convert_mapping=True)
        else:
            for key, value in args:
                self.set(key, value, convert_mapping=True)
        for key, value in kwargs.items():
            self.set(key, value, convert_mapping=True)

    def all_keys(self) -> Iterator:
        r"""
        Get all keys of `NestedDict`.

        Returns:
            (Iterator):

        Examples:
            >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
            >>> list(d.all_keys())
            ['a', 'b.c', 'b.d']
        """

        delimiter = self.getattr("delimiter", ".")

        @wraps(self.all_keys)
        def all_keys(self, prefix=""):
            for key, value in self.items():
                if prefix:
                    key = str(prefix) + str(delimiter) + str(key)
                if isinstance(value, NestedDict):
                    yield from all_keys(value, key)
                else:
                    yield key

        return all_keys(self)

    def all_values(self) -> Iterator:
        r"""
        Get all values of `NestedDict`.

        Returns:
            (Iterator):

        Examples:
            >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
            >>> list(d.all_values())
            [1, 2, 3]
        """

        for value in self.values():
            if isinstance(value, NestedDict):
                yield from value.all_values()
            else:
                yield value

    def all_items(self) -> Iterator[Tuple]:
        r"""
        Get all items of `NestedDict`.

        Returns:
            (Iterator):

        Examples:
            >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
            >>> list(d.all_items())
            [('a', 1), ('b.c', 2), ('b.d', 3)]
        """

        delimiter = self.getattr("delimiter", ".")

        @wraps(self.all_items)
        def all_items(self, prefix=""):
            for key, value in self.items():
                if prefix:
                    key = str(prefix) + str(delimiter) + str(key)
                if isinstance(value, NestedDict):
                    yield from all_items(value, key)
                else:
                    yield key, value

        return all_items(self)

    def apply(self, func: Callable, *args, **kwargs) -> NestedDict:
        r"""
        Recursively apply a function to `NestedDict` and its children.

        Note:
            This method is meant for non-in-place modification of `obj`, for example, [`to`][chanfig.NestedDict.to].

        Args:
            func(Callable):

        See Also:
            [`apply_`][chanfig.NestedDict.apply_]: Apply a in-place operation.

            [`apply`][chanfig.utils.apply]: implementation of `apply` method.

        Examples:
            >>> def func(d):
            ...     if isinstance(d, NestedDict):
            ...         d.t = 1
            >>> d = NestedDict()
            >>> d.a = NestedDict()
            >>> d.b = [NestedDict(),]
            >>> d.c = (NestedDict(),)
            >>> d.d = {NestedDict(),}
            >>> d.apply(func).dict()
            {'a': {}, 'b': [{}], 'c': ({},), 'd': ({},)}
        """

        return apply(self, func, *args, **kwargs)

    def apply_(self, func: Callable, *args, **kwargs) -> NestedDict:
        r"""
        Recursively apply a function to `NestedDict` and its children.

        Note:
            This method is meant for in-place modification of `obj`, for example, [`freeze`][chanfig.Config.freeze].

        Args:
            func(Callable):

        See Also:
            [`apply`][chanfig.NestedDict.apply]: Apply a non-in-place operation.

            [`apply_`][chanfig.utils.apply_]: implementation of `apply_` method.

        Examples:
            >>> def func(d):
            ...     if isinstance(d, NestedDict):
            ...         d.t = 1
            >>> d = NestedDict()
            >>> d.a = NestedDict()
            >>> d.b = [NestedDict(),]
            >>> d.c = (NestedDict(),)
            >>> d.d = {NestedDict(),}
            >>> d.apply_(func).dict()
            {'a': {'t': 1}, 'b': [{'t': 1}], 'c': ({'t': 1},), 'd': ({'t': 1},), 't': 1}
        """

        apply_(self, func, *args, **kwargs)
        return self

    def get(self, name: Any, default: Any = Null) -> Any:
        r"""
        Get value from `NestedDict`.

        Note that `default` has higher priority than `default_factory`.

        Args:
            name:
            default:

        Returns:
            value:
                If `NestedDict` does not contain `name`, return `default`.
                If `default` is not specified, return `default_factory()`.

        Raises:
            KeyError: If `NestedDict` does not contain `name` and `default`/`default_factory` is not specified.

        Examples:
            >>> d = NestedDict({"i.d": 1013}, default_factory=NestedDict)
            >>> d.get('i.d')
            1013
            >>> d['i.d']
            1013
            >>> d.i.d
            1013
            >>> d.get('i.d', None)
            1013
            >>> d.get('f', 2)
            2
            >>> d.f
            NestedDict(<class 'chanfig.nested_dict.NestedDict'>, )
            >>> del d.f
            >>> d = NestedDict()
            >>> d.e
            Traceback (most recent call last):
            AttributeError: 'NestedDict' object has no attribute 'e'
            >>> d.e.f
            Traceback (most recent call last):
            AttributeError: 'NestedDict' object has no attribute 'e'
        """

        delimiter = self.getattr("delimiter", ".")
        try:
            while isinstance(name, str) and delimiter in name:
                name, rest = name.split(delimiter, 1)
                self, name = self[name], rest  # pylint: disable=W0642
        except (AttributeError, TypeError):
            raise KeyError(name) from None
        # if value is a python dict
        if not isinstance(self, NestedDict):
            if name not in self and default is not Null:
                return default
            return dict.get(self, name)
        return super().get(name, default)

    def set(  # pylint: disable=W0221
        self,
        name: Any,
        value: Any,
        convert_mapping: Optional[bool] = None,
    ) -> None:
        r"""
        Set value of `NestedDict`.

        Args:
            name:
            value:
            convert_mapping: Whether convert mapping to NestedDict.
                Defaults to self.convert_mapping.

        Examples:
            >>> d = NestedDict(default_factory=NestedDict)
            >>> d.set('i.d', 1013)
            >>> d.get('i.d')
            1013
            >>> d.dict()
            {'i': {'d': 1013}}
            >>> d['f.n'] = 'chang'
            >>> d.f.n
            'chang'
            >>> d.n.l = 'liu'
            >>> d['n.l']
            'liu'
            >>> d['f.n.e'] = "error"
            Traceback (most recent call last):
            ValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.
            >>> d['f.n.e.a'] = "error"
            Traceback (most recent call last):
            KeyError: 'e'
            >>> d.f.n.e.a = "error"
            Traceback (most recent call last):
            AttributeError: 'str' object has no attribute 'e'
            >>> d.setattr('convert_mapping', True)
            >>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}
            >>> d.a.b.c.d
            1
            >>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}
            >>> d.c.d['e.f']
            2
            >>> d.setattr('convert_mapping', False)
            >>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)
            >>> d['e.f']['c.d']
            1
        """
        # pylint: disable=W0642

        full_name = name
        if convert_mapping is None:
            convert_mapping = self.convert_mapping
        delimiter = self.getattr("delimiter", ".")
        default_factory = self.getattr("default_factory", self.empty)
        try:
            while isinstance(name, str) and delimiter in name:
                name, rest = name.split(delimiter, 1)
                default_factory = self.getattr("default_factory", self.empty)
                if name in dir(self) and isinstance(getattr(self.__class__, name), property):
                    self, name = getattr(self, name), rest
                elif name not in self:
                    self, name = self.__missing__(name, default_factory()), rest
                else:
                    self, name = self[name], rest
        except (AttributeError, TypeError):
            raise KeyError(name) from None
        if convert_mapping and isinstance(value, Mapping):
            value = default_factory(value)
        if isinstance(self, Mapping):
            if not isinstance(self, NestedDict):
                dict.__setitem__(self, name, value)
            else:
                super().set(name, value)
        else:
            raise ValueError(
                f"Cannot set `{full_name}` to `{value}`, as `{delimiter.join(full_name.split(delimiter)[:-1])}={self}`."
            )

    def delete(self, name: Any) -> None:
        r"""
        Delete value from `NestedDict`.

        Args:
            name:

        Examples:
            >>> d = NestedDict({"i.d": 1013, "f.n": "chang"}, default_factory=NestedDict)
            >>> d.i.d
            1013
            >>> d.f.n
            'chang'
            >>> d.delete('i.d')
            >>> "i.d" in d
            False
            >>> d.i.d
            Traceback (most recent call last):
            AttributeError: 'NestedDict' object has no attribute 'd'
            >>> del d.f.n
            >>> d.f.n
            Traceback (most recent call last):
            AttributeError: 'NestedDict' object has no attribute 'n'
            >>> del d.e
            Traceback (most recent call last):
            AttributeError: 'NestedDict' object has no attribute 'e'
            >>> del d['e.f']
            Traceback (most recent call last):
            KeyError: 'f'
        """

        delimiter = self.getattr("delimiter", ".")
        try:
            while isinstance(name, str) and delimiter in name:
                name, rest = name.split(delimiter, 1)
                self, name = self[name], rest  # pylint: disable=W0642
        except (AttributeError, TypeError):
            raise KeyError(name) from None
        super().delete(name)

    def pop(self, name: Any, default: Any = Null) -> Any:
        r"""
        Pop value from `NestedDict`.

        Args:
            name:
            default:

        Returns:
            value: If `NestedDict` does not contain `name`, return `default`.

        Examples:
            >>> d = NestedDict({"i.d": 1013, "f.n": "chang", "n.a.b.c": 1}, default_factory=NestedDict)
            >>> d.pop('i.d')
            1013
            >>> d.pop('i.d', True)
            True
            >>> d.pop('i.d')
            Traceback (most recent call last):
            KeyError: 'd'
            >>> d.pop('e')
            Traceback (most recent call last):
            KeyError: 'e'
            >>> d.pop('e.f')
            Traceback (most recent call last):
            KeyError: 'f'
        """

        delimiter = self.getattr("delimiter", ".")
        try:
            while isinstance(name, str) and delimiter in name:
                name, rest = name.split(delimiter, 1)
                self, name = self[name], rest  # pylint: disable=W0642
        except (AttributeError, TypeError):
            raise KeyError(name) from None
        if not isinstance(self, dict) or name not in self:
            if default is not Null:
                return default
            raise KeyError(name)
        return super().pop(name)

    def merge(self, other: Union[Mapping, Iterable, PathStr]) -> NestedDict:
        r"""
        Merge `other` into `NestedDict`.

        Args:
            other:

        Returns:
            self:

        **Alias**:

        + `merge_from_file`
        + `union`

        Examples:
            >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
            >>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
            >>> d.merge(n).dict()
            {'a': 1, 'b': {'c': 3, 'd': 3}, 'e': 4}
            >>> NestedDict(a=1, b=1, c=1).merge_from_file("example.yaml").dict()  # alias
            {'a': 1, 'b': 2, 'c': 3}
            >>> NestedDict(a=1, b=1, c=1).union(NestedDict(b='b', c='c', d='d')).dict()  # alias
            {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}
        """

        if isinstance(other, (PathLike, str, bytes)):
            other = self.load(other)
        if not isinstance(other, NestedDict):
            other = NestedDict(other)
        for name, value in other.all_items():
            self.set(name, value)
        return self

    def intersect(  # pylint: disable=W0221
        self, other: Union[Mapping, Iterable, PathStr], recursive: bool = True
    ) -> NestedDict:
        r"""
        Intersection of `NestedDict` and `other`.

        Args:
            other (Mapping | Iterable | PathStr):
            recursive (bool):

        Examples:
            >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
            >>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
            >>> d.intersect(n).dict()
            {'a': 1, 'b': {'d': 3}}
            >>> d.intersect("example.yaml").dict()
            {'a': 1}
            >>> d.intersect(n, recursive=False).dict()
            {'a': 1}
            >>> l = [('a', 1), ('d', 4)]
            >>> d.intersect(l).dict()
            {'a': 1}
            >>> d.intersect(1)
            Traceback (most recent call last):
            TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.
        """

        if isinstance(other, (PathLike, str, bytes)):
            other = self.load(other)
        if isinstance(other, (Mapping,)):
            other = self.empty_like(other).items()
        if not isinstance(other, Iterable):
            raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")

        @wraps(self.intersect)
        def intersect(this: NestedDict, that: Iterable) -> Mapping:
            ret = {}
            for key, value in that:
                if key in this:
                    if isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:
                        ret[key] = this[key].intersect(value)
                    elif this[key] == value:
                        ret[key] = value
            return ret

        return self.empty_like(intersect(self, other))  # type: ignore

    def difference(  # pylint: disable=W0221, C0103
        self, other: Union[Mapping, Iterable, PathStr], recursive: bool = True
    ) -> NestedDict:
        r"""
        Difference between `NestedDict` and `other`.

        Args:
            other (Mapping | Iterable | PathStr):
            recursive (bool):

        Examples:
            >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
            >>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
            >>> d.difference(n).dict()
            {'b': {'c': 3}, 'e': 4}
            >>> d.difference("example.yaml").dict()
            {'b': 2, 'c': 3}
            >>> d.difference(n, recursive=False).dict()
            {'b': {'c': 3, 'd': 3}, 'e': 4}
            >>> l = [('a', 1), ('d', 4)]
            >>> d.difference(l).dict()
            {'d': 4}
            >>> d.difference(1)
            Traceback (most recent call last):
            TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.
        """

        if isinstance(other, (PathLike, str, bytes)):
            other = self.load(other)
        if isinstance(other, (Mapping,)):
            other = self.empty_like(other).items()
        if not isinstance(other, Iterable):
            raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")

        @wraps(self.difference)
        def difference(this: NestedDict, that: Iterable) -> Mapping:
            ret = {}
            for key, value in that:
                if key not in this:
                    ret[key] = value
                elif isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:
                    diff = this[key].difference(value)
                    if diff:
                        ret[key] = diff
                elif this[key] != value:
                    ret[key] = value
            return ret

        return self.empty_like(difference(self, other))  # type: ignore

    def to(self, cls: Union[str, TorchDevice, TorchDtype]) -> Any:
        r"""
        Convert values of `NestedDict` to target `cls`.

        Args:
            cls (str | torch.device | torch.dtype):

        Examples:
            >>> import torch
            >>> d = NestedDict({'i.d': torch.tensor(1013)})
            >>> d.cpu().dict()
            {'i': {'d': tensor(1013)}}
        """

        def to(obj):
            if hasattr(obj, "to"):
                return obj.to(cls)

        return self.apply(to)

    def dropnull(self) -> NestedDict:
        r"""
        Drop key-value pairs with `Null` value.

        Returns:
            (NestedDict):

        Examples:
            >>> d = NestedDict({"a.b": Null, "b.c.d": Null, "b.c.e.f": Null, "c.d.e.f": Null, "h.j": 1})
            >>> d.dict()
            {'a': {'b': Null}, 'b': {'c': {'d': Null, 'e': {'f': Null}}}, 'c': {'d': {'e': {'f': Null}}}, 'h': {'j': 1}}
            >>> d.dropnull().dict()
            {'h': {'j': 1}}
        """

        return NestedDict({k: v for k, v in self.all_items() if v is not Null})

    def __contains__(self, name: Any) -> bool:  # type: ignore
        delimiter = self.getattr("delimiter", ".")
        try:
            while isinstance(name, str) and delimiter in name:
                name, rest = name.split(delimiter, 1)
                self, name = self[name], rest  # pylint: disable=W0642
            return super().__contains__(name)
        except (TypeError, KeyError):  # TypeError when name is not in self
            return False

`all_keys()` ¶

Get all keys of NestedDict.

Returns:

Type	Description
`Iterator`

Examples:

Python Console Session

>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
>>> list(d.all_keys())
['a', 'b.c', 'b.d']

Source code in chanfig/nested_dict.py

Python
def all_keys(self) -> Iterator:
    r"""
    Get all keys of `NestedDict`.

    Returns:
        (Iterator):

    Examples:
        >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
        >>> list(d.all_keys())
        ['a', 'b.c', 'b.d']
    """

    delimiter = self.getattr("delimiter", ".")

    @wraps(self.all_keys)
    def all_keys(self, prefix=""):
        for key, value in self.items():
            if prefix:
                key = str(prefix) + str(delimiter) + str(key)
            if isinstance(value, NestedDict):
                yield from all_keys(value, key)
            else:
                yield key

    return all_keys(self)

`all_values()` ¶

Get all values of NestedDict.

Returns:

Type	Description
`Iterator`

Examples:

Python Console Session

>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
>>> list(d.all_values())
[1, 2, 3]

Source code in chanfig/nested_dict.py

Python
def all_values(self) -> Iterator:
    r"""
    Get all values of `NestedDict`.

    Returns:
        (Iterator):

    Examples:
        >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
        >>> list(d.all_values())
        [1, 2, 3]
    """

    for value in self.values():
        if isinstance(value, NestedDict):
            yield from value.all_values()
        else:
            yield value

`all_items()` ¶

Get all items of NestedDict.

Returns:

Type	Description
`Iterator`

Examples:

Python Console Session

>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
>>> list(d.all_items())
[('a', 1), ('b.c', 2), ('b.d', 3)]

Source code in chanfig/nested_dict.py

Python
def all_items(self) -> Iterator[Tuple]:
    r"""
    Get all items of `NestedDict`.

    Returns:
        (Iterator):

    Examples:
        >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})
        >>> list(d.all_items())
        [('a', 1), ('b.c', 2), ('b.d', 3)]
    """

    delimiter = self.getattr("delimiter", ".")

    @wraps(self.all_items)
    def all_items(self, prefix=""):
        for key, value in self.items():
            if prefix:
                key = str(prefix) + str(delimiter) + str(key)
            if isinstance(value, NestedDict):
                yield from all_items(value, key)
            else:
                yield key, value

    return all_items(self)

`apply(func, *args, **kwargs)` ¶

Recursively apply a function to NestedDict and its children.

Note

This method is meant for non-in-place modification of obj, for example, to.

Parameters:

Name	Type	Description	Default
`func(Callable)`			required

`apply_(func, *args, **kwargs)` ¶

Recursively apply a function to NestedDict and its children.

Note

This method is meant for in-place modification of obj, for example, freeze.

Parameters:

Name	Type	Description	Default
`func(Callable)`			required

`get(name, default=Null)` ¶

Get value from NestedDict.

Note that default has higher priority than default_factory.

Parameters:

Name	Type	Description	Default
`name`	`Any`		required
`default`	`Any`		`Null`

Returns:

Name	Type	Description
`value`	`Any`	If `NestedDict` does not contain `name`, return `default`. If `default` is not specified, return `default_factory()`.

Raises:

Type	Description
`KeyError`	If `NestedDict` does not contain `name` and `default`/`default_factory` is not specified.

Examples:

Python Console Session

>>> d = NestedDict({"i.d": 1013}, default_factory=NestedDict)
>>> d.get('i.d')
1013
>>> d['i.d']
1013
>>> d.i.d
1013
>>> d.get('i.d', None)
1013
>>> d.get('f', 2)
2
>>> d.f
NestedDict(<class 'chanfig.nested_dict.NestedDict'>, )
>>> del d.f
>>> d = NestedDict()
>>> d.e
Traceback (most recent call last):
AttributeError: 'NestedDict' object has no attribute 'e'
>>> d.e.f
Traceback (most recent call last):
AttributeError: 'NestedDict' object has no attribute 'e'

Source code in chanfig/nested_dict.py

Python
def get(self, name: Any, default: Any = Null) -> Any:
    r"""
    Get value from `NestedDict`.

    Note that `default` has higher priority than `default_factory`.

    Args:
        name:
        default:

    Returns:
        value:
            If `NestedDict` does not contain `name`, return `default`.
            If `default` is not specified, return `default_factory()`.

    Raises:
        KeyError: If `NestedDict` does not contain `name` and `default`/`default_factory` is not specified.

    Examples:
        >>> d = NestedDict({"i.d": 1013}, default_factory=NestedDict)
        >>> d.get('i.d')
        1013
        >>> d['i.d']
        1013
        >>> d.i.d
        1013
        >>> d.get('i.d', None)
        1013
        >>> d.get('f', 2)
        2
        >>> d.f
        NestedDict(<class 'chanfig.nested_dict.NestedDict'>, )
        >>> del d.f
        >>> d = NestedDict()
        >>> d.e
        Traceback (most recent call last):
        AttributeError: 'NestedDict' object has no attribute 'e'
        >>> d.e.f
        Traceback (most recent call last):
        AttributeError: 'NestedDict' object has no attribute 'e'
    """

    delimiter = self.getattr("delimiter", ".")
    try:
        while isinstance(name, str) and delimiter in name:
            name, rest = name.split(delimiter, 1)
            self, name = self[name], rest  # pylint: disable=W0642
    except (AttributeError, TypeError):
        raise KeyError(name) from None
    # if value is a python dict
    if not isinstance(self, NestedDict):
        if name not in self and default is not Null:
            return default
        return dict.get(self, name)
    return super().get(name, default)

`set(name, value, convert_mapping=None)` ¶

Set value of NestedDict.

Parameters:

Name	Type	Description	Default
`name`	`Any`		required
`value`	`Any`		required
`convert_mapping`	`Optional[bool]`	Whether convert mapping to NestedDict. Defaults to self.convert_mapping.	`None`

Examples:

Python Console Session

>>> d = NestedDict(default_factory=NestedDict)
>>> d.set('i.d', 1013)
>>> d.get('i.d')
1013
>>> d.dict()
{'i': {'d': 1013}}
>>> d['f.n'] = 'chang'
>>> d.f.n
'chang'
>>> d.n.l = 'liu'
>>> d['n.l']
'liu'
>>> d['f.n.e'] = "error"
Traceback (most recent call last):
ValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.
>>> d['f.n.e.a'] = "error"
Traceback (most recent call last):
KeyError: 'e'
>>> d.f.n.e.a = "error"
Traceback (most recent call last):
AttributeError: 'str' object has no attribute 'e'
>>> d.setattr('convert_mapping', True)
>>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}
>>> d.a.b.c.d
1
>>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}
>>> d.c.d['e.f']
2
>>> d.setattr('convert_mapping', False)
>>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)
>>> d['e.f']['c.d']
1

Source code in chanfig/nested_dict.py

Python
def set(  # pylint: disable=W0221
    self,
    name: Any,
    value: Any,
    convert_mapping: Optional[bool] = None,
) -> None:
    r"""
    Set value of `NestedDict`.

    Args:
        name:
        value:
        convert_mapping: Whether convert mapping to NestedDict.
            Defaults to self.convert_mapping.

    Examples:
        >>> d = NestedDict(default_factory=NestedDict)
        >>> d.set('i.d', 1013)
        >>> d.get('i.d')
        1013
        >>> d.dict()
        {'i': {'d': 1013}}
        >>> d['f.n'] = 'chang'
        >>> d.f.n
        'chang'
        >>> d.n.l = 'liu'
        >>> d['n.l']
        'liu'
        >>> d['f.n.e'] = "error"
        Traceback (most recent call last):
        ValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.
        >>> d['f.n.e.a'] = "error"
        Traceback (most recent call last):
        KeyError: 'e'
        >>> d.f.n.e.a = "error"
        Traceback (most recent call last):
        AttributeError: 'str' object has no attribute 'e'
        >>> d.setattr('convert_mapping', True)
        >>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}
        >>> d.a.b.c.d
        1
        >>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}
        >>> d.c.d['e.f']
        2
        >>> d.setattr('convert_mapping', False)
        >>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)
        >>> d['e.f']['c.d']
        1
    """
    # pylint: disable=W0642

    full_name = name
    if convert_mapping is None:
        convert_mapping = self.convert_mapping
    delimiter = self.getattr("delimiter", ".")
    default_factory = self.getattr("default_factory", self.empty)
    try:
        while isinstance(name, str) and delimiter in name:
            name, rest = name.split(delimiter, 1)
            default_factory = self.getattr("default_factory", self.empty)
            if name in dir(self) and isinstance(getattr(self.__class__, name), property):
                self, name = getattr(self, name), rest
            elif name not in self:
                self, name = self.__missing__(name, default_factory()), rest
            else:
                self, name = self[name], rest
    except (AttributeError, TypeError):
        raise KeyError(name) from None
    if convert_mapping and isinstance(value, Mapping):
        value = default_factory(value)
    if isinstance(self, Mapping):
        if not isinstance(self, NestedDict):
            dict.__setitem__(self, name, value)
        else:
            super().set(name, value)
    else:
        raise ValueError(
            f"Cannot set `{full_name}` to `{value}`, as `{delimiter.join(full_name.split(delimiter)[:-1])}={self}`."
        )

`delete(name)` ¶

Delete value from NestedDict.

Parameters:

Name	Type	Description	Default
`name`	`Any`		required

Examples:

Python Console Session

>>> d = NestedDict({"i.d": 1013, "f.n": "chang"}, default_factory=NestedDict)
>>> d.i.d
1013
>>> d.f.n
'chang'
>>> d.delete('i.d')
>>> "i.d" in d
False
>>> d.i.d
Traceback (most recent call last):
AttributeError: 'NestedDict' object has no attribute 'd'
>>> del d.f.n
>>> d.f.n
Traceback (most recent call last):
AttributeError: 'NestedDict' object has no attribute 'n'
>>> del d.e
Traceback (most recent call last):
AttributeError: 'NestedDict' object has no attribute 'e'
>>> del d['e.f']
Traceback (most recent call last):
KeyError: 'f'

Source code in chanfig/nested_dict.py

Python
def delete(self, name: Any) -> None:
    r"""
    Delete value from `NestedDict`.

    Args:
        name:

    Examples:
        >>> d = NestedDict({"i.d": 1013, "f.n": "chang"}, default_factory=NestedDict)
        >>> d.i.d
        1013
        >>> d.f.n
        'chang'
        >>> d.delete('i.d')
        >>> "i.d" in d
        False
        >>> d.i.d
        Traceback (most recent call last):
        AttributeError: 'NestedDict' object has no attribute 'd'
        >>> del d.f.n
        >>> d.f.n
        Traceback (most recent call last):
        AttributeError: 'NestedDict' object has no attribute 'n'
        >>> del d.e
        Traceback (most recent call last):
        AttributeError: 'NestedDict' object has no attribute 'e'
        >>> del d['e.f']
        Traceback (most recent call last):
        KeyError: 'f'
    """

    delimiter = self.getattr("delimiter", ".")
    try:
        while isinstance(name, str) and delimiter in name:
            name, rest = name.split(delimiter, 1)
            self, name = self[name], rest  # pylint: disable=W0642
    except (AttributeError, TypeError):
        raise KeyError(name) from None
    super().delete(name)

`pop(name, default=Null)` ¶

Pop value from NestedDict.

Parameters:

Name	Type	Description	Default
`name`	`Any`		required
`default`	`Any`		`Null`

Returns:

Name	Type	Description
`value`	`Any`	If `NestedDict` does not contain `name`, return `default`.

Examples:

Python Console Session

>>> d = NestedDict({"i.d": 1013, "f.n": "chang", "n.a.b.c": 1}, default_factory=NestedDict)
>>> d.pop('i.d')
1013
>>> d.pop('i.d', True)
True
>>> d.pop('i.d')
Traceback (most recent call last):
KeyError: 'd'
>>> d.pop('e')
Traceback (most recent call last):
KeyError: 'e'
>>> d.pop('e.f')
Traceback (most recent call last):
KeyError: 'f'

Source code in chanfig/nested_dict.py

Python
def pop(self, name: Any, default: Any = Null) -> Any:
    r"""
    Pop value from `NestedDict`.

    Args:
        name:
        default:

    Returns:
        value: If `NestedDict` does not contain `name`, return `default`.

    Examples:
        >>> d = NestedDict({"i.d": 1013, "f.n": "chang", "n.a.b.c": 1}, default_factory=NestedDict)
        >>> d.pop('i.d')
        1013
        >>> d.pop('i.d', True)
        True
        >>> d.pop('i.d')
        Traceback (most recent call last):
        KeyError: 'd'
        >>> d.pop('e')
        Traceback (most recent call last):
        KeyError: 'e'
        >>> d.pop('e.f')
        Traceback (most recent call last):
        KeyError: 'f'
    """

    delimiter = self.getattr("delimiter", ".")
    try:
        while isinstance(name, str) and delimiter in name:
            name, rest = name.split(delimiter, 1)
            self, name = self[name], rest  # pylint: disable=W0642
    except (AttributeError, TypeError):
        raise KeyError(name) from None
    if not isinstance(self, dict) or name not in self:
        if default is not Null:
            return default
        raise KeyError(name)
    return super().pop(name)

`merge(other)` ¶

Merge other into NestedDict.

Parameters:

Name	Type	Description	Default
`other`	`Union[Mapping, Iterable, PathStr]`		required

Returns:

Name	Type	Description
`self`	`NestedDict`

Alias:

merge_from_file
union

Examples:

Python Console Session

>>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
>>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
>>> d.merge(n).dict()
{'a': 1, 'b': {'c': 3, 'd': 3}, 'e': 4}
>>> NestedDict(a=1, b=1, c=1).merge_from_file("example.yaml").dict()  # alias
{'a': 1, 'b': 2, 'c': 3}
>>> NestedDict(a=1, b=1, c=1).union(NestedDict(b='b', c='c', d='d')).dict()  # alias
{'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}

Source code in chanfig/nested_dict.py

Python
def merge(self, other: Union[Mapping, Iterable, PathStr]) -> NestedDict:
    r"""
    Merge `other` into `NestedDict`.

    Args:
        other:

    Returns:
        self:

    **Alias**:

    + `merge_from_file`
    + `union`

    Examples:
        >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
        >>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
        >>> d.merge(n).dict()
        {'a': 1, 'b': {'c': 3, 'd': 3}, 'e': 4}
        >>> NestedDict(a=1, b=1, c=1).merge_from_file("example.yaml").dict()  # alias
        {'a': 1, 'b': 2, 'c': 3}
        >>> NestedDict(a=1, b=1, c=1).union(NestedDict(b='b', c='c', d='d')).dict()  # alias
        {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}
    """

    if isinstance(other, (PathLike, str, bytes)):
        other = self.load(other)
    if not isinstance(other, NestedDict):
        other = NestedDict(other)
    for name, value in other.all_items():
        self.set(name, value)
    return self

`intersect(other, recursive=True)` ¶

Intersection of NestedDict and other.

Parameters:

Name	Type	Description	Default
`other`	`Mapping \| Iterable \| PathStr`		required
`recursive`	`bool`		`True`

Examples:

Python Console Session

>>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
>>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
>>> d.intersect(n).dict()
{'a': 1, 'b': {'d': 3}}
>>> d.intersect("example.yaml").dict()
{'a': 1}
>>> d.intersect(n, recursive=False).dict()
{'a': 1}
>>> l = [('a', 1), ('d', 4)]
>>> d.intersect(l).dict()
{'a': 1}
>>> d.intersect(1)
Traceback (most recent call last):
TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.

Source code in chanfig/nested_dict.py

Python
def intersect(  # pylint: disable=W0221
    self, other: Union[Mapping, Iterable, PathStr], recursive: bool = True
) -> NestedDict:
    r"""
    Intersection of `NestedDict` and `other`.

    Args:
        other (Mapping | Iterable | PathStr):
        recursive (bool):

    Examples:
        >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
        >>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
        >>> d.intersect(n).dict()
        {'a': 1, 'b': {'d': 3}}
        >>> d.intersect("example.yaml").dict()
        {'a': 1}
        >>> d.intersect(n, recursive=False).dict()
        {'a': 1}
        >>> l = [('a', 1), ('d', 4)]
        >>> d.intersect(l).dict()
        {'a': 1}
        >>> d.intersect(1)
        Traceback (most recent call last):
        TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.
    """

    if isinstance(other, (PathLike, str, bytes)):
        other = self.load(other)
    if isinstance(other, (Mapping,)):
        other = self.empty_like(other).items()
    if not isinstance(other, Iterable):
        raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")

    @wraps(self.intersect)
    def intersect(this: NestedDict, that: Iterable) -> Mapping:
        ret = {}
        for key, value in that:
            if key in this:
                if isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:
                    ret[key] = this[key].intersect(value)
                elif this[key] == value:
                    ret[key] = value
        return ret

    return self.empty_like(intersect(self, other))  # type: ignore

`difference(other, recursive=True)` ¶

Difference between NestedDict and other.

Parameters:

Name	Type	Description	Default
`other`	`Mapping \| Iterable \| PathStr`		required
`recursive`	`bool`		`True`

Examples:

Python Console Session

>>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
>>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
>>> d.difference(n).dict()
{'b': {'c': 3}, 'e': 4}
>>> d.difference("example.yaml").dict()
{'b': 2, 'c': 3}
>>> d.difference(n, recursive=False).dict()
{'b': {'c': 3, 'd': 3}, 'e': 4}
>>> l = [('a', 1), ('d', 4)]
>>> d.difference(l).dict()
{'d': 4}
>>> d.difference(1)
Traceback (most recent call last):
TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.

Source code in chanfig/nested_dict.py

Python
def difference(  # pylint: disable=W0221, C0103
    self, other: Union[Mapping, Iterable, PathStr], recursive: bool = True
) -> NestedDict:
    r"""
    Difference between `NestedDict` and `other`.

    Args:
        other (Mapping | Iterable | PathStr):
        recursive (bool):

    Examples:
        >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3})
        >>> n = {'a': 1, 'b.c': 3, 'b.d': 3, 'e': 4}
        >>> d.difference(n).dict()
        {'b': {'c': 3}, 'e': 4}
        >>> d.difference("example.yaml").dict()
        {'b': 2, 'c': 3}
        >>> d.difference(n, recursive=False).dict()
        {'b': {'c': 3, 'd': 3}, 'e': 4}
        >>> l = [('a', 1), ('d', 4)]
        >>> d.difference(l).dict()
        {'d': 4}
        >>> d.difference(1)
        Traceback (most recent call last):
        TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.
    """

    if isinstance(other, (PathLike, str, bytes)):
        other = self.load(other)
    if isinstance(other, (Mapping,)):
        other = self.empty_like(other).items()
    if not isinstance(other, Iterable):
        raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")

    @wraps(self.difference)
    def difference(this: NestedDict, that: Iterable) -> Mapping:
        ret = {}
        for key, value in that:
            if key not in this:
                ret[key] = value
            elif isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:
                diff = this[key].difference(value)
                if diff:
                    ret[key] = diff
            elif this[key] != value:
                ret[key] = value
        return ret

    return self.empty_like(difference(self, other))  # type: ignore

`to(cls)` ¶

Convert values of NestedDict to target cls.

Parameters:

Name	Type	Description	Default
`cls`	`str \| torch.device \| torch.dtype`		required

Examples:

Python Console Session

>>> import torch
>>> d = NestedDict({'i.d': torch.tensor(1013)})
>>> d.cpu().dict()
{'i': {'d': tensor(1013)}}

Source code in chanfig/nested_dict.py

Python
def to(self, cls: Union[str, TorchDevice, TorchDtype]) -> Any:
    r"""
    Convert values of `NestedDict` to target `cls`.

    Args:
        cls (str | torch.device | torch.dtype):

    Examples:
        >>> import torch
        >>> d = NestedDict({'i.d': torch.tensor(1013)})
        >>> d.cpu().dict()
        {'i': {'d': tensor(1013)}}
    """

    def to(obj):
        if hasattr(obj, "to"):
            return obj.to(cls)

    return self.apply(to)

`dropnull()` ¶

Drop key-value pairs with Null value.

Returns:

Type	Description
`NestedDict`

Examples:

Python Console Session

>>> d = NestedDict({"a.b": Null, "b.c.d": Null, "b.c.e.f": Null, "c.d.e.f": Null, "h.j": 1})
>>> d.dict()
{'a': {'b': Null}, 'b': {'c': {'d': Null, 'e': {'f': Null}}}, 'c': {'d': {'e': {'f': Null}}}, 'h': {'j': 1}}
>>> d.dropnull().dict()
{'h': {'j': 1}}

Source code in chanfig/nested_dict.py

Python
def dropnull(self) -> NestedDict:
    r"""
    Drop key-value pairs with `Null` value.

    Returns:
        (NestedDict):

    Examples:
        >>> d = NestedDict({"a.b": Null, "b.c.d": Null, "b.c.e.f": Null, "c.d.e.f": Null, "h.j": 1})
        >>> d.dict()
        {'a': {'b': Null}, 'b': {'c': {'d': Null, 'e': {'f': Null}}}, 'c': {'d': {'e': {'f': Null}}}, 'h': {'j': 1}}
        >>> d.dropnull().dict()
        {'h': {'j': 1}}
    """

    return NestedDict({k: v for k, v in self.all_items() if v is not Null})

最后更新: 2023-05-20 15:08:43

NestedDict¶

all_keys() ¶

all_values() ¶

all_items() ¶

apply(func, *args, **kwargs) ¶

apply_(func, *args, **kwargs) ¶

get(name, default=Null) ¶

set(name, value, convert_mapping=None) ¶

delete(name) ¶

pop(name, default=Null) ¶

merge(other) ¶

intersect(other, recursive=True) ¶

difference(other, recursive=True) ¶

to(cls) ¶

dropnull() ¶

`all_keys()` ¶

`all_values()` ¶

`all_items()` ¶

`apply(func, *args, **kwargs)` ¶

`apply_(func, *args, **kwargs)` ¶

`get(name, default=Null)` ¶

`set(name, value, convert_mapping=None)` ¶

`delete(name)` ¶

`pop(name, default=Null)` ¶

`merge(other)` ¶

`intersect(other, recursive=True)` ¶

`difference(other, recursive=True)` ¶

`to(cls)` ¶

`dropnull()` ¶