lionagi 0.16.1__py3-none-any.whl → 0.16.3__py3-none-any.whl

lionagi/libs/nested/flatten.py

@@ -1,172 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from collections import deque
-from collections.abc import Mapping, Sequence
-from typing import Any, Literal, TypeVar, overload
-
-T = TypeVar("T")
-
-
-@overload
-def flatten(
-    nested_structure: T,
-    /,
-    *,
-    parent_key: tuple = (),
-    sep: str = "|",
-    coerce_keys: Literal[True] = True,
-    dynamic: bool = True,
-    coerce_sequence: Literal["dict", None] = None,
-    max_depth: int | None = None,
-) -> dict[str, Any] | None: ...
-
-
-@overload
-def flatten(
-    nested_structure: T,
-    /,
-    *,
-    parent_key: tuple = (),
-    sep: str = "|",
-    coerce_keys: Literal[False],
-    dynamic: bool = True,
-    coerce_sequence: Literal["dict", "list", None] = None,
-    max_depth: int | None = None,
-) -> dict[tuple, Any] | None: ...
-
-
-def flatten(
-    nested_structure: Any,
-    /,
-    *,
-    parent_key: tuple = (),
-    sep: str = "|",
-    coerce_keys: bool = True,
-    dynamic: bool = True,
-    coerce_sequence: Literal["dict", "list"] | None = None,
-    max_depth: int | None = None,
-) -> dict[tuple | str, Any] | None:
-    """Flatten a nested structure into a single-level dictionary.
-
-    Recursively traverses the input, creating keys that represent the path
-    to each value in the flattened result.
-
-    Args:
-        nested_structure: The nested structure to flatten.
-        parent_key: Base key for the current recursion level. Default: ().
-        sep: Separator for joining keys. Default: "|".
-        coerce_keys: Join keys into strings if True, keep as tuples if False.
-            Default: True.
-        dynamic: Handle sequences (except strings) dynamically if True.
-            Default: True.
-        coerce_sequence: Force sequences to be treated as dicts or lists.
-            Options: "dict", "list", or None. Default: None.
-        max_depth: Maximum depth to flatten. None for complete flattening.
-            Default: None.
-
-    Returns:
-        A flattened dictionary with keys as tuples or strings (based on
-        coerce_keys) representing the path to each value.
-
-    Raises:
-        ValueError: If coerce_sequence is "list" and coerce_keys is True.
-
-    Example:
-        >>> nested = {"a": 1, "b": {"c": 2, "d": [3, 4]}}
-        >>> flatten(nested)
-        {'a': 1, 'b|c': 2, 'b|d|0': 3, 'b|d|1': 4}
-
-    Note:
-        - Preserves order of keys in dicts and indices in sequences.
-        - With dynamic=True, treats sequences (except strings) as nestable.
-        - coerce_sequence allows forcing sequence handling for homogeneity.
-    """
-
-    if coerce_keys and coerce_sequence == "list":
-        raise ValueError(
-            "coerce_sequence cannot be 'list' when coerce_keys is True"
-        )
-
-    coerce_sequence_to_list = None
-    coerce_sequence_to_dict = None
-
-    if dynamic and coerce_sequence:
-        if coerce_sequence == "dict":
-            coerce_sequence_to_dict = True
-        elif coerce_sequence == "list":
-            coerce_sequence_to_list = True
-
-    return _flatten_iterative(
-        obj=nested_structure,
-        parent_key=parent_key,
-        sep=sep,
-        coerce_keys=coerce_keys,
-        dynamic=dynamic,
-        coerce_sequence_to_list=coerce_sequence_to_list,
-        coerce_sequence_to_dict=coerce_sequence_to_dict,
-        max_depth=max_depth,
-    )
-
-
-def _flatten_iterative(
-    obj: Any,
-    parent_key: tuple,
-    sep: str,
-    coerce_keys: bool,
-    dynamic: bool,
-    coerce_sequence_to_list: bool = False,
-    coerce_sequence_to_dict: bool = False,
-    max_depth: int | None = None,
-) -> dict[tuple | str, Any]:
-    stack = deque([(obj, parent_key, 0)])
-    result = {}
-
-    while stack:
-        current_obj, current_key, depth = stack.pop()
-
-        if max_depth is not None and depth >= max_depth:
-            result[_format_key(current_key, sep, coerce_keys)] = current_obj
-            continue
-
-        if isinstance(current_obj, Mapping):
-            for k, v in current_obj.items():
-                new_key = current_key + (k,)
-                if (
-                    v
-                    and isinstance(v, (Mapping, Sequence))
-                    and not isinstance(v, (str, bytes, bytearray))
-                ):
-                    stack.appendleft((v, new_key, depth + 1))
-                else:
-                    result[_format_key(new_key, sep, coerce_keys)] = v
-
-        elif (
-            dynamic
-            and isinstance(current_obj, Sequence)
-            and not isinstance(current_obj, (str, bytes, bytearray))
-        ):
-            if coerce_sequence_to_dict:
-                dict_obj = {str(i): v for i, v in enumerate(current_obj)}
-                for k, v in dict_obj.items():
-                    new_key = current_key + (k,)
-                    stack.appendleft((v, new_key, depth + 1))
-            elif coerce_sequence_to_list:
-                for i, v in enumerate(current_obj):
-                    new_key = current_key + (i,)
-                    stack.appendleft((v, new_key, depth + 1))
-            else:
-                for i, v in enumerate(current_obj):
-                    new_key = current_key + (str(i),)
-                    stack.appendleft((v, new_key, depth + 1))
-        else:
-            result[_format_key(current_key, sep, coerce_keys)] = current_obj
-
-    return result
-
-
-def _format_key(key: tuple, sep: str, coerce_keys: bool, /) -> tuple | str:
-    if not key:
-        return key
-    return sep.join(map(str, key)) if coerce_keys else key

lionagi/libs/nested/nfilter.py

@@ -1,59 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from collections.abc import Callable
-from typing import Any
-
-
-def nfilter(
-    nested_structure: dict[Any, Any] | list[Any],
-    /,
-    condition: Callable[[Any], bool],
-) -> dict[Any, Any] | list[Any]:
-    """Filter elements in a nested structure based on a condition.
-
-    Args:
-        nested_structure: The nested structure (dict or list) to filter.
-        condition: Function returning True for elements to keep, False to
-            discard.
-
-    Returns:
-        The filtered nested structure.
-
-    Raises:
-        TypeError: If nested_structure is not a dict or list.
-
-    Example:
-        >>> data = {"a": 1, "b": {"c": 2, "d": 3}, "e": [4, 5, 6]}
-        >>> nfilter(data, lambda x: isinstance(x, int) and x > 2)
-        {'b': {'d': 3}, 'e': [4, 5, 6]}
-    """
-    if isinstance(nested_structure, dict):
-        return _filter_dict(nested_structure, condition)
-    elif isinstance(nested_structure, list):
-        return _filter_list(nested_structure, condition)
-    else:
-        raise TypeError(
-            "The nested_structure must be either a dict or a list."
-        )
-
-
-def _filter_dict(
-    dictionary: dict[Any, Any], condition: Callable[[tuple[Any, Any]], bool]
-) -> dict[Any, Any]:
-    return {
-        k: nfilter(v, condition) if isinstance(v, dict | list) else v
-        for k, v in dictionary.items()
-        if condition(v) or isinstance(v, dict | list)
-    }
-
-
-def _filter_list(
-    lst: list[Any], condition: Callable[[Any], bool]
-) -> list[Any]:
-    return [
-        nfilter(item, condition) if isinstance(item, dict | list) else item
-        for item in lst
-        if condition(item) or isinstance(item, dict | list)
-    ]

lionagi/libs/nested/nget.py

@@ -1,45 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any
-
-from lionagi.utils import UNDEFINED
-
-from .utils import get_target_container
-
-
-def nget(
-    nested_structure: dict[Any, Any] | list[Any],
-    /,
-    indices: list[int | str],
-    default: Any = UNDEFINED,
-) -> Any:
-    try:
-        target_container = get_target_container(nested_structure, indices[:-1])
-        last_index = indices[-1]
-
-        if (
-            isinstance(target_container, list)
-            and isinstance(last_index, int)
-            and last_index < len(target_container)
-        ):
-            return target_container[last_index]
-        elif (
-            isinstance(target_container, dict)
-            and last_index in target_container
-        ):
-            return target_container[last_index]
-        elif default is not UNDEFINED:
-            return default
-        else:
-            raise LookupError(
-                "Target not found and no default value provided."
-            )
-    except (IndexError, KeyError, TypeError):
-        if default is not UNDEFINED:
-            return default
-        else:
-            raise LookupError(
-                "Target not found and no default value provided."
-            )

lionagi/libs/nested/ninsert.py

@@ -1,104 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any
-
-from lionagi.utils import to_list
-
-
-def ninsert(
-    nested_structure: dict[Any, Any] | list[Any],
-    /,
-    indices: list[str | int],
-    value: Any,
-    *,
-    current_depth: int = 0,
-) -> None:
-    """
-    Inserts a value into a nested structure at a specified path.
-
-    Navigates a nested dictionary or list based on a sequence of indices or
-    keys and inserts `value` at the final location. This method can create
-    intermediate dictionaries or lists as needed.
-
-    Args:
-        nested_structure: The nested structure to modify.
-        indices: The sequence of keys or indices defining the insertion path.
-        value: The value to insert at the specified location.
-        current_depth: Internal use only; tracks the current depth during
-            recursive calls.
-
-    Raises:
-        ValueError: If the indices list is empty.
-        TypeError: If an invalid key or container type is encountered.
-
-    Examples:
-        >>> subject_ = {'a': {'b': [1, 2]}}
-        >>> ninsert(subject_, ['a', 'b', 2], 3)
-        >>> assert subject_ == {'a': {'b': [1, 2, 3]}}
-
-        >>> subject_ = []
-        >>> ninsert(subject_, [0, 'a'], 1)
-        >>> assert subject_ == [{'a': 1}]
-    """
-    if not indices:
-        raise ValueError("Indices list cannot be empty")
-
-    indices = to_list(indices)
-    for i, part in enumerate(indices[:-1]):
-        if isinstance(part, int):
-            if isinstance(nested_structure, dict):
-                raise TypeError(
-                    f"Unsupported key type: {type(part).__name__}.Only string keys are acceptable.",
-                )
-            while len(nested_structure) <= part:
-                nested_structure.append(None)
-            if nested_structure[part] is None or not isinstance(
-                nested_structure[part], (dict, list)
-            ):
-                next_part = indices[i + 1]
-                nested_structure[part] = (
-                    [] if isinstance(next_part, int) else {}
-                )
-        elif isinstance(nested_structure, dict):
-            if part is None:
-                raise TypeError("Cannot use NoneType as a key in a dictionary")
-            if isinstance(part, (float, complex)):
-                raise TypeError(
-                    f"Unsupported key type: {type(part).__name__}.Only string keys are acceptable.",
-                )
-            if part not in nested_structure:
-                next_part = indices[i + 1]
-                nested_structure[part] = (
-                    [] if isinstance(next_part, int) else {}
-                )
-        else:
-            raise TypeError(
-                f"Invalid container type: {type(nested_structure)} encountered during insertion"
-            )
-
-        nested_structure = nested_structure[part]
-        current_depth += 1
-
-    last_part = indices[-1]
-    if isinstance(last_part, int):
-        if isinstance(nested_structure, dict):
-            raise TypeError(
-                f"Unsupported key type: {type(last_part).__name__}."
-                "Only string keys are acceptable.",
-            )
-        while len(nested_structure) <= last_part:
-            nested_structure.append(None)
-        nested_structure[last_part] = value
-    elif isinstance(nested_structure, list):
-        raise TypeError("Cannot use non-integer index on a list")
-    else:
-        if last_part is None:
-            raise TypeError("Cannot use NoneType as a key in a dictionary")
-        if isinstance(last_part, (float, complex)):
-            raise TypeError(
-                f"Unsupported key type: {type(last_part).__name__}."
-                "Only string keys are acceptable.",
-            )
-        nested_structure[last_part] = value

lionagi/libs/nested/nmerge.py

@@ -1,158 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from collections import defaultdict
-from collections.abc import Callable, Sequence
-from itertools import chain
-from typing import Any
-
-from .utils import is_homogeneous
-
-
-def nmerge(
-    nested_structure: Sequence[dict[str, Any] | list[Any]],
-    /,
-    *,
-    overwrite: bool = False,
-    dict_sequence: bool = False,
-    sort_list: bool = False,
-    custom_sort: Callable[[Any], Any] | None = None,
-) -> dict[str, Any] | list[Any]:
-    """
-    Merge multiple dictionaries, lists, or sequences into a unified structure.
-
-    Args:
-        nested_structure: A sequence containing dictionaries, lists, or other
-            iterable objects to merge.
-        overwrite: If True, overwrite existing keys in dictionaries with
-            those from subsequent dictionaries.
-        dict_sequence: Enables unique key generation for duplicate keys by
-            appending a sequence number. Applicable only if `overwrite` is
-            False.
-        sort_list: When True, sort the resulting list after merging. It does
-            not affect dictionaries.
-        custom_sort: An optional callable that defines custom sorting logic
-            for the merged list.
-
-    Returns:
-        A merged dictionary or list, depending on the types present in
-        `nested_structure`.
-
-    Raises:
-        TypeError: If `nested_structure` contains objects of incompatible
-            types that cannot be merged.
-    """
-    if not isinstance(nested_structure, list):
-        raise TypeError("Please input a list")
-    if is_homogeneous(nested_structure, dict):
-        return _merge_dicts(nested_structure, overwrite, dict_sequence)
-    elif is_homogeneous(nested_structure, list):
-        return _merge_sequences(nested_structure, sort_list, custom_sort)
-    else:
-        raise TypeError(
-            "All items in the input list must be of the same type, either dict, list, or Iterable."
-        )
-
-
-def _deep_merge_dicts(
-    dict1: dict[str, Any], dict2: dict[str, Any]
-) -> dict[str, Any]:
-    """
-    Recursively merges two dictionaries, combining values where keys overlap.
-
-    Args:
-        dict1: The first dictionary.
-        dict2: The second dictionary.
-
-    Returns:
-        The merged dictionary.
-    """
-    for key in dict2:
-        if key in dict1:
-            if isinstance(dict1[key], dict) and isinstance(dict2[key], dict):
-                _deep_merge_dicts(dict1[key], dict2[key])
-            else:
-                if not isinstance(dict1[key], list):
-                    dict1[key] = [dict1[key]]
-                dict1[key].append(dict2[key])
-        else:
-            dict1[key] = dict2[key]
-    return dict1
-
-
-def _merge_dicts(
-    iterables: list[dict[str, Any]],
-    dict_update: bool,
-    dict_sequence: bool,
-) -> dict[str, Any]:
-    """
-    Merges a list of dictionaries into a single dictionary, with options for
-    handling duplicate keys and sequences.
-
-    Args:
-        iterables: A list of dictionaries to merge.
-        dict_update: If True, overwrite existing keys in dictionaries
-            with those from subsequent dictionaries.
-        dict_sequence: Enables unique key generation for duplicate keys
-            by appending a sequence number
-
-    Returns:
-        The merged dictionary.
-    """
-    merged_dict = {}  # {'a': [1, 2]}
-    sequence_counters = defaultdict(int)
-    list_values = {}
-
-    for d in iterables:  # [{'a': [1, 2]}, {'a': [3, 4]}]
-        for key, value in d.items():  # {'a': [3, 4]}
-            if key not in merged_dict or dict_update:
-                if (
-                    key in merged_dict
-                    and isinstance(merged_dict[key], dict)
-                    and isinstance(value, dict)
-                ):
-                    _deep_merge_dicts(merged_dict[key], value)
-                else:
-                    merged_dict[key] = value  # {'a': [1, 2]}
-                    if isinstance(value, list):
-                        list_values[key] = True
-            elif dict_sequence:
-                sequence_counters[key] += 1
-                new_key = f"{key}{sequence_counters[key]}"
-                merged_dict[new_key] = value
-            else:
-                if not isinstance(merged_dict[key], list) or list_values.get(
-                    key, False
-                ):
-                    merged_dict[key] = [merged_dict[key]]
-                merged_dict[key].append(value)
-
-    return merged_dict
-
-
-def _merge_sequences(
-    iterables: list[list[Any]],
-    sort_list: bool,
-    custom_sort: Callable[[Any], Any] | None = None,
-) -> list[Any]:
-    """
-    Merges a list of lists into a single list, with options for sorting and
-    custom sorting logic.
-
-    Args:
-        iterables: A list of lists to merge.
-        sort_list: When True, sort the resulting list after merging.
-        custom_sort: An optional callable that defines custom sorting logic
-            for the merged list.
-
-    Returns:
-        The merged list.
-    """
-    merged_list = list(chain(*iterables))
-    if sort_list:
-        if custom_sort:
-            return sorted(merged_list, key=custom_sort)
-        else:
-            return sorted(merged_list, key=lambda x: (isinstance(x, str), x))
-    return merged_list

lionagi/libs/nested/npop.py

@@ -1,69 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from collections.abc import Sequence
-from typing import Any
-
-from lionagi.utils import UNDEFINED, to_list
-
-
-def npop(
-    input_: dict[str, Any] | list[Any],
-    /,
-    indices: str | int | Sequence[str | int],
-    default: Any = UNDEFINED,
-) -> Any:
-    """
-    Perform a nested pop operation on the input structure.
-
-    This function navigates through the nested structure using the provided
-    indices and removes and returns the value at the final location.
-
-    Args:
-        input_: The input nested structure (dict or list) to pop from.
-        indices: A single index or a sequence of indices to navigate the
-            nested structure.
-        default: The value to return if the key is not found. If not
-            provided, a KeyError will be raised.
-
-    Returns:
-        The value at the specified nested location.
-
-    Raises:
-        ValueError: If the indices list is empty.
-        KeyError: If a key is not found in a dictionary.
-        IndexError: If an index is out of range for a list.
-        TypeError: If an operation is not supported on the current data type.
-    """
-    if not indices:
-        raise ValueError("Indices list cannot be empty")
-
-    indices = to_list(indices)
-
-    current = input_
-    for key in indices[:-1]:
-        if isinstance(current, dict):
-            if current.get(key):
-                current = current[key]
-            else:
-                raise KeyError(f"{key} is not found in {current}")
-        elif isinstance(current, list) and isinstance(key, int):
-            if key >= len(current):
-                raise KeyError(
-                    f"{key} exceeds the length of the list {current}"
-                )
-            elif key < 0:
-                raise ValueError("list index cannot be negative")
-            current = current[key]
-
-    last_key = indices[-1]
-    try:
-        return current.pop(
-            last_key,
-        )
-    except Exception as e:
-        if default is not UNDEFINED:
-            return default
-        else:
-            raise KeyError(f"Invalid npop. Error: {e}")

lionagi/libs/nested/nset.py

@@ -1,94 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from collections.abc import Sequence
-from typing import Any
-
-from lionagi.utils import to_list
-
-from .utils import ensure_list_index
-
-
-def nset(
-    nested_structure: dict[str, Any] | list[Any],
-    /,
-    indices: str | int | Sequence[str | int],
-    value: Any,
-) -> None:
-    """Set a value within a nested structure at the specified path.
-
-    This method allows setting a value deep within a nested dictionary or list
-    by specifying a path to the target location using a sequence of indices.
-    Each index in the sequence represents a level in the nested structure,
-    with integers used for list indices and strings for dictionary keys.
-
-    Args:
-        nested_structure: The nested structure to modify.
-        indices: The path of indices leading to the target location.
-        value: The value to set at the specified location.
-
-    Raises:
-        ValueError: If the indices sequence is empty.
-        TypeError: If the target container is not a list or dictionary,
-                   or if the index type is incorrect.
-
-    Examples:
-        >>> data = {'a': {'b': [10, 20]}}
-        >>> nset(data, ['a', 'b', 1], 99)
-        >>> assert data == {'a': {'b': [10, 99]}}
-
-        >>> data = [0, [1, 2], 3]
-        >>> nset(data, [1, 1], 99)
-        >>> assert data == [0, [1, 99], 3]
-    """
-
-    if not indices:
-        raise ValueError(
-            "Indices list is empty, cannot determine target container"
-        )
-
-    _indices = to_list(indices)
-    target_container = nested_structure
-
-    for i, index in enumerate(_indices[:-1]):
-        if isinstance(target_container, list):
-            if not isinstance(index, int):
-                raise TypeError("Cannot use non-integer index on a list")
-            ensure_list_index(target_container, index)
-            if target_container[index] is None:
-                next_index = _indices[i + 1]
-                target_container[index] = (
-                    [] if isinstance(next_index, int) else {}
-                )
-        elif isinstance(target_container, dict):
-            if isinstance(index, int):
-                raise TypeError(
-                    f"Unsupported key type: {type(index).__name__}. "
-                    "Only string keys are acceptable."
-                )
-            if index not in target_container:
-                next_index = _indices[i + 1]
-                target_container[index] = (
-                    [] if isinstance(next_index, int) else {}
-                )
-        else:
-            raise TypeError("Target container is not a list or dictionary")
-
-        target_container = target_container[index]
-
-    last_index = _indices[-1]
-    if isinstance(target_container, list):
-        if not isinstance(last_index, int):
-            raise TypeError("Cannot use non-integer index on a list")
-        ensure_list_index(target_container, last_index)
-        target_container[last_index] = value
-    elif isinstance(target_container, dict):
-        if not isinstance(last_index, str):
-            raise TypeError(
-                f"Unsupported key type: {type(last_index).__name__}. "
-                "Only string keys are acceptable."
-            )
-        target_container[last_index] = value
-    else:
-        raise TypeError("Cannot set value on non-list/dict element")