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 | Sequence | Set	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

def to_dict(obj: Any, flatten: bool = False) -> Mapping | Sequence | Set:
    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 flatten and isinstance(obj, FlatDict):
        return {k: to_dict(v) for k, v in obj.all_items()}
    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

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

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

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

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