Skip to content

Functional

Convert an object to a dict.

Note that when converting a set object, it may be converted to a tuple object if its values is not hashable.

Parameters:

Name Type Description Default
obj Any

Object to be converted.

required

Returns:

Type Description
Mapping | list | set | tuple

A dict.

Examples:

Python Console Session
>>> to_dict(1)
1
>>> to_dict([1, 2, 3])
[1, 2, 3]
>>> to_dict((1, 2, 3))
(1, 2, 3)
>>> to_dict({1, 2, 3})
{1, 2, 3}
>>> to_dict({'a': 1, 'b': 2})
{'a': 1, 'b': 2}
>>> to_dict(Variable(1))
1
>>> to_dict(FlatDict(a=[[[[[FlatDict(b=1)]]]]]))
{'a': [[[[[{'b': 1}]]]]]}
>>> to_dict(FlatDict(a={FlatDict(b=1)}))
{'a': ({'b': 1},)}
Source code in chanfig/flat_dict.py
Python
def to_dict(obj: Any) -> Mapping | list | set | tuple:  # pylint: disable=R0911
    r"""
    Convert an object to a dict.

    Note that when converting a `set` object, it may be converted to a `tuple` object if its values is not hashable.

    Args:
        obj: Object to be converted.

    Returns:
        A dict.

    Examples:
        >>> to_dict(1)
        1
        >>> to_dict([1, 2, 3])
        [1, 2, 3]
        >>> to_dict((1, 2, 3))
        (1, 2, 3)
        >>> to_dict({1, 2, 3})
        {1, 2, 3}
        >>> to_dict({'a': 1, 'b': 2})
        {'a': 1, 'b': 2}
        >>> to_dict(Variable(1))
        1
        >>> to_dict(FlatDict(a=[[[[[FlatDict(b=1)]]]]]))
        {'a': [[[[[{'b': 1}]]]]]}
        >>> to_dict(FlatDict(a={FlatDict(b=1)}))
        {'a': ({'b': 1},)}
    """

    if isinstance(obj, Mapping):
        return {k: to_dict(v) for k, v in obj.items()}
    if isinstance(obj, list):
        return [to_dict(v) for v in obj]
    if isinstance(obj, tuple):
        return tuple(to_dict(v) for v in obj)
    if isinstance(obj, set):
        try:
            return {to_dict(v) for v in obj}
        except TypeError:
            return tuple(to_dict(v) for v in obj)
    if isinstance(obj, Variable):
        return obj.value
    return obj

options: heading_level: 0

Save FlatDict to file.

Raises:

Type Description
ValueError

If save to IO and method is not specified.

TypeError

If save to unsupported extension.

Alias:

  • save

Examples:

Python Console Session
>>> obj = {"a": 1, "b": 2, "c": 3}
>>> save(obj, "test.yaml")
>>> save(obj, "test.json")
>>> save(obj, "test.conf")
Traceback (most recent call last):
TypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.
>>> with open("test.yaml", "w") as f:
...     save(obj, f)
Traceback (most recent call last):
ValueError: `method` must be specified when saving to IO.
Source code in chanfig/functional.py
Python
def save(  # pylint: disable=W1113
    obj, file: File, method: str = None, *args: Any, **kwargs: Any  # type: ignore[assignment]
) -> None:
    r"""
    Save `FlatDict` to file.

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

    **Alias**:

    + `save`

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

    if isinstance(obj, FlatDict):
        obj.save(file, method, *args, **kwargs)
        return

    data = to_dict(obj)
    if method is None:
        if isinstance(file, IOBase):
            raise ValueError("`method` must be specified when saving to IO.")
        method = splitext(file)[-1][1:]
    extension = method.lower()
    if extension in YAML:
        with FlatDict.open(file, mode="w") as fp:  # pylint: disable=C0103
            yaml_dump(data, fp, *args, **kwargs)
        return
    if extension in JSON:
        with FlatDict.open(file, mode="w") as fp:  # pylint: disable=C0103
            fp.write(json_dumps(data, *args, **kwargs))
        return
    raise TypeError(f"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.")

options: heading_level: 0

Load a file into a FlatDict.

This function simply calls cls.load, by default, cls is NestedDict.

Parameters:

Name Type Description Default
file PathStr

The file to load.

required
cls type[FlatDict]

The class of the file to load. Defaults to NestedDict.

NestedDict
*args Any

The arguments to pass to NestedDict.load.

()
**kwargs Any

The keyword arguments to pass to NestedDict.load.

{}
See Also

load

Examples:

Python Console Session
>>> from chanfig import load
>>> config = load("tests/test.yaml")
>>> config
NestedDict(
  ('a'): 1
  ('b'): 2
  ('c'): 3
)
Source code in chanfig/functional.py
Python
def load(  # pylint: disable=W1113
    file: PathStr, cls: type[FlatDict] = NestedDict, *args: Any, **kwargs: Any
) -> FlatDict:
    r"""
    Load a file into a `FlatDict`.

    This function simply calls `cls.load`, by default, `cls` is `NestedDict`.

    Args:
        file: The file to load.
        cls: The class of the file to load. Defaults to `NestedDict`.
        *args: The arguments to pass to `NestedDict.load`.
        **kwargs: The keyword arguments to pass to `NestedDict.load`.

    See Also:
        [`load`][chanfig.FlatDict.load]

    Examples:
        >>> from chanfig import load
        >>> config = load("tests/test.yaml")
        >>> config
        NestedDict(
          ('a'): 1
          ('b'): 2
          ('c'): 3
        )
    """

    return cls.load(file, *args, **kwargs)

options: heading_level: 0

Apply func to all children of obj.

Note that this method is meant for non-in-place modification of obj and should return the original object.

Parameters:

Name Type Description Default
obj Any

Object to apply function.

required
func Callable

Function to be applied.

required
*args Any

Positional arguments to be passed to func.

()
**kwargs Any

Keyword arguments to be passed to func.

{}

Returns:

Type Description
Any

Return value of func.

See Also

apply_: Apply an in-place operation.

Source code in chanfig/nested_dict.py
Python
def apply(obj: Any, func: Callable, *args: Any, **kwargs: Any) -> Any:
    r"""
    Apply `func` to all children of `obj`.

    Note that this method is meant for non-in-place modification of `obj` and should return the original object.

    Args:
        obj: Object to apply function.
        func: Function to be applied.
        *args: Positional arguments to be passed to `func`.
        **kwargs: Keyword arguments to be passed to `func`.

    Returns:
        (Any): Return value of `func`.

    See Also:
        [`apply_`][chanfig.nested_dict.apply_]: Apply an in-place operation.
    """

    if isinstance(obj, NestedDict):
        return obj.empty_like(**{k: apply(v, func, *args, **kwargs) for k, v in obj.items()})
    if isinstance(obj, Mapping):
        return {k: apply(v, func, *args, **kwargs) for k, v in obj.items()}
    if isinstance(obj, list):
        return [apply(v, func, *args, **kwargs) for v in obj]
    if isinstance(obj, tuple):
        return tuple(apply(v, func, *args, **kwargs) for v in obj)
    if isinstance(obj, set):
        try:
            return {apply(v, func, *args, **kwargs) for v in obj}
        except TypeError:
            tuple(apply(v, func, *args, **kwargs) for v in obj)
    return func(*args, **kwargs) if ismethod(func) else func(obj, *args, **kwargs)

options: heading_level: 0

Apply func to all children of obj.

Note that this method is meant for non-in-place modification of obj and should return a new object.

Parameters:

Name Type Description Default
obj Any

Object to apply function.

required
func Callable

Function to be applied.

required
*args Any

Positional arguments to be passed to func.

()
**kwargs Any

Keyword arguments to be passed to func.

{}

Returns:

Type Description
Any

Return value of func.

See Also

apply_: Apply a non-in-place operation.

Source code in chanfig/nested_dict.py
Python
def apply_(obj: Any, func: Callable, *args: Any, **kwargs: Any) -> Any:
    r"""
    Apply `func` to all children of `obj`.

    Note that this method is meant for non-in-place modification of `obj` and should return a new object.

    Args:
        obj: Object to apply function.
        func: Function to be applied.
        *args: Positional arguments to be passed to `func`.
        **kwargs: Keyword arguments to be passed to `func`.

    Returns:
        (Any): Return value of `func`.

    See Also:
        [`apply_`][chanfig.nested_dict.apply]: Apply a non-in-place operation.
    """
    # pylint: disable=C0103

    if isinstance(obj, Mapping):
        for v in obj.values():
            apply_(v, func, *args, **kwargs)
    if isinstance(obj, (list, tuple, set)):
        for v in obj:
            apply_(v, func, *args, **kwargs)
    return func(*args, **kwargs) if ismethod(func) else func(obj, *args, **kwargs)

options: heading_level: 0