API Reference

any

any()

any(predicate: Callable[[T], bool] | None = None)

Bases: Extension[Iterable[T], [Callable[[T], bool] | None], bool]

Whether the iterable contains any elements, or whether the iterable contains any element that satisfies the predicate.

Parameters:

predicate
(Callable[[T], bool] | None, default: None ) –

Function to evaluate per element. Defaults to None.

Example

source = [1, 2, 3]

result = source | any[int](lambda x: x == 2)

print(result)
# True

count

count()

Bases: Extension[Iterable[T], [], int]

Count the number of elements in an iterable.

Example

source = [1, 1, 1, 1, 1]

print(source | count())
# 5

distinct

distinct()

Bases: Extension[Iterable[T], [], Iterable[T]]

Returns distinct elements from the iterable.

Example

source = [1, 3, 4, 1, 3, 7, 9, 3, 7]

result = source | distinct()

print(list(result))
# [1, 3, 4, 7, 9]

first

first()

Bases: Extension[Iterable[T], [], T]

Take the first element of an iterable.

Raises:

ValueError –

If the iterable contains no elements.

Example

source = [4, 7, 2]

result = source | first()

print(result)
# 4

first_or_none

first_or_none()

Bases: Extension[Iterable[T], [], T | None]

Take the first element of an iterable. Returns None if the iterable is empty.

Examples:

source = [4, 7, 2]

result = source | first_or_none()

print(result)
# 4

group_by

group_by(key_selector: Callable[[T], TKey])

Bases: Extension[Iterable[T], [Callable[[T], TKey]], Iterable[Grouping[T, TKey]]]

Group the elements in an iterable based on a key.

No prior sorting required.

Parameters:

key_selector
(Callable[[T], TKey]) –

Function to generate the key for each element.

Note

While the returned Grouping object itself is an iterable that is evaluated lazily, the elements within each individual group are materialized into list when their group is iterated. This may lead to memory issues in case of a large number of elements.

Example

@dataclass
class Person:
    age: int
    name: str


source = [
    Person(10, "Arthur"),
    Person(10, "Becky"),
    Person(20, "Chris"),
    Person(30, "Dave"),
    Person(30, "Eduardo"),
    Person(30, "Felice"),
]

grouped = source | group_by[Person, int](lambda p: p.age)

print(list(grouped))
# [
#   10: [Person(age=10, name='Arthur'), Person(age=10, name='Becky')],
#   20: [Person(age=20, name='Chris')],
#   30: [Person(age=30, name='Dave'), Person(age=30, name='Eduardo'), Person(age=30, name='Felice')]
# ]

order_by

order_by(key_selector: Callable[[T], TKey])

Bases: Extension[Iterable[T], [Callable[[T], TKey]], Iterable[T]]

Order the elements in an iterable based on a key in ascending order.

Parameters:

key_selector
(Callable[[T], TKey]) –

Function to generate the key for each element.

Note

order_by materializes the entire input iterable, i.e. does not evaluate lazily. This may lead to memory issues in case of large iterables.

Example

@dataclass
class Person:
    age: int
    name: str

source = [
    Person(31, "Arthur"),
    Person(12, "Becky"),
    Person(45, "Chris"),
]

ordered = source | order_by[Person, int](lambda p: p.age)

print(list(ordered))
# [
#     Person(age=12, name='Becky'),
#     Person(age=31, name='Arthur'),
#     Person(age=45, name='Chris')
# ]

order_by_descending

order_by_descending(key_selector: Callable[[T], TKey])

Bases: Extension[Iterable[T], [Callable[[T], TKey]], Iterable[T]]

Order the elements in an iterable based on a key in descending order.

Parameters:

key_selector
(Callable[[T], TKey]) –

Function to generate the key for each element.

Note

order_by_descending materializes the entire input iterable, i.e. does not evaluate lazily. This may lead to memory issues in case of large iterables.

Example

@dataclass
class Person:
    age: int
    name: str

source = [
    Person(31, "Arthur"),
    Person(12, "Becky"),
    Person(45, "Chris"),
]

ordered = source | order_by_descending[Person, int](lambda p: p.age)

print(list(ordered))
# [
#     Person(age=45, name='Chris')
#     Person(age=31, name='Arthur'),
#     Person(age=12, name='Becky'),
# ]

last

last()

Bases: Extension[Iterable[T], [], T]

Find the last element of an iterable.

Raises:

ValueError –

If the iterable contains no elements.

Example

source = [4, 7, 2]

result = source | last()

print(result)
# 2

last_or_none

last_or_none()

Bases: Extension[Iterable[T], [], T | None]

Find the last element of an iterable, or returns None if the iterable is empty.

Example

source = [4, 7, 2]

result = source | last_or_none()

print(result)
# 2

max

max()

Bases: Extension[Iterable[T], [], T]

Takes the maximum value in an iterable

Raises:

ValueError –

If the iterable contains no elements.

Example

source = [4, 7, 2]

result = source | max()

print(result)
# 7

min

min()

Bases: Extension[Iterable[T], [], T]

Takes the minimum value in an iterable

Raises:

ValueError –

If the iterable contains no elements.

Example

source = [4, 7, 2]

result = source | min()

print(result)
# 2

select

select(selector: Callable[[TIn], TOut])

Bases: Extension[Iterable[TIn], [Callable[[TIn], TOut]], Iterable[TOut]]

Transform each element in an iterable according to a selector function.

Parameters:

selector
(Callable[[TIn], TOut]) –

Function to transform each element.

Example:

    source = [1, 2, 3, 4, 5]

    transformed = source | select[int, str](lambda x: str(2 * x))

    print(list(transformed))
    # ['2', '4', '6', '8', '10']

single

single()

Bases: Extension[Iterable[T], [], T]

Takes the single element of an iterable.

Raises:

ValueError –

If the iterable contains no elements, or more than one.

Example

source = [4]

result = source | single()

print(result)
# 4

single_or_none

single_or_none()

Bases: Extension[Iterable[T], [], T | None]

Takes the single element of an iterable, or returns None if the iterable is empty.

Raises:

ValueError –

If the iterable contains more than one element.

Example

source = [4]

result = source | single_or_none()

print(result)
# 4

to_dictionary

to_dictionary(key_selector: Callable[[T], TKey])

to_dictionary(key_selector: Callable[[T], TKey], value_selector: Callable[[T], TValue])

Bases: Extension[Iterable[T], [Callable[[T], TKey], Callable[[T], TValue] | None], dict[TKey, TValue]]

Transform an iterable into a dictionary based on a key. Optionally transform each element.

Parameters:

key_selector
(Callable[[TIn], TKey]) –

Function to generate key for each element.
value_selector
(Callable[[TIn], TValue] | None, default: None ) –

Function to transform each element. Defaults to None.

Example

@dataclass
class Person:
    age: int
    name: str


source = [
    Person(31, "Arthur"),
    Person(12, "Becky"),
    Person(45, "Chris"),
]

dict = source | to_dictionary[Person, int, str](
    lambda p: p.age,
    lambda p: p.name.upper(),
)

print(dict)
# {31: 'ARTHUR', 12: 'BECKY', 45: 'CHRIS'}

to_list

to_list()

Bases: Extension[Iterable[T], [], list[T]]

Materialize an iterable into a list.

Example

source = range(5)

lst = source | to_list()

print(lst)
# [0, 1, 2, 3, 4]

where

where(predicate: Callable[[T], bool])

Bases: Extension[Iterable[T], [Callable[[T], bool]], Iterable[T]]

Filter an iterable based on a predicate. Only elements for which the predicate evaluates to true are included in the resulting iterable.

Parameters:

predicate
(Callable[[T], bool]) –

Function to include an element.

Example

source = [1, 2, 3, 4, 5]

filtered = source | where[int](lambda x: x > 3)

print(list(filtered))
# [4, 5]

API Reference

any

`predicate`

count

distinct

first

first_or_none

group_by

`key_selector`

order_by

`key_selector`

order_by_descending

`key_selector`

last

last_or_none

max

min

select

`selector`

single

single_or_none

to_dictionary

`key_selector`

`value_selector`

to_list

where

`predicate`