confingy.utils.types

types

TrackedInstance

Bases: Protocol

Protocol for objects decorated with @track.

_tracked_info is private. Use get_init_args to read the recorded constructor arguments, and update or map_fingy to change them.

Source code in src/confingy/utils/types.py

class TrackedInstance(Protocol):
    """Protocol for objects decorated with @track.

    `_tracked_info` is private. Use
    [get_init_args][confingy.tree.get_init_args] to read the recorded constructor
    arguments, and [update][confingy.tracking.update] or
    [map_fingy][confingy.tree.map_fingy] to change them.
    """

    _tracked_info: dict[str, Any]

is_lazy_type

is_lazy_type(obj: Any) -> bool

Check if an object is a Lazy type annotation.

Source code in src/confingy/utils/types.py

def is_lazy_type(obj: Any) -> bool:
    """Check if an object is a [Lazy][confingy.tracking.Lazy] type annotation."""
    # Import at runtime to avoid circular dependency
    from confingy.tracking import Lazy

    # Check if it's a GenericAlias with Lazy as the origin
    origin = get_origin(obj)
    return origin is Lazy

is_lazy_instance

is_lazy_instance(obj: Any) -> TypeGuard[Lazy[Any]]

Check if an object is a Lazy instance.

Source code in src/confingy/utils/types.py

def is_lazy_instance(obj: Any) -> TypeGuard["Lazy[Any]"]:
    """
    Check if an object is a [Lazy][confingy.tracking.Lazy] instance.
    """
    return hasattr(obj, "_confingy_lazy_info") and hasattr(obj, "instantiate")

is_tracked_instance

is_tracked_instance(obj: Any) -> TypeGuard[TrackedInstance]

Check if an object is a tracked instance (decorated with @track).

Tracked instances have a _tracked_info attribute that stores the class name, module, and constructor arguments used to create them.

Source code in src/confingy/utils/types.py

def is_tracked_instance(obj: Any) -> TypeGuard[TrackedInstance]:
    """
    Check if an object is a tracked instance (decorated with @track).

    Tracked instances have a `_tracked_info` attribute that stores
    the class name, module, and constructor arguments used to create them.
    """
    return hasattr(obj, "_tracked_info")

is_lazy_version_of

is_lazy_version_of(obj: Any, expected_type: type) -> bool

Check if an object is a Lazy version of a given type.

This compares classes by exact equality, so it does not match Lazies built from track(expected_type), which creates a new subclass on every call. Use is_fingy_of to match tracked and lazy objects of a class or its subclasses.

Source code in src/confingy/utils/types.py

def is_lazy_version_of(obj: Any, expected_type: type) -> bool:
    """Check if an object is a [Lazy][confingy.tracking.Lazy] version of a given type.

    This compares classes by exact equality, so it does not match Lazies built
    from `track(expected_type)`, which creates a new subclass on every call. Use
    [is_fingy_of][confingy.tree.is_fingy_of] to match tracked and lazy objects of
    a class or its subclasses.
    """
    return is_lazy_instance(obj) and obj._confingy_cls == expected_type

is_nonlazy_subclass_of

is_nonlazy_subclass_of(
    obj: Any, expected_supertype: type
) -> bool

Check if an object is a non-lazy subclass of a given type.

Parameters:

Name	Type	Description	Default
obj	Any	The object to check	required
expected_supertype	type	The expected supertype	required

Returns:

Type	Description
bool	True if obj is a subclass of expected_supertype and not lazy

Source code in src/confingy/utils/types.py

def is_nonlazy_subclass_of(obj: Any, expected_supertype: type) -> bool:
    """
    Check if an object is a non-lazy subclass of a given type.

    Args:
        obj: The object to check
        expected_supertype: The expected supertype

    Returns:
        True if obj is a subclass of expected_supertype and not lazy
    """
    # Check if it's a lazy type or instance
    if is_lazy_type(obj) or is_lazy_instance(obj):
        return False

    # Get the actual type to check against
    actual_expected_type = expected_supertype
    if hasattr(expected_supertype, "_original_cls"):
        actual_expected_type = expected_supertype._original_cls
    elif callable(expected_supertype) and not isinstance(expected_supertype, type):
        return False

    # Perform the type check
    if isinstance(obj, type):
        try:
            return issubclass(obj, actual_expected_type)
        except TypeError:
            return False
    else:
        try:
            return isinstance(obj, actual_expected_type)
        except TypeError:
            return False

is_all_lazy

is_all_lazy(obj: Any) -> bool

Check if an entire nested fingy is fully lazy.

This function recursively walks through a fingy and verifies that all tracked objects are Lazy instances (not already instantiated). This is useful to ensure a fingy can be safely mutated before instantiation.

Parameters:

Name	Type	Description	Default
obj	Any	The object to check. Can be a Lazy instance, dataclass, dict, list, or any other value.	required

Returns:

Type	Description
bool	True if all tracked objects in the structure are Lazy instances,
bool	False if any tracked object has been instantiated.

Examples:

@track
class Inner:
    def __init__(self, value: int):
        self.value = value

@track
class Outer:
    def __init__(self, inner: Inner):
        self.inner = inner

# All lazy - returns True
config = Outer.lazy(inner=Inner.lazy(value=1))
assert is_all_lazy(config)

# Contains instantiated object - returns False
config = Outer.lazy(inner=Inner(value=1))  # Inner is instantiated!
assert not is_all_lazy(config)

Source code in src/confingy/utils/types.py

def is_all_lazy(obj: Any) -> bool:
    """
    Check if an entire nested fingy is fully lazy.

    This function recursively walks through a fingy and verifies
    that all tracked objects are Lazy instances (not already instantiated).
    This is useful to ensure a fingy can be safely mutated before instantiation.

    Args:
        obj: The object to check. Can be a Lazy instance, dataclass, dict, list,
             or any other value.

    Returns:
        True if all tracked objects in the structure are Lazy instances,
        False if any tracked object has been instantiated.

    Examples:
        ```python
        @track
        class Inner:
            def __init__(self, value: int):
                self.value = value

        @track
        class Outer:
            def __init__(self, inner: Inner):
                self.inner = inner

        # All lazy - returns True
        config = Outer.lazy(inner=Inner.lazy(value=1))
        assert is_all_lazy(config)

        # Contains instantiated object - returns False
        config = Outer.lazy(inner=Inner(value=1))  # Inner is instantiated!
        assert not is_all_lazy(config)
        ```
    """
    from confingy.serde import HandlerRegistry

    handlers = HandlerRegistry.get_default_handlers()
    found_non_lazy = [False]  # Mutable for closure

    def check(value: Any) -> Any:
        """Check value and recurse into children. Returns value unchanged."""
        if found_non_lazy[0]:
            return value  # Short-circuit if we already found a non-lazy

        # Tracked instance = not lazy!
        if is_tracked_instance(value):
            found_non_lazy[0] = True
            return value

        # Lazy instance - check its config
        if is_lazy_instance(value):
            for v in value._confingy_config.values():
                check(v)
            return value

        # Use handlers to recurse into containers (dict, list, tuple, set, dataclass)
        for handler in handlers:
            if handler.can_handle(value):
                handler.map_children(value, check)
                return value

        return value

    check(obj)
    return not found_non_lazy[0]