hbutils.collection.structural

Structural operations for nested collection processing.

This module provides utilities for flattening nested sequences and walking through nested structures composed of dictionaries, lists, and tuples. It exposes functions to flatten nested sequences into a flat list as well as to traverse nested structures and retrieve full paths to each leaf element.

The module contains the following public components:

• sq_flatten() - Recursively flatten a nested sequence into a flat list.

• nested_walk() - Yield path-value pairs for each leaf element in a nested structure.

• nested_flatten() - Collect path-value pairs from a nested structure into a list.

Example:

>>> from hbutils.collection.structural import sq_flatten, nested_walk, nested_flatten
>>> sq_flatten([1, [2, (3, 4)], 5])
[1, 2, 3, 4, 5]
>>> list(nested_walk({'a': 1, 'b': [2, {'c': 3}]}))
[(('a',), 1), (('b', 0), 2), (('b', 1, 'c'), 3)]
>>> nested_flatten({'a': 1, 'b': [2, {'c': 3}]})
[(('a',), 1), (('b', 0), 2), (('b', 1, 'c'), 3)]

__all__

hbutils.collection.structural.__all__ = ['sq_flatten', 'nested_walk', 'nested_flatten']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

sq_flatten

hbutils.collection.structural.sq_flatten(s: list | tuple) → List[Any]

Flatten a nested sequence into a single-level list.

This function recursively flattens nested lists and tuples into a single flat list, preserving the original traversal order of elements.

Parameters:

s (Union[list, tuple]) – The given sequence to flatten (can contain nested lists and tuples).

Returns:

Flattened sequence as a list.

Return type:

List[Any]

Examples::

>>> from hbutils.collection import sq_flatten
>>> sq_flatten([1, 2, [3, 4], [5, [6, 7], (8, 9, 10)], 11])
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

nested_walk

hbutils.collection.structural.nested_walk(s: Any) → Iterator[Tuple[Tuple[int | str, ...], Any]]

Walk through a nested structure and yield paths and values for all leaf elements.

This function traverses nested dictionaries, lists, and tuples, yielding a tuple containing the path (as a tuple of keys/indices) and the value for each leaf element.

Parameters:

s (Any) – Given nested structure to walk through.

Returns:

Iterator yielding tuples of (path, value) for each leaf element.

Return type:

Iterator[Tuple[Tuple[Union[int, str], …], Any]]

Examples::

>>> from hbutils.collection import nested_walk
>>> for p, v in nested_walk({'a': 1, 'b': ['c', 'd', {'x': (3, 4), 'y': 'f'}]}):
...     print(p, v)
...
('a',) 1
('b', 0) c
('b', 1) d
('b', 2, 'x', 0) 3
('b', 2, 'x', 1) 4
('b', 2, 'y') f

nested_flatten

hbutils.collection.structural.nested_flatten(s: Any) → List[Tuple[Tuple[int | str, ...], Any]]

Flatten a nested structure into a list of (path, value) tuples.

This function converts a nested structure (dictionaries, lists, tuples) into a flat list where each element is a tuple containing the path to a leaf element and its value.

Parameters:

s (Any) – Given nested structure to flatten.

Returns:

List of tuples containing (path, value) for each leaf element.

Return type:

List[Tuple[Tuple[Union[int, str], …], Any]]

Examples::

>>> from hbutils.collection import nested_flatten
>>> print(nested_flatten({'a': 1, 'b': ['c', 'd', {'x': (3, 4), 'y': 'f'}]}))
[(('a',), 1), (('b', 0), 'c'), (('b', 1), 'd'), (('b', 2, 'x', 0), 3), (('b', 2, 'x', 1), 4), (('b', 2, 'y'), 'f')]