List Utilities

The rite.collections.list subpackage provides higher-level list manipulation helpers such as chunking, flattening, grouping, and partitioning sequences.

List Operations Module

Utilities for list manipulation and transformation.

Functions

• list_unique: Remove duplicates while preserving order.
• list_flatten: Flatten nested lists recursively.
• list_chunk: Split list into chunks.
• list_group_by: Group items by key function or attribute.
• list_partition: Split list into two based on predicate.
• list_interleave: Interleave multiple lists.

Examples

from rite.collections.list import list_unique, list_chunk list_unique([1, 2, 2, 3]) [1, 2, 3] list_chunk([1, 2, 3, 4, 5], size=2) [[1, 2], [3, 4], [5]]

Modules

list_chunk

List Chunk

Split a list into chunks of specified size.

Functions

• list_chunk: Split list into smaller chunks.

Examples

from rite.collections.list import list_chunk list_chunk([1, 2, 3, 4, 5], size=2) [[1, 2], [3, 4], [5]] list_chunk([1, 2, 3, 4, 5, 6], size=3) [[1, 2, 3], [4, 5, 6]]

Functions

list_chunk(items: list[T], size: int) -> list[list[T]]

Split a list into chunks of specified size.

Parameters:

Name	Type	Description	Default
items	list[T]	List to split into chunks.	required
size	int	Size of each chunk. Must be positive.	required

Returns:

Type	Description
list[list[T]]	List of chunks, last chunk may be smaller.

Raises:

Type	Description
ValueError	If size is not positive.

Examples:

>>> list_chunk([1, 2, 3, 4, 5], size=2)
[[1, 2], [3, 4], [5]]
>>> list_chunk([1, 2, 3, 4, 5, 6], size=3)
[[1, 2, 3], [4, 5, 6]]
>>> list_chunk([], size=2)
[]
>>> list_chunk([1, 2, 3], size=5)
[[1, 2, 3]]

list_flatten

List Flatten

Flatten nested lists into a single-level list.

Functions

• list_flatten: Flatten nested lists recursively.

Examples

from rite.collections.list import list_flatten list_flatten([[1, 2], [3, 4], [5]]) [1, 2, 3, 4, 5] list_flatten([[1, [2, 3]], [4, 5]]) [1, 2, 3, 4, 5]

Functions

list_flatten(items: list[Any], depth: int | None = None) -> list[Any]

Flatten nested lists recursively.

Parameters:

Name	Type	Description	Default
items	list[Any]	List that may contain nested lists.	required
depth	int | None	Maximum depth to flatten. None for full recursion.	None

Returns:

Type	Description
list[Any]	Flattened list.

Examples:

>>> list_flatten([[1, 2], [3, 4], [5]])
[1, 2, 3, 4, 5]
>>> list_flatten([[1, [2, 3]], [4, 5]])
[1, 2, 3, 4, 5]
>>> list_flatten([[1, [2, [3]]], [4]], depth=1)
[1, [2, [3]], 4]
>>> list_flatten([])
[]

list_group_by

List Group By

Group list items by a key function or attribute.

Functions

• list_group_by: Group items by key.

Examples

from rite.collections.list import list_group_by data = [{"type": "fruit", "name": "apple"}] list_group_by(data, key="type") {'fruit': [{'type': 'fruit', 'name': 'apple'}]}

Functions

list_group_by(items: list[T], key: str | Callable[[T], K]) -> dict[Any, list[T]]

Group list items by a key function or dict key.

Parameters:

Name	Type	Description	Default
items	list[T]	List of items to group.	required
key	str | Callable[[T], K]	Either attribute name (str) or function to extract key.	required

Returns:

Type	Description
dict[Any, list[T]]	Dictionary mapping keys to lists of items.

Examples:

>>> data = [
...     {"type": "fruit", "name": "apple"},
...     {"type": "fruit", "name": "banana"},
...     {"type": "veg", "name": "carrot"}
... ]
>>> list_group_by(data, key="type")
{'fruit': [...], 'veg': [...]}
>>> list_group_by([1, 2, 3, 4], key=lambda x: x % 2)
{1: [1, 3], 0: [2, 4]}

list_interleave

List Interleave

Interleave multiple lists together.

Functions

• list_interleave: Combine lists by alternating elements.

Examples

from rite.collections.list import list_interleave list_interleave([1, 2, 3], ['a', 'b', 'c']) [1, 'a', 2, 'b', 3, 'c']

Functions

list_interleave(*lists: list[Any]) -> list[Any]

Interleave multiple lists by alternating elements.

Parameters:

Name	Type	Description	Default
*lists	list[Any]	Variable number of lists to interleave.	()

Returns:

Type	Description
list[Any]	New list with elements from all lists interleaved.

Examples:

>>> list_interleave([1, 2, 3], ['a', 'b', 'c'])
[1, 'a', 2, 'b', 3, 'c']
>>> list_interleave([1, 2], [10, 20], [100, 200])
[1, 10, 100, 2, 20, 200]
>>> list_interleave([1, 2, 3], ['a'])
[1, 'a', 2, 3]
>>> list_interleave([])
[]

list_partition

List Partition

Partition a list into two lists based on a predicate function.

Functions

• list_partition: Split list into matching and non-matching items.

Examples

from rite.collections.list import list_partition list_partition([1, 2, 3, 4, 5], lambda x: x % 2 == 0) ([2, 4], [1, 3, 5])

Functions

list_partition(items: list[T], predicate: Callable[[T], bool]) -> tuple[list[T], list[T]]

Partition a list based on a predicate function.

Parameters:

Name	Type	Description	Default
items	list[T]	List to partition.	required
predicate	Callable[[T], bool]	Function that returns True for items in first list.	required

Returns:

Type	Description
tuple[list[T], list[T]]	Tuple of (matching_items, non_matching_items).

Examples:

>>> list_partition([1, 2, 3, 4, 5], lambda x: x % 2 == 0)
([2, 4], [1, 3, 5])
>>> list_partition(['a', 'bb', 'ccc'], lambda x: len(x) > 1)
(['bb', 'ccc'], ['a'])
>>> list_partition([], lambda x: True)
([], [])

list_unique

List Unique

Remove duplicate elements from a list while preserving order.

Functions

• list_unique: Remove duplicates from a list.

Examples

from rite.collections.list import list_unique list_unique([1, 2, 2, 3, 3, 3]) [1, 2, 3] list_unique(['a', 'b', 'a', 'c']) ['a', 'b', 'c']

Functions

list_unique(items: list[T]) -> list[T]

Remove duplicate elements while preserving order.

Uses a set to track seen elements and preserves first occurrence of each unique element.

Parameters:

Name	Type	Description	Default
items	list[T]	List that may contain duplicates.	required

Returns:

Type	Description
list[T]	New list with duplicates removed, order preserved.

Examples:

>>> list_unique([1, 2, 2, 3, 3, 3])
[1, 2, 3]
>>> list_unique(['a', 'b', 'a', 'c'])
['a', 'b', 'c']
>>> list_unique([])
[]

options: show_root_heading: true show_source: false heading_level: 2