FlatDict

Bases: dict

FlatDict with attribute-style access.

FlatDict inherits from built-in dict.

It comes with many easy to use helper function, such as difference, intersect.

It also has full support for IO operations, such as json and yaml.

Even better, FlatDict has pytorch support built-in. You can directly call FlatDict.cpu() or FlatDict.to("cpu") to move all torch.Tensor objects across devices.

FlatDict works best with Variable objects. Just simply call FlatDict.a = Variable(1); FlatDict.b = FlatDict.a, and their values will be synced.

Attributes:

Name	Type	Description
indent	int	Indentation level in printing and dumping to json or yaml.

Notes

FlatDict rewrite __getattribute__ and __getattr__ to supports attribute-style access to its members. Therefore, all internal attributes should be set and get through FlatDict.setattr and FlatDict.getattr.

Although it is possible to override other internal methods, it is not recommended to do so.

__class__, __dict__, and getattr are reserved and cannot be overrided in any manner.

Examples:

Python Console Session

>>> d = FlatDict()
>>> d.d = 1013
>>> d['d']
1013
>>> d['i'] = 1013
>>> d.i
1013
>>> d.a = Variable(1)
>>> d.b = d.a
>>> d.a, d.b
(1, 1)
>>> d.a += 1
>>> d.a, d.b
(2, 2)
>>> d.a = 3
>>> d.a, d.b
(3, 3)
>>> d.a = Variable('hello')
>>> f"{d.a}, world!"
'hello, world!'
>>> d.a = d.a + ', world!'
>>> d.b
'hello, world!'

Source code in chanfig/flat_dict.py

class FlatDict(dict):
    r"""
    `FlatDict` with attribute-style access.

    `FlatDict` inherits from built-in `dict`.

    It comes with many easy to use helper function, such as `difference`, `intersect`.

    It also has full support for IO operations, such as `json` and `yaml`.

    Even better, `FlatDict` has pytorch support built-in.
    You can directly call `FlatDict.cpu()` or `FlatDict.to("cpu")` to move all `torch.Tensor` objects across devices.

    `FlatDict` works best with `Variable` objects.
    Just simply call ``FlatDict.a = Variable(1); FlatDict.b = FlatDict.a``, and their values will be synced.

    Attributes:
        indent: Indentation level in printing and dumping to json or yaml.

    Notes:
        `FlatDict` rewrite `__getattribute__` and `__getattr__` to supports attribute-style access to its members.
        Therefore, all internal attributes should be set and get through `FlatDict.setattr` and `FlatDict.getattr`.

        Although it is possible to override other internal methods, it is not recommended to do so.

        `__class__`, `__dict__`, and `getattr` are reserved and cannot be overrided in any manner.

    Examples:
        >>> d = FlatDict()
        >>> d.d = 1013
        >>> d['d']
        1013
        >>> d['i'] = 1013
        >>> d.i
        1013
        >>> d.a = Variable(1)
        >>> d.b = d.a
        >>> d.a, d.b
        (1, 1)
        >>> d.a += 1
        >>> d.a, d.b
        (2, 2)
        >>> d.a = 3
        >>> d.a, d.b
        (3, 3)
        >>> d.a = Variable('hello')
        >>> f"{d.a}, world!"
        'hello, world!'
        >>> d.a = d.a + ', world!'
        >>> d.b
        'hello, world!'
    """

    # pylint: disable=R0904

    indent: int = 2

    def __init__(self, *args, **kwargs) -> None:
        super().__init__()
        self._init(*args, **kwargs)

    def _init(self, *args, **kwargs) -> None:
        r"""
        Initialise values from arguments for `FlatDict`.

        This method is called in `__init__`.
        """

        if len(args) == 1:
            args = args[0]
            if isinstance(args, Mapping):
                for key, value in args.items():
                    self.set(key, value)
            elif isinstance(args, Iterable):
                for key, value in args:
                    self.set(key, value)
        else:
            for key, value in args:
                self.set(key, value)
        for key, value in kwargs.items():
            self.set(key, value)

    def __getattribute__(self, name: Any) -> Any:
        if name not in ("__class__", "__dict__", "getattr") and name in self:
            return self.get(name)
        return super().__getattribute__(name)

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

        Args:
            name:
            default:

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

        Raises:
            KeyError: If `FlatDict` does not contain `name` and `default` is not specified.

        Examples:
            >>> d = FlatDict(d=1013)
            >>> d.get('d')
            1013
            >>> d['d']
            1013
            >>> d.d
            1013
            >>> d.get('d', None)
            1013
            >>> d.get('f', 2)
            2
            >>> d.get('f')
            Traceback (most recent call last):
            KeyError: 'f'
        """

        if name in self:
            return dict.__getitem__(self, name)
        if default is not Null:
            return default
        return self.__missing__(name)

    def __getitem__(self, name: Any) -> Any:
        return self.get(name)

    def __getattr__(self, name: Any) -> Any:
        try:
            return self.get(name)
        except KeyError:
            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'") from None

    def set(self, name: Any, value: Any) -> None:
        r"""
        Set value of `FlatDict`.

        Args:
            name:
            value:

        Examples:
            >>> d = FlatDict()
            >>> d.set('d', 1013)
            >>> d.get('d')
            1013
            >>> d['n'] = 'chang'
            >>> d.n
            'chang'
            >>> d.n = 'liu'
            >>> d['n']
            'liu'
        """

        if isinstance(value, str):
            try:
                value = literal_eval(value)
            except (TypeError, ValueError, SyntaxError):
                pass
        if name in self and isinstance(self.get(name), Variable):
            self.get(name).set(value)
        else:
            dict.__setitem__(self, name, value)

    def __setitem__(self, name: Any, value: Any) -> None:
        self.set(name, value)

    def __setattr__(self, name: Any, value: Any) -> None:
        try:
            self.set(name, value)
        except KeyError:
            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'") from None

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

        Args:
            name:

        Examples:
            >>> d = FlatDict(d=1016, n='chang')
            >>> d.d
            1016
            >>> d.n
            'chang'
            >>> d.delete('d')
            >>> d.d
            Traceback (most recent call last):
            AttributeError: 'FlatDict' object has no attribute 'd'
            >>> del d.n
            >>> d.n
            Traceback (most recent call last):
            AttributeError: 'FlatDict' object has no attribute 'n'
            >>> del d.f
            Traceback (most recent call last):
            AttributeError: 'FlatDict' object has no attribute 'f'
        """

        dict.__delitem__(self, name)

    def __delitem__(self, name: Any) -> None:
        return self.delete(name)

    def __delattr__(self, name: Any) -> None:
        try:
            self.delete(name)
        except KeyError:
            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'") from None

    def __missing__(self, name: Any) -> Any:  # pylint: disable=R1710
        raise KeyError(name)

    def getattr(self, name: str, default: Any = Null) -> Any:
        r"""
        Get attribute of `FlatDict`.

        Note that it won't retrieve value in `FlatDict`,

        Args:
            name:
            default:

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

        Raises:
            AttributeError: If `FlatDict` does not contain `name` and `default` is not specified.

        Examples:
            >>> d = FlatDict(a=1)
            >>> d.get('a')
            1
            >>> d.getattr('a')
            Traceback (most recent call last):
            AttributeError: 'FlatDict' object has no attribute 'a'
            >>> d.getattr('b', 2)
            2
            >>> d.setattr('b', 3)
            >>> d.getattr('b')
            3
        """

        try:
            if name in self.__dict__:
                return self.__dict__[name]
            if name in self.__class__.__dict__:
                return self.__class__.__dict__[name]
            return super().getattr(name, default)  # type: ignore
        except AttributeError:
            if default is not Null:
                return default
            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'") from None

    def setattr(self, name: str, value: Any) -> None:
        r"""
        Set attribute of `FlatDict`.

        Note that it won't alter values in `FlatDict`.

        Args:
            name:
            value:

        Warns:
            RuntimeWarning: If name already exists in `FlatDict`.

        Examples:
            >>> d = FlatDict()
            >>> d.setattr('attr', 'value')
            >>> d.getattr('attr')
            'value'
            >>> d.set('d', 1013)
            >>> d.setattr('d', 1031)  # RuntimeWarning: d already exists in FlatDict.
            >>> d.get('d')
            1013
            >>> d.d
            1013
            >>> d.getattr('d')
            1031
        """

        if name in self:
            warn(
                f"{name} already exists in {self.__class__.__name__}.\n"
                f"Users must call `{self.__class__.__name__}.getattr()` to retrieve conflicting attribute value.",
                RuntimeWarning,
            )
        self.__dict__[name] = value

    def delattr(self, name: str) -> None:
        r"""
        Delete attribute of `FlatDict`.

        Note that it won't delete values in `FlatDict`.

        Args:
            name:

        Examples:
            >>> d = FlatDict()
            >>> d.setattr('name', 'chang')
            >>> d.getattr('name')
            'chang'
            >>> d.delattr('name')
            >>> d.getattr('name')
            Traceback (most recent call last):
            AttributeError: 'FlatDict' object has no attribute 'name'
        """

        del self.__dict__[name]

    def hasattr(self, name: str) -> bool:
        r"""
        Determine if an attribute exists in `FlatDict`.

        Args:
            name:

        Returns:
            (bool):

        Examples:
            >>> d = FlatDict()
            >>> d.setattr('name', 'chang')
            >>> d.hasattr('name')
            True
            >>> d.delattr('name')
            >>> d.hasattr('name')
            False
        """

        try:
            if name in self.__dict__ or name in self.__class__.__dict__:
                return True
            return super().hasattr(name)  # type: ignore
        except AttributeError:
            return False

    def dict(self, cls: Callable = dict) -> Mapping:
        r"""
        Convert `FlatDict` to other `Mapping`.

        Args:
            cls: Target class to be converted to.

        Returns:
            (Mapping):

        See Also:
            [`to_dict`][chanfig.flat_dict.to_dict]: implementation of `dict` method.

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> d.dict()
            {'a': 1, 'b': 2, 'c': 3}
        """

        return cls(to_dict(self))

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

        Args:
            other:

        Returns:
            self:

        **Alias**:

        + `merge_from_file`
        + `union`

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}
            >>> d.merge(n).dict()
            {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}
            >>> l = [('c', 3), ('d', 4)]
            >>> d.merge(l).dict()
            {'a': 1, 'b': 'b', 'c': 3, 'd': 4}
            >>> d.merge("example.yaml").dict()
            {'a': 1, 'b': 2, 'c': 3, 'd': 4}
            >>> FlatDict(a=1, b=1, c=1).merge_from_file("example.yaml").dict()  # alias
            {'a': 1, 'b': 2, 'c': 3}
            >>> FlatDict(a=1, b=1, c=1).union(FlatDict(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, FlatDict):
            other = FlatDict(other)
        for name, value in other.items():
            self.set(name, value)
        return self

    def merge_from_file(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
        r"""
        Alias of [`merge`][chanfig.FlatDict.merge].
        """
        return self.merge(other)

    def union(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
        r"""
        Alias of [`merge`][chanfig.FlatDict.merge].
        """
        return self.merge(other)

    def intersect(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
        r"""
        Intersection of `FlatDict` and `other`.

        Args:
            other (Mapping | Iterable | PathStr):

        Returns:
            (FlatDict):

        **Alias**:

        + `inter`

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

        if isinstance(other, (PathLike, str, bytes)):
            other = self.load(other)
        if isinstance(other, (Mapping,)):
            other = other.items()
        if not isinstance(other, Iterable):
            raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")
        return self.empty_like(
            **{key: value for key, value in other if key in self and self[key] == value}  # type: ignore
        )

    def inter(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
        r"""
        Alias of [`intersect`][chanfig.FlatDict.intersect].
        """
        return self.intersect(other)

    def difference(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
        r"""
        Difference between `FlatDict` and `other`.

        Args:
            other:

        Returns:
            (FlatDict):

        **Alias**:

        + `diff`

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

        if isinstance(other, (PathLike, str, bytes)):
            other = self.load(other)
        if isinstance(other, (Mapping,)):
            other = other.items()
        if not isinstance(other, Iterable):
            raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")
        return self.empty_like(
            **{key: value for key, value in other if key not in self or self[key] != value}  # type: ignore
        )

    def diff(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
        r"""
        Alias of [`difference`][chanfig.FlatDict.difference].
        """
        return self.difference(other)

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

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

        Returns:
            self:

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> d.to(int)
            Traceback (most recent call last):
            TypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.
        """

        # pylint: disable=C0103

        if isinstance(cls, str):
            if cls in ("cpu", "gpu", "cuda", "tpu", "xla"):
                return getattr(self, cls)()
        if isinstance(cls, (TorchDevice, TorchDtype)):
            for k, v in self.items():
                if hasattr(v, "to"):
                    self[k] = v.to(cls)
            return self

        raise TypeError(f"to() only support torch.dtype and torch.device, but got {cls}.")

    def cpu(self) -> FlatDict:  # pylint: disable=C0103
        r"""
        Move all tensors to cpu.

        Returns:
            self:

        Examples:
            >>> import torch
            >>> d = FlatDict(a=torch.tensor(1))
            >>> d.cpu().dict()  # doctest: +SKIP
            {'a': tensor(1, device='cpu')}
        """

        return self.to(TorchDevice("cpu"))

    def gpu(self) -> FlatDict:  # pylint: disable=C0103
        r"""
        Move all tensors to gpu.

        Returns:
            self:

        **Alias**:

        + `cuda`

        Examples:
            >>> import torch
            >>> d = FlatDict(a=torch.tensor(1))
            >>> d.gpu().dict()  # doctest: +SKIP
            {'a': tensor(1, device='cuda:0')}
            >>> d.cuda().dict()  # alias  # doctest: +SKIP
            {'a': tensor(1, device='cuda:0')}
        """

        return self.to(TorchDevice("cuda"))

    def cuda(self) -> FlatDict:
        r"""
        Alias of [`gpu`][chanfig.FlatDict.gpu].
        """
        return self.gpu()

    def tpu(self) -> FlatDict:
        r"""
        Move all tensors to tpu.

        Returns:
            self:

        **Alias**:

        + `xla`

        Examples:
            >>> import torch
            >>> d = FlatDict(a=torch.tensor(1))
            >>> d.tpu().dict()  # doctest: +SKIP
            {'a': tensor(1, device='xla:0')}
            >>> d.xla().dict()  # alias  # doctest: +SKIP
            {'a': tensor(1, device='xla:0')}
        """

        return self.to(TorchDevice("xla"))

    def xla(self) -> FlatDict:
        r"""
        Alias of [`tpu`][chanfig.FlatDict.tpu].
        """
        return self.tpu()

    def copy(self) -> FlatDict:
        r"""
        Create a shallow copy of `FlatDict`.

        Returns:
            (FlatDict):

        Examples:
            >>> d = FlatDict(a=[])
            >>> d.setattr("name", "Chang")
            >>> c = d.copy()
            >>> c.dict()
            {'a': []}
            >>> d.a.append(1)
            >>> c.dict()
            {'a': [1]}
            >>> c.getattr("name")
            'Chang'
        """

        return copy(self)

    def __deepcopy__(self, memo: Optional[Mapping] = None) -> FlatDict:
        # pylint: disable=C0103

        if memo is not None and id(self) in memo:
            return memo[id(self)]
        ret = self.empty_like()
        for k, v in self.items():
            if isinstance(v, FlatDict):
                ret[k] = v.deepcopy(memo=memo)
            else:
                ret[k] = deepcopy(v)
        return ret

    def deepcopy(self, memo: Optional[Mapping] = None) -> FlatDict:  # pylint: disable=W0613
        r"""
        Create a deep copy of `FlatDict`.

        Returns:
            (FlatDict):

        **Alias**:

        + `clone`

        Examples:
            >>> d = FlatDict(a=[])
            >>> d.setattr("name", "Chang")
            >>> c = d.deepcopy()
            >>> c.dict()
            {'a': []}
            >>> d.a.append(1)
            >>> c.dict()
            {'a': []}
            >>> c.getattr("name")
            'Chang'
            >>> d == d.clone()  # alias
            True
        """

        return deepcopy(self)

    def clone(self, memo: Optional[Mapping] = None) -> FlatDict:
        r"""
        Alias of [`deepcopy`][chanfig.FlatDict.deepcopy].
        """
        return self.deepcopy(memo=memo)

    def dump(self, file: File, method: Optional[str] = None, *args, **kwargs) -> None:  # pylint: disable=W1113
        r"""
        Dump `FlatDict` to file.

        Raises:
            ValueError: If dump to `IO` and `method` is not specified.
            TypeError: If dump to unsupported extension.

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> d.dump("example.yaml")
            >>> d.dump("example.conf")
            Traceback (most recent call last):
            TypeError: `file='example.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.
            >>> with open("test.yaml", "w") as f:
            ...     d.dump(f)
            Traceback (most recent call last):
            ValueError: `method` must be specified when dumping to IO.
        """

        if method is None:
            if isinstance(file, IOBase):
                raise ValueError("`method` must be specified when dumping to IO.")
            method = splitext(file)[-1][1:]  # type: ignore
        extension = method.lower()  # type: ignore
        if extension in YAML:
            return self.yaml(file=file, *args, **kwargs)  # type: ignore
        if extension in JSON:
            return self.json(file=file, *args, **kwargs)  # type: ignore
        raise TypeError(f"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.")  # type: ignore

    @classmethod
    def load(cls, file: File, method: Optional[str] = None, *args, **kwargs) -> FlatDict:  # pylint: disable=W1113
        """
        Load `FlatDict` from file.

        Args:
            file: File to load from.
            method: File type, should be in `JSON` or `YAML`.

        Returns:
            (FlatDict):

        Raises:
            ValueError: If load from `IO` and `method` is not specified.
            TypeError: If dump to unsupported extension.

        Examples:
            >>> d = FlatDict.load("example.yaml")
            >>> d.dict()
            {'a': 1, 'b': 2, 'c': 3}
            >>> d.load("example.conf")
            Traceback (most recent call last):
            TypeError: `file='example.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.
            >>> with open("test.yaml") as f:
            ...     d.load(f)
            Traceback (most recent call last):
            ValueError: `method` must be specified when loading from IO.
        """

        if method is None:
            if isinstance(file, IOBase):
                raise ValueError("`method` must be specified when loading from IO.")
            method = splitext(file)[-1][1:]  # type: ignore
        extension = method.lower()  # type: ignore
        if extension in JSON:
            return cls.from_json(file, *args, **kwargs)
        if extension in YAML:
            return cls.from_yaml(file, *args, **kwargs)
        raise TypeError(f"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.")

    def json(self, file: File, *args, **kwargs) -> None:
        r"""
        Dump `FlatDict` to json file.

        This function calls `self.jsons()` to generate json string.
        You may overwrite `jsons` in case something is not json serializable.

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> d.json("example.json")
        """

        with self.open(file, mode="w") as fp:  # pylint: disable=C0103
            fp.write(self.jsons(*args, **kwargs))

    @classmethod
    def from_json(cls, file: File, *args, **kwargs) -> FlatDict:
        r"""
        Construct `FlatDict` from json file.

        This function calls `self.from_jsons()` to construct object from json string.
        You may overwrite `from_jsons` in case something is not json serializable.

        Returns:
            (FlatDict):

        Examples:
            >>> d = FlatDict.from_json('example.json')
            >>> d.dict()
            {'a': 1, 'b': 2, 'c': 3}
        """

        with cls.open(file) as fp:  # pylint: disable=C0103
            return cls.from_jsons(fp.read(), *args, **kwargs)

    def jsons(self, *args, **kwargs) -> str:
        r"""
        Dump `FlatDict` to json string.

        Returns:
            (str):

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> d.jsons()
            '{\n  "a": 1,\n  "b": 2,\n  "c": 3\n}'
        """

        if "cls" not in kwargs:
            kwargs["cls"] = JsonEncoder
        if "indent" not in kwargs:
            kwargs["indent"] = self.getattr("indent", 2)
        return json_dumps(self.dict(), *args, **kwargs)

    @classmethod
    def from_jsons(cls, string: str, *args, **kwargs) -> FlatDict:
        r"""
        Construct `FlatDict` from json string.

        Returns:
            (FlatDict):

        Examples:
            >>> d = FlatDict.from_jsons('{\n  "a": 1,\n  "b": 2,\n  "c": 3\n}')
            >>> d.dict()
            {'a': 1, 'b': 2, 'c': 3}
        """

        config = cls()
        config._init(json_loads(string, *args, **kwargs))  # pylint: disable=W0212
        return config

    def yaml(self, file: File, *args, **kwargs) -> None:
        r"""
        Dump `FlatDict` to yaml file.

        This function calls `self.yamls()` to generate yaml string.
        You may overwrite `yamls` in case something is not yaml serializable.

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> d.yaml("example.yaml")
        """

        with self.open(file, mode="w") as fp:  # pylint: disable=C0103
            self.yamls(fp, *args, **kwargs)

    @classmethod
    def from_yaml(cls, file: File, *args, **kwargs) -> FlatDict:
        r"""
        Construct `FlatDict` from yaml file.

        This function calls `self.from_yamls()` to construct object from yaml string.
        You may overwrite `from_yamls` in case something is not yaml serializable.

        Returns:
            (FlatDict):

        Examples:
            >>> d = FlatDict.from_yaml('example.yaml')
            >>> d.dict()
            {'a': 1, 'b': 2, 'c': 3}
        """

        with cls.open(file) as fp:  # pylint: disable=C0103
            return cls.from_yamls(fp.read(), *args, **kwargs)

    def yamls(self, *args, **kwargs) -> str:
        r"""
        Dump `FlatDict` to yaml string.

        Returns:
            (str):

        Examples:
            >>> d = FlatDict(a=1, b=2, c=3)
            >>> d.yamls()
            'a: 1\nb: 2\nc: 3\n'
        """

        if "Dumper" not in kwargs:
            kwargs["Dumper"] = YamlDumper
        if "indent" not in kwargs:
            kwargs["indent"] = self.getattr("indent", 2)
        return yaml_dump(self.dict(), *args, **kwargs)  # type: ignore

    @classmethod
    def from_yamls(cls, string: str, *args, **kwargs) -> FlatDict:
        r"""
        Construct `FlatDict` from yaml string.

        Returns:
            (FlatDict):

        Examples:
            >>> d = FlatDict.from_yamls('a: 1\nb: 2\nc: 3\n')
            >>> d.dict()
            {'a': 1, 'b': 2, 'c': 3}
        """

        if "Loader" not in kwargs:
            kwargs["Loader"] = YamlLoader

        config = cls()
        config._init(yaml_load(string, *args, **kwargs))  # pylint: disable=W0212
        return config

    @staticmethod
    @contextmanager
    def open(file: File, *args, **kwargs):
        r"""
        Open file IO from file path or IO.

        This methods extends the ability of built-in `open` by allowing it to accept an `IOBase` object.

        Args:
            file: File path or IO.
            *args: Additional arguments passed to `open`.
                Defaults to ().
            **kwargs: Any
                Additional keyword arguments passed to `open`.
                Defaults to {}.

        Yields:
            (FileIO):

        Examples:
            >>> with FlatDict.open("example.yaml") as fp:
            ...     print(fp.read())
            a: 1
            b: 2
            c: 3
            <BLANKLINE>
            >>> io = open("example.yaml")
            >>> with FlatDict.open(io) as fp:
            ...     print(fp.read())
            a: 1
            b: 2
            c: 3
            <BLANKLINE>
        """

        if isinstance(file, (PathLike, str)):
            file = open(file, *args, **kwargs)  # pylint: disable=W1514
            try:
                yield file
            finally:
                file.close()  # type: ignore
        elif isinstance(file, (IOBase,)):
            yield file
        else:
            raise TypeError(
                f"`file={file!r}` should be of type (str, os.PathLike) or (io.IOBase), but got {type(file)}."
            )

    @classmethod
    def empty(cls, *args, **kwargs) -> FlatDict:
        r"""
        Initialise an empty `FlatDict`.

        This method is helpful when you inheriting `FlatDict` with default values defined in `__init__()`.
        As use `type(self)()` in this case would copy all the default values, which might not be desired.

        This method will preserve everything in `FlatDict.__class__.__dict__`.

        Returns:
            (FlatDict):

        Examples:
            >>> d = FlatDict(a=[])
            >>> c = d.empty()
            >>> c.dict()
            {}
        """

        empty = cls.__new__(cls)
        empty._init(*args, **kwargs)  # pylint: disable=W0212
        return empty

    def empty_like(self, *args, **kwargs) -> FlatDict:
        r"""
        Initialise an empty copy of `FlatDict`.

        This method will preserve everything in `FlatDict.__class__.__dict__` and `FlatDict.__dict__`.

        Returns:
            (FlatDict):

        Examples:
            >>> d = FlatDict(a=[])
            >>> d.setattr("name", "Chang")
            >>> c = d.empty_like()
            >>> c.dict()
            {}
            >>> c.getattr("name")
            'Chang'
        """

        empty = self.empty(*args, **kwargs)
        empty.__dict__.update(self.__dict__)
        return empty

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

        Returns:
            (FlatDict):

        **Alias**:

        + `dropna`

        Examples:
            >>> d = FlatDict(a=Null, b=Null, c=3)
            >>> d.dict()
            {'a': Null, 'b': Null, 'c': 3}
            >>> d.dropnull().dict()
            {'c': 3}
            >>> d.dropna().dict()  # alias
            {'c': 3}
        """

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

    def dropna(self) -> FlatDict:
        r"""
        Alias of [`dropnull`][chanfig.FlatDict.dropnull].
        """
        return self.dropnull()

    @staticmethod
    def extra_repr() -> str:  # pylint: disable=C0116
        return ""

    def __repr__(self) -> str:
        extra_lines = []
        extra_repr = self.extra_repr()
        # empty string will be split into list ['']
        if extra_repr:
            extra_lines = extra_repr.split("\n")
        child_lines = []
        for key, value in self.items():
            key_repr = repr(key)
            value_repr = repr(value)
            value_repr = self._add_indent(value_repr)
            child_lines.append("(" + key_repr + "): " + value_repr)
        lines = extra_lines + child_lines

        main_repr = self.__class__.__name__ + "("
        if lines:
            # simple one-liner info, which most builtin Modules will use
            if len(extra_lines) == 1 and not child_lines:
                main_repr += extra_lines[0]
            else:
                main_repr += "\n  " + "\n  ".join(lines) + "\n"

        main_repr += ")"
        return main_repr

    def _add_indent(self, text: str) -> str:
        lines = text.split("\n")
        # don't do anything for single-line stuff
        if len(lines) == 1:
            return text
        first = lines.pop(0)
        lines = [(self.getattr("indent", 2) * " ") + line for line in lines]
        text = "\n".join(lines)
        text = first + "\n" + text
        return text

    def __hash__(self):
        return hash(frozenset(self.items()))

    def __getstate__(self, *args, **kwargs):
        return self.__dict__

    def __setstate__(self, states, *args, **kwargs):
        for name, value in states.items():
            self.setattr(name, value)

    def __wrapped__(self, *args, **kwargs):
        pass

    def _ipython_display_(self):
        return repr(self)

    def _ipython_canary_method_should_not_exist_(self):
        return None

get(name, default=Null)

Get value from FlatDict.

Parameters:

Name	Type	Description	Default
name	Any		required
default	Any		Null

Returns:

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

Raises:

Type	Description
KeyError	If FlatDict does not contain name and default is not specified.

Examples:

Python Console Session

>>> d = FlatDict(d=1013)
>>> d.get('d')
1013
>>> d['d']
1013
>>> d.d
1013
>>> d.get('d', None)
1013
>>> d.get('f', 2)
2
>>> d.get('f')
Traceback (most recent call last):
KeyError: 'f'

Source code in chanfig/flat_dict.py

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

    Args:
        name:
        default:

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

    Raises:
        KeyError: If `FlatDict` does not contain `name` and `default` is not specified.

    Examples:
        >>> d = FlatDict(d=1013)
        >>> d.get('d')
        1013
        >>> d['d']
        1013
        >>> d.d
        1013
        >>> d.get('d', None)
        1013
        >>> d.get('f', 2)
        2
        >>> d.get('f')
        Traceback (most recent call last):
        KeyError: 'f'
    """

    if name in self:
        return dict.__getitem__(self, name)
    if default is not Null:
        return default
    return self.__missing__(name)

set(name, value)

Set value of FlatDict.

Parameters:

Name	Type	Description	Default
name	Any		required
value	Any		required

Examples:

Python Console Session

>>> d = FlatDict()
>>> d.set('d', 1013)
>>> d.get('d')
1013
>>> d['n'] = 'chang'
>>> d.n
'chang'
>>> d.n = 'liu'
>>> d['n']
'liu'

Source code in chanfig/flat_dict.py

def set(self, name: Any, value: Any) -> None:
    r"""
    Set value of `FlatDict`.

    Args:
        name:
        value:

    Examples:
        >>> d = FlatDict()
        >>> d.set('d', 1013)
        >>> d.get('d')
        1013
        >>> d['n'] = 'chang'
        >>> d.n
        'chang'
        >>> d.n = 'liu'
        >>> d['n']
        'liu'
    """

    if isinstance(value, str):
        try:
            value = literal_eval(value)
        except (TypeError, ValueError, SyntaxError):
            pass
    if name in self and isinstance(self.get(name), Variable):
        self.get(name).set(value)
    else:
        dict.__setitem__(self, name, value)

delete(name)

Delete value from FlatDict.

Parameters:

Name	Type	Description	Default
name	Any		required

Examples:

Python Console Session

>>> d = FlatDict(d=1016, n='chang')
>>> d.d
1016
>>> d.n
'chang'
>>> d.delete('d')
>>> d.d
Traceback (most recent call last):
AttributeError: 'FlatDict' object has no attribute 'd'
>>> del d.n
>>> d.n
Traceback (most recent call last):
AttributeError: 'FlatDict' object has no attribute 'n'
>>> del d.f
Traceback (most recent call last):
AttributeError: 'FlatDict' object has no attribute 'f'

Source code in chanfig/flat_dict.py

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

    Args:
        name:

    Examples:
        >>> d = FlatDict(d=1016, n='chang')
        >>> d.d
        1016
        >>> d.n
        'chang'
        >>> d.delete('d')
        >>> d.d
        Traceback (most recent call last):
        AttributeError: 'FlatDict' object has no attribute 'd'
        >>> del d.n
        >>> d.n
        Traceback (most recent call last):
        AttributeError: 'FlatDict' object has no attribute 'n'
        >>> del d.f
        Traceback (most recent call last):
        AttributeError: 'FlatDict' object has no attribute 'f'
    """

    dict.__delitem__(self, name)

getattr(name, default=Null)

Get attribute of FlatDict.

Note that it won’t retrieve value in FlatDict,

Parameters:

Name	Type	Description	Default
name	str		required
default	Any		Null

Returns:

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

Raises:

Type	Description
AttributeError	If FlatDict does not contain name and default is not specified.

Examples:

Python Console Session

>>> d = FlatDict(a=1)
>>> d.get('a')
1
>>> d.getattr('a')
Traceback (most recent call last):
AttributeError: 'FlatDict' object has no attribute 'a'
>>> d.getattr('b', 2)
2
>>> d.setattr('b', 3)
>>> d.getattr('b')
3

Source code in chanfig/flat_dict.py

def getattr(self, name: str, default: Any = Null) -> Any:
    r"""
    Get attribute of `FlatDict`.

    Note that it won't retrieve value in `FlatDict`,

    Args:
        name:
        default:

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

    Raises:
        AttributeError: If `FlatDict` does not contain `name` and `default` is not specified.

    Examples:
        >>> d = FlatDict(a=1)
        >>> d.get('a')
        1
        >>> d.getattr('a')
        Traceback (most recent call last):
        AttributeError: 'FlatDict' object has no attribute 'a'
        >>> d.getattr('b', 2)
        2
        >>> d.setattr('b', 3)
        >>> d.getattr('b')
        3
    """

    try:
        if name in self.__dict__:
            return self.__dict__[name]
        if name in self.__class__.__dict__:
            return self.__class__.__dict__[name]
        return super().getattr(name, default)  # type: ignore
    except AttributeError:
        if default is not Null:
            return default
        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'") from None

setattr(name, value)

Set attribute of FlatDict.

Note that it won’t alter values in FlatDict.

Parameters:

Name	Type	Description	Default
name	str		required
value	Any		required

Warns:

Type	Description
RuntimeWarning	If name already exists in FlatDict.

Examples:

Python Console Session

>>> d = FlatDict()
>>> d.setattr('attr', 'value')
>>> d.getattr('attr')
'value'
>>> d.set('d', 1013)
>>> d.setattr('d', 1031)  # RuntimeWarning: d already exists in FlatDict.
>>> d.get('d')
1013
>>> d.d
1013
>>> d.getattr('d')
1031

Source code in chanfig/flat_dict.py

def setattr(self, name: str, value: Any) -> None:
    r"""
    Set attribute of `FlatDict`.

    Note that it won't alter values in `FlatDict`.

    Args:
        name:
        value:

    Warns:
        RuntimeWarning: If name already exists in `FlatDict`.

    Examples:
        >>> d = FlatDict()
        >>> d.setattr('attr', 'value')
        >>> d.getattr('attr')
        'value'
        >>> d.set('d', 1013)
        >>> d.setattr('d', 1031)  # RuntimeWarning: d already exists in FlatDict.
        >>> d.get('d')
        1013
        >>> d.d
        1013
        >>> d.getattr('d')
        1031
    """

    if name in self:
        warn(
            f"{name} already exists in {self.__class__.__name__}.\n"
            f"Users must call `{self.__class__.__name__}.getattr()` to retrieve conflicting attribute value.",
            RuntimeWarning,
        )
    self.__dict__[name] = value

delattr(name)

Delete attribute of FlatDict.

Note that it won’t delete values in FlatDict.

Parameters:

Name	Type	Description	Default
name	str		required

Examples:

Python Console Session

>>> d = FlatDict()
>>> d.setattr('name', 'chang')
>>> d.getattr('name')
'chang'
>>> d.delattr('name')
>>> d.getattr('name')
Traceback (most recent call last):
AttributeError: 'FlatDict' object has no attribute 'name'

Source code in chanfig/flat_dict.py

def delattr(self, name: str) -> None:
    r"""
    Delete attribute of `FlatDict`.

    Note that it won't delete values in `FlatDict`.

    Args:
        name:

    Examples:
        >>> d = FlatDict()
        >>> d.setattr('name', 'chang')
        >>> d.getattr('name')
        'chang'
        >>> d.delattr('name')
        >>> d.getattr('name')
        Traceback (most recent call last):
        AttributeError: 'FlatDict' object has no attribute 'name'
    """

    del self.__dict__[name]

hasattr(name)

Determine if an attribute exists in FlatDict.

Parameters:

Name	Type	Description	Default
name	str		required

Returns:

Type	Description
bool

Examples:

Python Console Session

>>> d = FlatDict()
>>> d.setattr('name', 'chang')
>>> d.hasattr('name')
True
>>> d.delattr('name')
>>> d.hasattr('name')
False

Source code in chanfig/flat_dict.py

def hasattr(self, name: str) -> bool:
    r"""
    Determine if an attribute exists in `FlatDict`.

    Args:
        name:

    Returns:
        (bool):

    Examples:
        >>> d = FlatDict()
        >>> d.setattr('name', 'chang')
        >>> d.hasattr('name')
        True
        >>> d.delattr('name')
        >>> d.hasattr('name')
        False
    """

    try:
        if name in self.__dict__ or name in self.__class__.__dict__:
            return True
        return super().hasattr(name)  # type: ignore
    except AttributeError:
        return False

dict(cls=dict)

Convert FlatDict to other Mapping.

Parameters:

Name	Type	Description	Default
cls	Callable	Target class to be converted to.	dict

Returns:

Type	Description
Mapping

See Also

to_dict: implementation of dict method.

Examples:

Python Console Session

>>> d = FlatDict(a=1, b=2, c=3)
>>> d.dict()
{'a': 1, 'b': 2, 'c': 3}

Source code in chanfig/flat_dict.py

def dict(self, cls: Callable = dict) -> Mapping:
    r"""
    Convert `FlatDict` to other `Mapping`.

    Args:
        cls: Target class to be converted to.

    Returns:
        (Mapping):

    See Also:
        [`to_dict`][chanfig.flat_dict.to_dict]: implementation of `dict` method.

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> d.dict()
        {'a': 1, 'b': 2, 'c': 3}
    """

    return cls(to_dict(self))

merge(other)

Merge other into FlatDict.

Parameters:

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

Returns:

Name	Type	Description
self	FlatDict

Alias:

• merge_from_file
• union

Examples:

Python Console Session

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

Source code in chanfig/flat_dict.py

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

    Args:
        other:

    Returns:
        self:

    **Alias**:

    + `merge_from_file`
    + `union`

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}
        >>> d.merge(n).dict()
        {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}
        >>> l = [('c', 3), ('d', 4)]
        >>> d.merge(l).dict()
        {'a': 1, 'b': 'b', 'c': 3, 'd': 4}
        >>> d.merge("example.yaml").dict()
        {'a': 1, 'b': 2, 'c': 3, 'd': 4}
        >>> FlatDict(a=1, b=1, c=1).merge_from_file("example.yaml").dict()  # alias
        {'a': 1, 'b': 2, 'c': 3}
        >>> FlatDict(a=1, b=1, c=1).union(FlatDict(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, FlatDict):
        other = FlatDict(other)
    for name, value in other.items():
        self.set(name, value)
    return self

merge_from_file(other)

Alias of merge.

Source code in chanfig/flat_dict.py

def merge_from_file(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
    r"""
    Alias of [`merge`][chanfig.FlatDict.merge].
    """
    return self.merge(other)

union(other)

Alias of merge.

Source code in chanfig/flat_dict.py

def union(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
    r"""
    Alias of [`merge`][chanfig.FlatDict.merge].
    """
    return self.merge(other)

intersect(other)

Intersection of FlatDict and other.

Parameters:

Name	Type	Description	Default
other	Mapping | Iterable | PathStr		required

Returns:

Type	Description
FlatDict

Alias:

• inter

Examples:

Python Console Session

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

Source code in chanfig/flat_dict.py

def intersect(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
    r"""
    Intersection of `FlatDict` and `other`.

    Args:
        other (Mapping | Iterable | PathStr):

    Returns:
        (FlatDict):

    **Alias**:

    + `inter`

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

    if isinstance(other, (PathLike, str, bytes)):
        other = self.load(other)
    if isinstance(other, (Mapping,)):
        other = other.items()
    if not isinstance(other, Iterable):
        raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")
    return self.empty_like(
        **{key: value for key, value in other if key in self and self[key] == value}  # type: ignore
    )

inter(other)

Alias of intersect.

Source code in chanfig/flat_dict.py

def inter(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
    r"""
    Alias of [`intersect`][chanfig.FlatDict.intersect].
    """
    return self.intersect(other)

difference(other)

Difference between FlatDict and other.

Parameters:

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

Returns:

Type	Description
FlatDict

Alias:

• diff

Examples:

Python Console Session

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

Source code in chanfig/flat_dict.py

def difference(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
    r"""
    Difference between `FlatDict` and `other`.

    Args:
        other:

    Returns:
        (FlatDict):

    **Alias**:

    + `diff`

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

    if isinstance(other, (PathLike, str, bytes)):
        other = self.load(other)
    if isinstance(other, (Mapping,)):
        other = other.items()
    if not isinstance(other, Iterable):
        raise TypeError(f"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.")
    return self.empty_like(
        **{key: value for key, value in other if key not in self or self[key] != value}  # type: ignore
    )

diff(other)

Alias of difference.

Source code in chanfig/flat_dict.py

def diff(self, other: Union[Mapping, Iterable, PathStr]) -> FlatDict:
    r"""
    Alias of [`difference`][chanfig.FlatDict.difference].
    """
    return self.difference(other)

to(cls)

Convert values of FlatDict to target cls.

Parameters:

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

Returns:

Name	Type	Description
self	FlatDict

Examples:

Python Console Session

>>> d = FlatDict(a=1, b=2, c=3)
>>> d.to(int)
Traceback (most recent call last):
TypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.

Source code in chanfig/flat_dict.py

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

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

    Returns:
        self:

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> d.to(int)
        Traceback (most recent call last):
        TypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.
    """

    # pylint: disable=C0103

    if isinstance(cls, str):
        if cls in ("cpu", "gpu", "cuda", "tpu", "xla"):
            return getattr(self, cls)()
    if isinstance(cls, (TorchDevice, TorchDtype)):
        for k, v in self.items():
            if hasattr(v, "to"):
                self[k] = v.to(cls)
        return self

    raise TypeError(f"to() only support torch.dtype and torch.device, but got {cls}.")

cpu()

Move all tensors to cpu.

Returns:

Name	Type	Description
self	FlatDict

Examples:

Python Console Session

>>> import torch
>>> d = FlatDict(a=torch.tensor(1))
>>> d.cpu().dict()
{'a': tensor(1, device='cpu')}

Source code in chanfig/flat_dict.py

def cpu(self) -> FlatDict:  # pylint: disable=C0103
    r"""
    Move all tensors to cpu.

    Returns:
        self:

    Examples:
        >>> import torch
        >>> d = FlatDict(a=torch.tensor(1))
        >>> d.cpu().dict()  # doctest: +SKIP
        {'a': tensor(1, device='cpu')}
    """

    return self.to(TorchDevice("cpu"))

gpu()

Move all tensors to gpu.

Returns:

Name	Type	Description
self	FlatDict

Alias:

• cuda

Examples:

Python Console Session

>>> import torch
>>> d = FlatDict(a=torch.tensor(1))
>>> d.gpu().dict()
{'a': tensor(1, device='cuda:0')}
>>> d.cuda().dict()  # alias
{'a': tensor(1, device='cuda:0')}

Source code in chanfig/flat_dict.py

def gpu(self) -> FlatDict:  # pylint: disable=C0103
    r"""
    Move all tensors to gpu.

    Returns:
        self:

    **Alias**:

    + `cuda`

    Examples:
        >>> import torch
        >>> d = FlatDict(a=torch.tensor(1))
        >>> d.gpu().dict()  # doctest: +SKIP
        {'a': tensor(1, device='cuda:0')}
        >>> d.cuda().dict()  # alias  # doctest: +SKIP
        {'a': tensor(1, device='cuda:0')}
    """

    return self.to(TorchDevice("cuda"))

cuda()

Alias of gpu.

Source code in chanfig/flat_dict.py

def cuda(self) -> FlatDict:
    r"""
    Alias of [`gpu`][chanfig.FlatDict.gpu].
    """
    return self.gpu()

tpu()

Move all tensors to tpu.

Returns:

Name	Type	Description
self	FlatDict

Alias:

• xla

Examples:

Python Console Session

>>> import torch
>>> d = FlatDict(a=torch.tensor(1))
>>> d.tpu().dict()
{'a': tensor(1, device='xla:0')}
>>> d.xla().dict()  # alias
{'a': tensor(1, device='xla:0')}

Source code in chanfig/flat_dict.py

def tpu(self) -> FlatDict:
    r"""
    Move all tensors to tpu.

    Returns:
        self:

    **Alias**:

    + `xla`

    Examples:
        >>> import torch
        >>> d = FlatDict(a=torch.tensor(1))
        >>> d.tpu().dict()  # doctest: +SKIP
        {'a': tensor(1, device='xla:0')}
        >>> d.xla().dict()  # alias  # doctest: +SKIP
        {'a': tensor(1, device='xla:0')}
    """

    return self.to(TorchDevice("xla"))

xla()

Alias of tpu.

Source code in chanfig/flat_dict.py

def xla(self) -> FlatDict:
    r"""
    Alias of [`tpu`][chanfig.FlatDict.tpu].
    """
    return self.tpu()

copy()

Create a shallow copy of FlatDict.

Returns:

Type	Description
FlatDict

Examples:

Python Console Session

>>> d = FlatDict(a=[])
>>> d.setattr("name", "Chang")
>>> c = d.copy()
>>> c.dict()
{'a': []}
>>> d.a.append(1)
>>> c.dict()
{'a': [1]}
>>> c.getattr("name")
'Chang'

Source code in chanfig/flat_dict.py

def copy(self) -> FlatDict:
    r"""
    Create a shallow copy of `FlatDict`.

    Returns:
        (FlatDict):

    Examples:
        >>> d = FlatDict(a=[])
        >>> d.setattr("name", "Chang")
        >>> c = d.copy()
        >>> c.dict()
        {'a': []}
        >>> d.a.append(1)
        >>> c.dict()
        {'a': [1]}
        >>> c.getattr("name")
        'Chang'
    """

    return copy(self)

deepcopy(memo=None)

Create a deep copy of FlatDict.

Returns:

Type	Description
FlatDict

Alias:

• clone

Examples:

Python Console Session

>>> d = FlatDict(a=[])
>>> d.setattr("name", "Chang")
>>> c = d.deepcopy()
>>> c.dict()
{'a': []}
>>> d.a.append(1)
>>> c.dict()
{'a': []}
>>> c.getattr("name")
'Chang'
>>> d == d.clone()  # alias
True

Source code in chanfig/flat_dict.py

def deepcopy(self, memo: Optional[Mapping] = None) -> FlatDict:  # pylint: disable=W0613
    r"""
    Create a deep copy of `FlatDict`.

    Returns:
        (FlatDict):

    **Alias**:

    + `clone`

    Examples:
        >>> d = FlatDict(a=[])
        >>> d.setattr("name", "Chang")
        >>> c = d.deepcopy()
        >>> c.dict()
        {'a': []}
        >>> d.a.append(1)
        >>> c.dict()
        {'a': []}
        >>> c.getattr("name")
        'Chang'
        >>> d == d.clone()  # alias
        True
    """

    return deepcopy(self)

clone(memo=None)

Alias of deepcopy.

Source code in chanfig/flat_dict.py

def clone(self, memo: Optional[Mapping] = None) -> FlatDict:
    r"""
    Alias of [`deepcopy`][chanfig.FlatDict.deepcopy].
    """
    return self.deepcopy(memo=memo)

dump(file, method=None, *args, **kwargs)

Dump FlatDict to file.

Raises:

Type	Description
ValueError	If dump to IO and method is not specified.
TypeError	If dump to unsupported extension.

Examples:

Python Console Session

>>> d = FlatDict(a=1, b=2, c=3)
>>> d.dump("example.yaml")
>>> d.dump("example.conf")
Traceback (most recent call last):
TypeError: `file='example.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.
>>> with open("test.yaml", "w") as f:
...     d.dump(f)
Traceback (most recent call last):
ValueError: `method` must be specified when dumping to IO.

Source code in chanfig/flat_dict.py

def dump(self, file: File, method: Optional[str] = None, *args, **kwargs) -> None:  # pylint: disable=W1113
    r"""
    Dump `FlatDict` to file.

    Raises:
        ValueError: If dump to `IO` and `method` is not specified.
        TypeError: If dump to unsupported extension.

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> d.dump("example.yaml")
        >>> d.dump("example.conf")
        Traceback (most recent call last):
        TypeError: `file='example.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.
        >>> with open("test.yaml", "w") as f:
        ...     d.dump(f)
        Traceback (most recent call last):
        ValueError: `method` must be specified when dumping to IO.
    """

    if method is None:
        if isinstance(file, IOBase):
            raise ValueError("`method` must be specified when dumping to IO.")
        method = splitext(file)[-1][1:]  # type: ignore
    extension = method.lower()  # type: ignore
    if extension in YAML:
        return self.yaml(file=file, *args, **kwargs)  # type: ignore
    if extension in JSON:
        return self.json(file=file, *args, **kwargs)  # type: ignore
    raise TypeError(f"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.")  # type: ignore

load(file, method=None, *args, **kwargs) classmethod

Load FlatDict from file.

Parameters:

Name	Type	Description	Default
file	File	File to load from.	required
method	Optional[str]	File type, should be in JSON or YAML.	None

Returns:

Type	Description
FlatDict

Raises:

Type	Description
ValueError	If load from IO and method is not specified.
TypeError	If dump to unsupported extension.

Examples:

Python Console Session

>>> d = FlatDict.load("example.yaml")
>>> d.dict()
{'a': 1, 'b': 2, 'c': 3}
>>> d.load("example.conf")
Traceback (most recent call last):
TypeError: `file='example.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.
>>> with open("test.yaml") as f:
...     d.load(f)
Traceback (most recent call last):
ValueError: `method` must be specified when loading from IO.

Source code in chanfig/flat_dict.py

@classmethod
def load(cls, file: File, method: Optional[str] = None, *args, **kwargs) -> FlatDict:  # pylint: disable=W1113
    """
    Load `FlatDict` from file.

    Args:
        file: File to load from.
        method: File type, should be in `JSON` or `YAML`.

    Returns:
        (FlatDict):

    Raises:
        ValueError: If load from `IO` and `method` is not specified.
        TypeError: If dump to unsupported extension.

    Examples:
        >>> d = FlatDict.load("example.yaml")
        >>> d.dict()
        {'a': 1, 'b': 2, 'c': 3}
        >>> d.load("example.conf")
        Traceback (most recent call last):
        TypeError: `file='example.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.
        >>> with open("test.yaml") as f:
        ...     d.load(f)
        Traceback (most recent call last):
        ValueError: `method` must be specified when loading from IO.
    """

    if method is None:
        if isinstance(file, IOBase):
            raise ValueError("`method` must be specified when loading from IO.")
        method = splitext(file)[-1][1:]  # type: ignore
    extension = method.lower()  # type: ignore
    if extension in JSON:
        return cls.from_json(file, *args, **kwargs)
    if extension in YAML:
        return cls.from_yaml(file, *args, **kwargs)
    raise TypeError(f"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.")

json(file, *args, **kwargs)

Dump FlatDict to json file.

This function calls self.jsons() to generate json string. You may overwrite jsons in case something is not json serializable.

Examples:

Python Console Session

>>> d = FlatDict(a=1, b=2, c=3)
>>> d.json("example.json")

Source code in chanfig/flat_dict.py

def json(self, file: File, *args, **kwargs) -> None:
    r"""
    Dump `FlatDict` to json file.

    This function calls `self.jsons()` to generate json string.
    You may overwrite `jsons` in case something is not json serializable.

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> d.json("example.json")
    """

    with self.open(file, mode="w") as fp:  # pylint: disable=C0103
        fp.write(self.jsons(*args, **kwargs))

from_json(file, *args, **kwargs) classmethod

Construct FlatDict from json file.

This function calls self.from_jsons() to construct object from json string. You may overwrite from_jsons in case something is not json serializable.

Returns:

Type	Description
FlatDict

Examples:

Python Console Session

>>> d = FlatDict.from_json('example.json')
>>> d.dict()
{'a': 1, 'b': 2, 'c': 3}

Source code in chanfig/flat_dict.py

@classmethod
def from_json(cls, file: File, *args, **kwargs) -> FlatDict:
    r"""
    Construct `FlatDict` from json file.

    This function calls `self.from_jsons()` to construct object from json string.
    You may overwrite `from_jsons` in case something is not json serializable.

    Returns:
        (FlatDict):

    Examples:
        >>> d = FlatDict.from_json('example.json')
        >>> d.dict()
        {'a': 1, 'b': 2, 'c': 3}
    """

    with cls.open(file) as fp:  # pylint: disable=C0103
        return cls.from_jsons(fp.read(), *args, **kwargs)

jsons(*args, **kwargs)

Dump FlatDict to json string.

Returns:

Type	Description
str

Examples:

Python Console Session

>>> d = FlatDict(a=1, b=2, c=3)
>>> d.jsons()
'{\n  "a": 1,\n  "b": 2,\n  "c": 3\n}'

Source code in chanfig/flat_dict.py

def jsons(self, *args, **kwargs) -> str:
    r"""
    Dump `FlatDict` to json string.

    Returns:
        (str):

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> d.jsons()
        '{\n  "a": 1,\n  "b": 2,\n  "c": 3\n}'
    """

    if "cls" not in kwargs:
        kwargs["cls"] = JsonEncoder
    if "indent" not in kwargs:
        kwargs["indent"] = self.getattr("indent", 2)
    return json_dumps(self.dict(), *args, **kwargs)

from_jsons(string, *args, **kwargs) classmethod

Construct FlatDict from json string.

Returns:

Type	Description
FlatDict

Examples:

Python Console Session

>>> d = FlatDict.from_jsons('{\n  "a": 1,\n  "b": 2,\n  "c": 3\n}')
>>> d.dict()
{'a': 1, 'b': 2, 'c': 3}

Source code in chanfig/flat_dict.py

@classmethod
def from_jsons(cls, string: str, *args, **kwargs) -> FlatDict:
    r"""
    Construct `FlatDict` from json string.

    Returns:
        (FlatDict):

    Examples:
        >>> d = FlatDict.from_jsons('{\n  "a": 1,\n  "b": 2,\n  "c": 3\n}')
        >>> d.dict()
        {'a': 1, 'b': 2, 'c': 3}
    """

    config = cls()
    config._init(json_loads(string, *args, **kwargs))  # pylint: disable=W0212
    return config

yaml(file, *args, **kwargs)

Dump FlatDict to yaml file.

This function calls self.yamls() to generate yaml string. You may overwrite yamls in case something is not yaml serializable.

Examples:

Python Console Session

>>> d = FlatDict(a=1, b=2, c=3)
>>> d.yaml("example.yaml")

Source code in chanfig/flat_dict.py

def yaml(self, file: File, *args, **kwargs) -> None:
    r"""
    Dump `FlatDict` to yaml file.

    This function calls `self.yamls()` to generate yaml string.
    You may overwrite `yamls` in case something is not yaml serializable.

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> d.yaml("example.yaml")
    """

    with self.open(file, mode="w") as fp:  # pylint: disable=C0103
        self.yamls(fp, *args, **kwargs)

from_yaml(file, *args, **kwargs) classmethod

Construct FlatDict from yaml file.

This function calls self.from_yamls() to construct object from yaml string. You may overwrite from_yamls in case something is not yaml serializable.

Returns:

Type	Description
FlatDict

Examples:

Python Console Session

>>> d = FlatDict.from_yaml('example.yaml')
>>> d.dict()
{'a': 1, 'b': 2, 'c': 3}

Source code in chanfig/flat_dict.py

@classmethod
def from_yaml(cls, file: File, *args, **kwargs) -> FlatDict:
    r"""
    Construct `FlatDict` from yaml file.

    This function calls `self.from_yamls()` to construct object from yaml string.
    You may overwrite `from_yamls` in case something is not yaml serializable.

    Returns:
        (FlatDict):

    Examples:
        >>> d = FlatDict.from_yaml('example.yaml')
        >>> d.dict()
        {'a': 1, 'b': 2, 'c': 3}
    """

    with cls.open(file) as fp:  # pylint: disable=C0103
        return cls.from_yamls(fp.read(), *args, **kwargs)

yamls(*args, **kwargs)

Dump FlatDict to yaml string.

Returns:

Type	Description
str

Examples:

Python Console Session

>>> d = FlatDict(a=1, b=2, c=3)
>>> d.yamls()
'a: 1\nb: 2\nc: 3\n'

Source code in chanfig/flat_dict.py

def yamls(self, *args, **kwargs) -> str:
    r"""
    Dump `FlatDict` to yaml string.

    Returns:
        (str):

    Examples:
        >>> d = FlatDict(a=1, b=2, c=3)
        >>> d.yamls()
        'a: 1\nb: 2\nc: 3\n'
    """

    if "Dumper" not in kwargs:
        kwargs["Dumper"] = YamlDumper
    if "indent" not in kwargs:
        kwargs["indent"] = self.getattr("indent", 2)
    return yaml_dump(self.dict(), *args, **kwargs)  # type: ignore

from_yamls(string, *args, **kwargs) classmethod

Construct FlatDict from yaml string.

Returns:

Type	Description
FlatDict

Examples:

Python Console Session

>>> d = FlatDict.from_yamls('a: 1\nb: 2\nc: 3\n')
>>> d.dict()
{'a': 1, 'b': 2, 'c': 3}

Source code in chanfig/flat_dict.py

@classmethod
def from_yamls(cls, string: str, *args, **kwargs) -> FlatDict:
    r"""
    Construct `FlatDict` from yaml string.

    Returns:
        (FlatDict):

    Examples:
        >>> d = FlatDict.from_yamls('a: 1\nb: 2\nc: 3\n')
        >>> d.dict()
        {'a': 1, 'b': 2, 'c': 3}
    """

    if "Loader" not in kwargs:
        kwargs["Loader"] = YamlLoader

    config = cls()
    config._init(yaml_load(string, *args, **kwargs))  # pylint: disable=W0212
    return config

open(file, *args, **kwargs) staticmethod

Open file IO from file path or IO.

This methods extends the ability of built-in open by allowing it to accept an IOBase object.

Parameters:

Name	Type	Description	Default
file	File	File path or IO.	required
*args		Additional arguments passed to open. Defaults to ().	()
**kwargs		Any Additional keyword arguments passed to open. Defaults to {}.	{}

Yields:

Type	Description
FileIO

Examples:

Python Console Session

>>> with FlatDict.open("example.yaml") as fp:
...     print(fp.read())
a: 1
b: 2
c: 3

>>> io = open("example.yaml")
>>> with FlatDict.open(io) as fp:
...     print(fp.read())
a: 1
b: 2
c: 3

Source code in chanfig/flat_dict.py

@staticmethod
@contextmanager
def open(file: File, *args, **kwargs):
    r"""
    Open file IO from file path or IO.

    This methods extends the ability of built-in `open` by allowing it to accept an `IOBase` object.

    Args:
        file: File path or IO.
        *args: Additional arguments passed to `open`.
            Defaults to ().
        **kwargs: Any
            Additional keyword arguments passed to `open`.
            Defaults to {}.

    Yields:
        (FileIO):

    Examples:
        >>> with FlatDict.open("example.yaml") as fp:
        ...     print(fp.read())
        a: 1
        b: 2
        c: 3
        <BLANKLINE>
        >>> io = open("example.yaml")
        >>> with FlatDict.open(io) as fp:
        ...     print(fp.read())
        a: 1
        b: 2
        c: 3
        <BLANKLINE>
    """

    if isinstance(file, (PathLike, str)):
        file = open(file, *args, **kwargs)  # pylint: disable=W1514
        try:
            yield file
        finally:
            file.close()  # type: ignore
    elif isinstance(file, (IOBase,)):
        yield file
    else:
        raise TypeError(
            f"`file={file!r}` should be of type (str, os.PathLike) or (io.IOBase), but got {type(file)}."
        )

empty(*args, **kwargs) classmethod

Initialise an empty FlatDict.

This method is helpful when you inheriting FlatDict with default values defined in __init__(). As use type(self)() in this case would copy all the default values, which might not be desired.

This method will preserve everything in FlatDict.__class__.__dict__.

Returns:

Type	Description
FlatDict

Examples:

Python Console Session

>>> d = FlatDict(a=[])
>>> c = d.empty()
>>> c.dict()
{}

Source code in chanfig/flat_dict.py

@classmethod
def empty(cls, *args, **kwargs) -> FlatDict:
    r"""
    Initialise an empty `FlatDict`.

    This method is helpful when you inheriting `FlatDict` with default values defined in `__init__()`.
    As use `type(self)()` in this case would copy all the default values, which might not be desired.

    This method will preserve everything in `FlatDict.__class__.__dict__`.

    Returns:
        (FlatDict):

    Examples:
        >>> d = FlatDict(a=[])
        >>> c = d.empty()
        >>> c.dict()
        {}
    """

    empty = cls.__new__(cls)
    empty._init(*args, **kwargs)  # pylint: disable=W0212
    return empty

empty_like(*args, **kwargs)

Initialise an empty copy of FlatDict.

This method will preserve everything in FlatDict.__class__.__dict__ and FlatDict.__dict__.

Returns:

Type	Description
FlatDict

Examples:

Python Console Session

>>> d = FlatDict(a=[])
>>> d.setattr("name", "Chang")
>>> c = d.empty_like()
>>> c.dict()
{}
>>> c.getattr("name")
'Chang'

Source code in chanfig/flat_dict.py

def empty_like(self, *args, **kwargs) -> FlatDict:
    r"""
    Initialise an empty copy of `FlatDict`.

    This method will preserve everything in `FlatDict.__class__.__dict__` and `FlatDict.__dict__`.

    Returns:
        (FlatDict):

    Examples:
        >>> d = FlatDict(a=[])
        >>> d.setattr("name", "Chang")
        >>> c = d.empty_like()
        >>> c.dict()
        {}
        >>> c.getattr("name")
        'Chang'
    """

    empty = self.empty(*args, **kwargs)
    empty.__dict__.update(self.__dict__)
    return empty

dropnull()

Drop key-value pairs with Null value.

Returns:

Type	Description
FlatDict

Alias:

• dropna

Examples:

Python Console Session

>>> d = FlatDict(a=Null, b=Null, c=3)
>>> d.dict()
{'a': Null, 'b': Null, 'c': 3}
>>> d.dropnull().dict()
{'c': 3}
>>> d.dropna().dict()  # alias
{'c': 3}

Source code in chanfig/flat_dict.py

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

    Returns:
        (FlatDict):

    **Alias**:

    + `dropna`

    Examples:
        >>> d = FlatDict(a=Null, b=Null, c=3)
        >>> d.dict()
        {'a': Null, 'b': Null, 'c': 3}
        >>> d.dropnull().dict()
        {'c': 3}
        >>> d.dropna().dict()  # alias
        {'c': 3}
    """

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

dropna()

Alias of dropnull.

Source code in chanfig/flat_dict.py

def dropna(self) -> FlatDict:
    r"""
    Alias of [`dropnull`][chanfig.FlatDict.dropnull].
    """
    return self.dropnull()

---

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