lionagi 0.16.2__py3-none-any.whl → 0.17.0__py3-none-any.whl

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")

lionagi/libs/nested/unflatten.py

@@ -1,83 +0,0 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any
-
-
-def unflatten(
-    flat_dict: dict[str, Any], sep: str = "|", inplace: bool = False
-) -> dict[str, Any] | list[Any]:
-    """
-    Unflatten a single-level dictionary into a nested dictionary or list.
-
-    Args:
-        flat_dict: The flattened dictionary to unflatten.
-        sep: The separator used for joining keys.
-        inplace: Whether to modify the input dictionary in place.
-
-    Returns:
-        The unflattened nested dictionary or list.
-
-    Examples:
-        >>> unflatten({"a|b|c": 1, "a|b|d": 2})
-        {'a': {'b': {'c': 1, 'd': 2}}}
-
-        >>> unflatten({"0": "a", "1": "b", "2": "c"})
-        ['a', 'b', 'c']
-    """
-
-    def _unflatten(data: dict) -> dict | list:
-        result = {}
-        for key, value in data.items():
-            parts = key.split(sep)
-            current = result
-            for part in parts[:-1]:
-                if part not in current:
-                    current[part] = {}
-                current = current[part]
-            if isinstance(value, dict):
-                current[parts[-1]] = _unflatten(value)
-            else:
-                current[parts[-1]] = value
-
-        # Convert dictionary to list if keys are consecutive integers
-        if result and all(
-            isinstance(key, str) and key.isdigit() for key in result
-        ):
-            return [result[str(i)] for i in range(len(result))]
-        return result
-
-    if inplace:
-        unflattened_dict = {}
-        for key, value in flat_dict.items():
-            parts = key.split(sep)
-            current = unflattened_dict
-            for part in parts[:-1]:
-                if part not in current:
-                    current[part] = {}
-                current = current[part]
-            current[parts[-1]] = value
-
-        unflattened_result = _unflatten(unflattened_dict)
-        flat_dict.clear()
-        if isinstance(unflattened_result, list):
-            flat_dict.update(
-                {str(i): v for i, v in enumerate(unflattened_result)}
-            )
-        else:
-            flat_dict.update(unflattened_result)
-        return flat_dict
-
-    else:
-        unflattened_dict = {}
-        for key, value in flat_dict.items():
-            parts = key.split(sep)
-            current = unflattened_dict
-            for part in parts[:-1]:
-                if part not in current:
-                    current[part] = {}
-                current = current[part]
-            current[parts[-1]] = value
-
-        return _unflatten(unflattened_dict)

lionagi/libs/nested/utils.py

@@ -1,189 +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
-
-
-def is_homogeneous(
-    iterables: list[Any] | dict[Any, Any], type_check: type | tuple[type, ...]
-) -> bool:
-    """
-    Check if all elements in a list or all values in a dict are of same type.
-
-    Args:
-        iterables: The list or dictionary to check.
-        type_check: The type to check against.
-
-    Returns:
-        True if all elements/values are of the same type, False otherwise.
-    """
-    if isinstance(iterables, list):
-        return all(isinstance(it, type_check) for it in iterables)
-
-    elif isinstance(iterables, dict):
-        return all(isinstance(val, type_check) for val in iterables.values())
-
-    else:
-        return isinstance(iterables, type_check)
-
-
-def is_same_dtype(
-    input_: list[Any] | dict[Any, Any],
-    dtype: type | None = None,
-    return_dtype: bool = False,
-) -> bool | tuple[bool, type | None]:
-    """
-    Check if all elements in a list or dict values are of the same data type.
-
-    Args:
-        input_: The input list or dictionary to check.
-        dtype: The data type to check against. If None, uses the type of the
-            first element.
-        return_dtype: If True, return the data type with the check result.
-
-    Returns:
-        If return_dtype is False, returns True if all elements are of the
-        same type (or if the input is empty), False otherwise.
-        If return_dtype is True, returns a tuple (bool, type | None).
-    """
-    if not input_:
-        return True
-
-    iterable = input_.values() if isinstance(input_, dict) else input_
-    first_element_type = type(next(iter(iterable), None))
-
-    dtype = dtype or first_element_type
-
-    result = all(isinstance(element, dtype) for element in iterable)
-    return (result, dtype) if return_dtype else result
-
-
-def is_structure_homogeneous(
-    structure: Any, return_structure_type: bool = False
-) -> bool | tuple[bool, type | None]:
-    """
-    Check if a nested structure is homogeneous (no mix of lists and dicts).
-
-    Args:
-        structure: The nested structure to check.
-        return_structure_type: If True, return the type of the homogeneous
-            structure.
-
-    Returns:
-        If return_structure_type is False, returns True if the structure is
-        homogeneous, False otherwise.
-        If True, returns a tuple (bool, type | None).
-
-    Examples:
-        >>> is_structure_homogeneous({'a': {'b': 1}, 'c': {'d': 2}})
-        True
-        >>> is_structure_homogeneous({'a': {'b': 1}, 'c': [1, 2]})
-        False
-    """
-
-    def _check_structure(substructure):
-        structure_type = None
-        if isinstance(substructure, list):
-            structure_type = list
-            for item in substructure:
-                if not isinstance(item, structure_type) and isinstance(
-                    item, list | dict
-                ):
-                    return False, None
-                result, _ = _check_structure(item)
-                if not result:
-                    return False, None
-        elif isinstance(substructure, dict):
-            structure_type = dict
-            for item in substructure.values():
-                if not isinstance(item, structure_type) and isinstance(
-                    item, list | dict
-                ):
-                    return False, None
-                result, _ = _check_structure(item)
-                if not result:
-                    return False, None
-        return True, structure_type
-
-    is_homogeneous, structure_type = _check_structure(structure)
-    return (
-        (is_homogeneous, structure_type)
-        if return_structure_type
-        else is_homogeneous
-    )
-
-
-def deep_update(
-    original: dict[Any, Any], update: dict[Any, Any]
-) -> dict[Any, Any]:
-    """
-    Recursively merge two dicts, updating nested dicts instead of overwriting.
-
-    Args:
-        original: The dictionary to update.
-        update: The dictionary containing updates to apply to `original`.
-
-    Returns:
-        The `original` dictionary after applying updates from `update`.
-
-    Note:
-        This method modifies the `original` dictionary in place.
-    """
-    for key, value in update.items():
-        if isinstance(value, dict) and key in original:
-            original[key] = deep_update(original.get(key, {}), value)
-        else:
-            original[key] = value
-    return original
-
-
-def get_target_container(
-    nested: list[Any] | dict[Any, Any], indices: list[int | str]
-) -> list[Any] | dict[Any, Any]:
-    """
-    Retrieve the target container in a nested structure using indices.
-
-    Args:
-        nested: The nested structure to navigate.
-        indices: A list of indices to navigate through the nested structure.
-
-    Returns:
-        The target container at the specified path.
-
-    Raises:
-        IndexError: If a list index is out of range.
-        KeyError: If a dictionary key is not found.
-        TypeError: If the current element is neither a list nor a dictionary.
-    """
-    current_element = nested
-    for index in indices:
-        if isinstance(current_element, list):
-            if isinstance(index, str) and index.isdigit():
-                index = int(index)
-
-            if isinstance(index, int) and 0 <= index < len(current_element):
-                current_element = current_element[index]
-
-            else:
-                raise IndexError("List index is invalid or out of range")
-
-        elif isinstance(current_element, dict):
-            if index in current_element:
-                current_element = current_element.get(index, None)
-            else:
-                raise KeyError("Key not found in dictionary")
-        else:
-            raise TypeError(
-                "Current element is neither a list nor a dictionary"
-            )
-    return current_element
-
-
-def ensure_list_index(
-    lst: list[Any], index: int, default: Any = UNDEFINED
-) -> None:
-    while len(lst) <= index:
-        lst.append(default if default is not UNDEFINED else None)