Utilities

chanfig.utils

NULL

NULL class.

get method in CHANfiG may accept None or Ellipse(...) as value of default. Therefore, it is mandatory to have a different default value for default.

Null is an instance of NULL and is recommended to be used as obj is Null.

Source code in chanfig/utils/null.py

class NULL(metaclass=Singleton):
    r"""
    NULL class.

    `get` method in CHANfiG may accept `None` or `Ellipse`(`...`) as value of `default`.
    Therefore, it is mandatory to have a different default value for `default`.

    `Null` is an instance of `NULL` and is recommended to be used as `obj is Null`.
    """

    def __repr__(self):
        return "Null"

    def __nonzero__(self):
        return False

    def __len__(self):
        return 0

    def __call__(self, *args: Any, **kwargs: Any):
        return self

    def __contains__(self, name):
        return False

    def __iter__(self):
        return self

    def __next__(self):
        raise StopIteration

    def __getattr__(self, name):
        return self

    def __getitem__(self, index):
        return self

SafeEvalError

Bases: Exception

Raised when an expression cannot be safely evaluated.

Source code in chanfig/utils/safe_eval.py

class SafeEvalError(Exception):
    """Raised when an expression cannot be safely evaluated."""

conform_annotation

Python

conform_annotation(data: Any, annotation: type) -> bool

Check if data is valid according to the expected type.

This function handles complex type annotations including: - Basic types (int, str, etc.) - Container types (List, Dict, etc.) - Union types (including Optional) - Nested generic types

Source code in chanfig/utils/annotation.py

def conform_annotation(data: Any, annotation: type) -> bool:
    r"""
    Check if data is valid according to the expected type.

    This function handles complex type annotations including:
    - Basic types (int, str, etc.)
    - Container types (List, Dict, etc.)
    - Union types (including Optional)
    - Nested generic types
    """
    if annotation is Any:
        return True
    if annotation is type(None):
        return data is None
    origin_type = get_origin(annotation)
    arg_types = get_args(annotation)
    if origin_type is Literal:
        return any(data.__class__ is literal.__class__ and data == literal for literal in arg_types)
    if origin_type in (Union, UnionType):
        return any(conform_annotation(data, arg_type) for arg_type in arg_types)
    if origin_type is Callable:
        return callable(data)
    if origin_type is not None and arg_types:
        if not isinstance(data, origin_type):
            return False
        if not data:
            return True
        if origin_type is tuple and len(arg_types) > 1 and arg_types[-1] is not Ellipsis:
            if len(data) != len(arg_types):
                return False
            return all(conform_annotation(item, type_) for item, type_ in zip(data, arg_types))
        if issubclass(origin_type, Sequence) and not isinstance(data, str):
            item_type = arg_types[0]
            return all(conform_annotation(item, item_type) for item in data)
        if issubclass(origin_type, Mapping):
            key_type, value_type = arg_types[:2]
            return all(conform_annotation(k, key_type) and conform_annotation(v, value_type) for k, v in data.items())
        if issubclass(origin_type, (set, frozenset)):
            item_type = arg_types[0]
            return all(conform_annotation(item, item_type) for item in data)
        return isinstance(data, origin_type)
    try:
        return isinstance(data, annotation)
    except TypeError:
        return False

get_annotations

Python

get_annotations(
    obj,
    *,
    globalns: Mapping | None = None,
    localns: Mapping | None = None,
    eval_str: bool = True
) -> Mapping

Compute the annotations dict for an object.

obj may be a callable, class, or module. Passing in an object of any other type raises TypeError.

Returns a dict. get_annotations() returns a new dict every time it’s called; calling it twice on the same object will return two different but equivalent dicts.

This function handles several details for you:

• If eval_str is true, values of type str will be un-stringized using eval(). This is intended for use with stringized annotations (from __future__ import annotations).
• globalns fall back to public member of typing.
• If obj doesn’t have an annotations dict, returns an empty dict. (Functions and methods always have an annotations dict; classes, modules, and other types of callables may not.)
• Ignores inherited annotations on classes. If a class doesn’t have its own annotations dict, returns an empty dict.
• All accesses to object members and dict values are done using getattr() and dict.get() for safety.
• Always, always, always returns a freshly-created dict.

eval_str controls whether or not values of type str are replaced with the result of calling eval() on those values:

• If eval_str is true, eval() is called on values of type str.
• If eval_str is false (the default), values of type str are unchanged.

globalns and localns are passed in to eval(); see the documentation for eval() for more information.

globalns fall back to public member of typing.

If either globalns or localns is None, this function may replace that value with a context-specific default, contingent on type(obj):

• If obj is a module, globalns defaults to obj.__dict__.
• If obj is a class, globalns defaults to sys.modules[obj.__module__].__dict__ and localns defaults to the obj class namespace.
• If obj is a callable, globalns defaults to obj.__globals__, although if obj is a wrapped function (using functools.update_wrapper()) it is first unwrapped.
• If obj is an instance, globalns defaults to sys.modules[obj.__module__].__dict__ and localns defaults to the obj class namespace.

Source code in chanfig/utils/annotation.py

@no_type_check
def get_annotations(  # pylint: disable=all
    obj, *, globalns: Mapping | None = None, localns: Mapping | None = None, eval_str: bool = True
) -> Mapping:
    r"""
    Compute the annotations dict for an object.

    obj may be a callable, class, or module.
    Passing in an object of any other type raises TypeError.

    Returns a dict.  get_annotations() returns a new dict every time
    it's called; calling it twice on the same object will return two
    different but equivalent dicts.

    This function handles several details for you:

      * If `eval_str` is true, values of type str will
        be un-stringized using `eval()`.  This is intended
        for use with stringized annotations
        (`from __future__ import annotations`).
      * `globalns` fall back to public member of `typing`.
      * If obj doesn't have an annotations dict, returns an
        empty dict.  (Functions and methods always have an
        annotations dict; classes, modules, and other types of
        callables may not.)
      * Ignores inherited annotations on classes.  If a class
        doesn't have its own annotations dict, returns an empty dict.
      * All accesses to object members and dict values are done
        using `getattr()` and `dict.get()` for safety.
      * Always, always, always returns a freshly-created dict.

    `eval_str` controls whether or not values of type str are replaced
    with the result of calling eval() on those values:

      * If `eval_str` is true, eval() is called on values of type str.
      * If `eval_str` is false (the default), values of type str are unchanged.

    `globalns` and `localns` are passed in to `eval()`; see the documentation
    for `eval()` for more information.

    `globalns` fall back to public member of `typing`.

    If either `globalns` or `localns` is
    None, this function may replace that value with a context-specific
    default, contingent on `type(obj)`:

      * If `obj` is a module, globalns defaults to `obj.__dict__`.
      * If `obj` is a class, globalns defaults to
        `sys.modules[obj.__module__].__dict__` and `localns`
        defaults to the obj class namespace.
      * If `obj` is a callable, `globalns` defaults to `obj.__globals__`,
        although if obj is a wrapped function (using
        functools.update_wrapper()) it is first unwrapped.
      * If `obj` is an instance, `globalns` defaults to
        `sys.modules[obj.__module__].__dict__` and localns
        defaults to the obj class namespace.
    """
    if isinstance(obj, type):
        # class
        annos = getattr(obj, "__annotations__", None)
        obj_globalns = None
        module_name = getattr(obj, "__module__", None)
        if module_name:
            module = sys.modules.get(module_name, None)
            if module:
                obj_globalns = getattr(module, "__dict__", None)
        obj_localns = dict(vars(obj))
        unwrap = obj
    elif isinstance(obj, ModuleType):
        # module
        annos = getattr(obj, "__annotations__", None)
        obj_globalns = getattr(obj, "__dict__")
        obj_localns = None
        unwrap = None
    elif callable(obj):
        # this includes types.Function, types.BuiltinFunctionType,
        # types.BuiltinMethodType, functools.partial, functools.singledispatch,
        # "class funclike" from Lib/test/test_inspect... on and on it goes.
        annos = getattr(obj, "__annotations__", None)
        obj_globalns = getattr(obj, "__globals__", None)
        obj_localns = None
        unwrap = obj
    else:
        # obj
        annos = getattr(type(obj), "__annotations__", None)
        obj_globalns = None
        module_name = getattr(obj, "__module__", None)
        if module_name:
            module = sys.modules.get(module_name, None)
            if module:
                obj_globalns = getattr(module, "__dict__", None)
        obj_localns = dict(vars(obj))
        unwrap = obj

    if annos is None or not annos:
        return {}

    if not isinstance(annos, dict):
        raise ValueError(f"{obj!r}.__annotations__ is neither a dict nor None")

    if unwrap is not None:
        while True:
            if hasattr(unwrap, "__wrapped__"):
                unwrap = unwrap.__wrapped__
                continue
            if isinstance(unwrap, partial):
                unwrap = unwrap.func
                continue
            break
        if hasattr(unwrap, "__globals__"):
            obj_globalns = unwrap.__globals__ or {}

    # globalns = GLOBAL_NS | globalns if globalns is not None else obj_globalns
    if globalns is None:
        globalns = obj_globalns
    if globalns is None:
        globalns = {}
    globalns = {**GLOBAL_NS, **dict(globalns)}
    if localns is None:
        localns = obj_localns

    ret = {}
    for key, value in annos.items():
        if eval_str and isinstance(value, str):
            try:
                value = eval(value, globalns, localns)  # pylint: disable=W0123
            except NameError:
                raise ValueError(
                    f"Type annotation '{key}: {value}' in {obj!r} is invalid.\n"
                    "If you are running on an earlier version of Python, "
                    "please ensure annotations does not contain forward references."
                ) from None
            except TypeError:
                raise ValueError(
                    f"Type annotation '{key}: {value}' in {obj!r} is invalid.\n"
                    "If you are running on an earlier version of Python, "
                    "please ensure you are not using future features such as PEP604."
                ) from None
        ret[key] = value
    return ret

get_cached_annotations

Python

get_cached_annotations(obj, copy: bool = True) -> Mapping

Lightweight cached wrapper around get_annotations keyed by class.

By default, the returned mapping is copied to preserve the original get_annotations contract of producing a fresh dict for each call. Internal callers may set copy=False to retrieve a read-only cached mapping and avoid per-call dict allocations in hot paths.

Source code in chanfig/utils/annotation.py

def get_cached_annotations(obj, copy: bool = True) -> Mapping:
    """
    Lightweight cached wrapper around `get_annotations` keyed by class.

    By default, the returned mapping is copied to preserve the original
    `get_annotations` contract of producing a fresh dict for each call.
    Internal callers may set `copy=False` to retrieve a read-only cached mapping
    and avoid per-call dict allocations in hot paths.
    """

    try:
        cls = obj if isinstance(obj, type) else obj.__class__
    except Exception:
        annotations = get_annotations(obj)
        return dict(annotations) if copy else annotations
    try:
        cached = _cached_annotations_for_class(cls)
    except TypeError:
        annotations = get_annotations(obj)
        return dict(annotations) if copy else annotations
    if copy:
        return dict(cached)
    return cached

honor_annotation

Python

honor_annotation(data: Any, annotation: type) -> Any

Attempt to convert data to match the expected type annotation.

This function tries to honor the type annotation by converting the data when possible, rather than rejecting it. It works with: - Basic types (int, str, etc.) - Container types (List, Dict, etc.) - Union types (including Optional) - Nested generic types

Unlike conform_annotation which validates type compatibility, this function tries to adapt the data to match the annotation.

Examples:

>>> honor_annotation("42", int)
42
>>> honor_annotation(42, str)
'42'
>>> honor_annotation("name", Union[int, str])
'name'
>>> honor_annotation(123, Union[int, str])
123

Source code in chanfig/utils/annotation.py

def honor_annotation(data: Any, annotation: type) -> Any:
    r"""
    Attempt to convert data to match the expected type annotation.

    This function tries to honor the type annotation by converting the data
    when possible, rather than rejecting it. It works with:
    - Basic types (int, str, etc.)
    - Container types (List, Dict, etc.)
    - Union types (including Optional)
    - Nested generic types

    Unlike `conform_annotation` which validates type compatibility,
    this function tries to adapt the data to match the annotation.

    Examples:
        >>> honor_annotation("42", int)
        42
        >>> honor_annotation(42, str)
        '42'
        >>> honor_annotation("name", Union[int, str])
        'name'
        >>> honor_annotation(123, Union[int, str])
        123
    """
    if data is None or annotation is Any:
        return data
    origin_type = get_origin(annotation)
    arg_types = get_args(annotation)
    with suppress(Exception):
        if origin_type is Literal:
            if conform_annotation(data, annotation):
                return data
            for literal in arg_types:
                if literal.__class__ is bool:
                    continue
                with suppress(ValueError, TypeError):
                    converted = literal.__class__(data)
                    if converted.__class__ is literal.__class__ and converted == literal:
                        return literal
            return data
        if origin_type is Union or origin_type is UnionType:
            if any(conform_annotation(data, t) for t in arg_types):
                return data
            for t in arg_types:
                if t is not type(None):
                    with suppress(ValueError, TypeError):
                        return t(data)
            return data
        if origin_type is not None and arg_types:
            if issubclass(origin_type, tuple) and len(arg_types) == len(data):
                return origin_type(honor_annotation(item, arg) for item, arg in zip(data, arg_types))
            if isinstance(data, origin_type):
                if not data:
                    return data
                if origin_type is tuple and len(arg_types) > 1 and arg_types[-1] is not Ellipsis:
                    if len(data) == len(arg_types):
                        return tuple(honor_annotation(item, arg) for item, arg in zip(data, arg_types))
                    return data
                if issubclass(origin_type, Sequence) and not isinstance(data, str):
                    item_type = arg_types[0]
                    item_origin = get_origin(item_type)
                    item_args = get_args(item_type)
                    if item_origin is not None and item_args:
                        return origin_type([honor_annotation(item, item_type) for item in data])
                    return origin_type(honor_annotation(item, item_type) for item in data)
                if issubclass(origin_type, Mapping):
                    key_type, value_type = arg_types[:2]
                    return origin_type(
                        {honor_annotation(k, key_type): honor_annotation(v, value_type) for k, v in data.items()}
                    )
                if issubclass(origin_type, (set, frozenset)):
                    item_type = arg_types[0]
                    return origin_type(honor_annotation(item, item_type) for item in data)
            else:
                with suppress(ValueError, TypeError):
                    converted = origin_type(data)
                    return honor_annotation(converted, annotation)
            return data
        if isinstance(annotation, type) and not isinstance(data, annotation):
            with suppress(ValueError, TypeError):
                return annotation(data)
            return data
    return data

apply

Python

apply(
    obj: Any, func: Callable, *args: Any, **kwargs: Any
) -> Any

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.	{}

See Also

[apply_][chanfig.utils.apply.apply_]: Apply an in-place operation.

Source code in chanfig/utils/functional.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`.

    See Also:
        [`apply_`][chanfig.utils.apply.apply_]: Apply an in-place operation.
    """
    # Handle circular import
    from ..nested_dict import NestedDict

    is_method = ismethod(func)

    def _invoke(target):
        return func(*args, **kwargs) if is_method else func(target, *args, **kwargs)

    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:
            return tuple(apply(v, func, *args, **kwargs) for v in obj)
    return _invoke(obj)

apply_

Python

apply_(
    obj: Any, func: Callable, *args: Any, **kwargs: Any
) -> Any

Apply func to all children of obj.

Note that this method is meant for in-place modification of obj and should return the modified 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.	{}

See Also

[apply][chanfig.utils.apply.apply]: Apply a non-in-place operation.

Source code in chanfig/utils/functional.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 in-place modification of `obj` and should return the modified 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`.

    See Also:
        [`apply`][chanfig.utils.apply.apply]: Apply a non-in-place operation.
    """
    # pylint: disable=C0103
    is_method = ismethod(func)

    def _invoke(target):
        return func(*args, **kwargs) if is_method else func(target, *args, **kwargs)

    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 _invoke(obj)

parse_bool

Python

parse_bool(value: bool | str | int) -> bool

Convert various types of values to boolean.

This function converts different input types (bool, str, int) to their boolean equivalent.

Examples:

>>> parse_bool(True)
True
>>> parse_bool("yes")
True
>>> parse_bool(1)
True
>>> parse_bool(0)
False
>>> parse_bool("false")
False

Source code in chanfig/utils/functional.py

def parse_bool(value: bool | str | int) -> bool:
    r"""
    Convert various types of values to boolean.

    This function converts different input types (bool, str, int) to their boolean equivalent.

    Examples:
        >>> parse_bool(True)
        True
        >>> parse_bool("yes")
        True
        >>> parse_bool(1)
        True
        >>> parse_bool(0)
        False
        >>> parse_bool("false")
        False
    """
    if isinstance(value, bool):
        return value
    if isinstance(value, int):
        if value == 1:
            return True
        if value == 0:
            return False
        raise ValueError(f"Only 0 or 1 is allowed for boolean value, but got {value}.")
    if isinstance(value, str):
        if value.lower() in ("yes", "true", "t", "y", "1"):
            return True
        if value.lower() in ("no", "false", "f", "n", "0"):
            return False
    raise ValueError(f"Boolean value is expected, but got {value}.")

suggest_key

Python

suggest_key(
    name: Any,
    candidates: Iterable[Any],
    cutoff: float = 0.75,
) -> str | None

Suggest the closest key from candidates to name.

Parameters:

Name	Type	Description	Default
name	Any	The queried name.	required
candidates	Iterable[Any]	An iterable of candidate names.	required
cutoff	float	Similarity threshold passed to :func:difflib.get_close_matches.	0.75

Source code in chanfig/utils/functional.py

def suggest_key(name: Any, candidates: Iterable[Any], cutoff: float = 0.75) -> str | None:
    r"""
    Suggest the closest key from `candidates` to `name`.

    Args:
        name: The queried name.
        candidates: An iterable of candidate names.
        cutoff: Similarity threshold passed to :func:`difflib.get_close_matches`.
    """

    try:
        target = str(name)
    except Exception:
        return None
    try:
        strings = [str(candidate) for candidate in candidates]
    except Exception:
        return None
    matches = get_close_matches(target, strings, n=1, cutoff=cutoff)
    return matches[0] if matches else None

to_chanfig

Python

to_chanfig(obj: Any, cls: type | None = None) -> Any

Convert arbitrary data structure to CHANfiG objects when possible.

This function recursively converts mappings to FlatDict instances and handles nested structures of arbitrary depth.

Parameters:

Name	Type	Description	Default
obj	Any	Object to be converted.	required
cls	type | None	Class to use for creating FlatDict instances. Defaults to FlatDict.	None

Examples:

>>> to_chanfig({'a': 1, 'b': 2})
FlatDict(
  ('a'): 1
  ('b'): 2
)
>>> to_chanfig([1, 2, 3])
[1, 2, 3]
>>> to_chanfig([{'a': 1}, {'b': 2}])
[FlatDict(('a'): 1), FlatDict(('b'): 2)]
>>> to_chanfig([[1, 2], [3, 4]])
FlatDict(
  (1): 2
  (3): 4
)
>>> to_chanfig([[1, 2, 3], [4, 5, 6]])
[[1, 2, 3], [4, 5, 6]]

Source code in chanfig/utils/functional.py

def to_chanfig(obj: Any, cls: type | None = None) -> Any:
    r"""
    Convert arbitrary data structure to CHANfiG objects when possible.

    This function recursively converts mappings to FlatDict instances
    and handles nested structures of arbitrary depth.

    Args:
        obj: Object to be converted.
        cls: Class to use for creating FlatDict instances. Defaults to `FlatDict`.

    Examples:
        >>> to_chanfig({'a': 1, 'b': 2})
        FlatDict(
          ('a'): 1
          ('b'): 2
        )
        >>> to_chanfig([1, 2, 3])
        [1, 2, 3]
        >>> to_chanfig([{'a': 1}, {'b': 2}])
        [FlatDict(('a'): 1), FlatDict(('b'): 2)]
        >>> to_chanfig([[1, 2], [3, 4]])
        FlatDict(
          (1): 2
          (3): 4
        )
        >>> to_chanfig([[1, 2, 3], [4, 5, 6]])
        [[1, 2, 3], [4, 5, 6]]
    """
    # Handle circular import
    from ..flat_dict import FlatDict

    if cls is None:
        cls = FlatDict

    if isinstance(obj, Mapping):
        result = cls()
        for k, v in obj.items():
            result[k] = to_chanfig(v, cls)
        return result
    if isinstance(obj, (list, tuple)) and all(isinstance(item, (list, tuple)) and len(item) == 2 for item in obj):
        try:
            result = cls()
            for k, v in obj:
                result[k] = to_chanfig(v, cls)
            return result
        except (ValueError, TypeError):
            pass
    if isinstance(obj, (list, tuple)):
        return type(obj)(to_chanfig(item, cls) for item in obj)
    if isinstance(obj, set):
        try:
            return {to_chanfig(item, cls) for item in obj}
        except TypeError:
            return tuple(to_chanfig(item, cls) for item in obj)
    return obj

to_dict

Python

to_dict(
    obj: Any, flatten: bool = False
) -> Mapping | Sequence | Set

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
flatten	bool	Whether to flatten nested structures.	False

Examples:

>>> from chanfig import FlatDict, Variable

>>> 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/utils/functional.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.
        flatten: Whether to flatten nested structures.

    Examples:
        >>> from chanfig import FlatDict, Variable

        >>> 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},)}
    """
    # Handle circular import
    from ..flat_dict import FlatDict
    from ..variable import Variable

    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.placeholder if obj.placeholder is not None else obj.value
    if is_dataclass(obj):
        return asdict(obj)  # type: ignore[arg-type]
    if hasattr(obj, "to_dict"):
        return obj.to_dict()
    return obj

find_circular_reference

Python

find_circular_reference(graph: Mapping) -> list[str] | None

Find circular references in a dependency graph.

This function performs a depth-first search to detect any circular references in a graph represented as a mapping of nodes to their dependencies.

Source code in chanfig/utils/placeholder.py

def find_circular_reference(graph: Mapping) -> list[str] | None:
    r"""
    Find circular references in a dependency graph.

    This function performs a depth-first search to detect any circular references
    in a graph represented as a mapping of nodes to their dependencies.
    """

    visited: set[Any] = set()
    path: list[Any] = []
    path_indices: dict[Any, int] = {}

    def dfs(node):
        if node in path_indices:
            cycle_start = path_indices[node]
            return path[cycle_start:] + [node]
        if node in visited:
            return None

        path_indices[node] = len(path)
        path.append(node)

        for child in graph.get(node, []):
            result = dfs(child)
            if result is not None:
                return result

        path.pop()
        path_indices.pop(node, None)
        visited.add(node)
        return None

    for key in graph:
        if key in visited:
            continue
        result = dfs(key)
        if result is not None:
            return result

    return None

find_placeholders

Python

find_placeholders(text: str) -> list[str]

Find all placeholders in text, including nested ones.

This function searches for placeholders in the format ${name} and returns a list of all placeholder names found, including those that are nested within other placeholders.

Examples:

>>> find_placeholders("Hello ${name}")
['name']
>>> find_placeholders("Hello ${user.${type}}")
['user.${type}', 'type']
>>> find_placeholders("${outer${inner}}")
['outer${inner}', 'inner']

Source code in chanfig/utils/placeholder.py

def find_placeholders(text: str) -> list[str]:
    r"""Find all placeholders in text, including nested ones.

    This function searches for placeholders in the format ${name} and returns a list
    of all placeholder names found, including those that are nested within other placeholders.

    Examples:
        >>> find_placeholders("Hello ${name}")
        ['name']
        >>> find_placeholders("Hello ${user.${type}}")
        ['user.${type}', 'type']
        >>> find_placeholders("${outer${inner}}")
        ['outer${inner}', 'inner']
    """
    if not isinstance(text, str):
        return []

    results = []
    stack = []
    i = 0

    while i < len(text):
        if text[i : i + 2] == "${":  # noqa: E203
            stack.append(i)
            i += 2
        elif text[i] == "}" and stack:
            start = stack.pop()
            placeholder = text[start + 2 : i]  # noqa: E203
            if not stack:
                results.append(placeholder)
            i += 1
        else:
            i += 1

    nested_results = []
    for placeholder in results:
        nested_results.extend(find_placeholders(placeholder))

    return results + nested_results

safe_eval_expr

Python

safe_eval_expr(
    expression: str, context: Mapping[str, Any]
) -> Any

Safely evaluate a limited arithmetic expression against a context of names.

Supported

• Literals (ints, floats, strings)
• Names (looked up in context)
• Unary ± on numbers
• Binary ops: +, -, *, /, //, %, **
• Parentheses (handled by the AST parser)

Anything else raises SafeEvalError.

Source code in chanfig/utils/safe_eval.py

def safe_eval_expr(expression: str, context: Mapping[str, Any]) -> Any:
    """
    Safely evaluate a limited arithmetic expression against a context of names.

    Supported:
        - Literals (ints, floats, strings)
        - Names (looked up in `context`)
        - Unary +/- on numbers
        - Binary ops: +, -, *, /, //, %, **
        - Parentheses (handled by the AST parser)

    Anything else raises SafeEvalError.
    """

    try:
        tree = ast.parse(expression, mode="eval")
    except SyntaxError as exc:  # pragma: no cover - defensive
        raise SafeEvalError(f"Invalid expression: {expression!r}") from exc

    def _eval(node):
        if isinstance(node, ast.Expression):
            return _eval(node.body)
        if isinstance(node, ast.Constant):
            return node.value
        if isinstance(node, ast.Name):
            if node.id not in context:
                raise SafeEvalError(f"Unknown name: {node.id}")
            return context[node.id]
        if isinstance(node, ast.UnaryOp) and type(node.op) in _ALLOWED_UNARY_OPS:
            operand = _eval(node.operand)
            return _ALLOWED_UNARY_OPS[type(node.op)](operand)
        if isinstance(node, ast.BinOp) and type(node.op) in _ALLOWED_BIN_OPS:
            left = _eval(node.left)
            right = _eval(node.right)
            return _ALLOWED_BIN_OPS[type(node.op)](left, right)
        raise SafeEvalError(f"Unsupported expression: {expression!r}")

    return _eval(tree)