0
# Built-in Functions
1

2
Async versions of Python's built-in functions for iteration, aggregation, and data processing. These functions provide the fundamental async building blocks that mirror Python's standard builtins while working seamlessly with both sync and async iterables.
3

4
## Capabilities
5

6
### Async Iterator Navigation
7

8
Functions for navigating and consuming async iterators.
9

10
```python { .api }
11
async def anext(iterator: AsyncIterator[T]) -> T: ...
12
async def anext(iterator: AsyncIterator[T], default: T) -> T:
13
    """
14
    Retrieve the next item from the async iterator.
15

16
    Parameters:
17
    - iterator: AsyncIterator[T] - The async iterator to get next item from
18
    - default: T, optional - Value to return if iterator is exhausted
19

20
    Returns:
21
    T - The next item from the iterator
22

23
    Raises:
24
    StopAsyncIteration - If iterator is exhausted and no default provided
25
    """
26
```
27

28
Usage example:
29
```python
30
async def example():
31
    async def async_gen():
32
        yield 1
33
        yield 2
34
    
35
    it = aiter(async_gen())
36
    first = await anext(it)  # 1
37
    second = await anext(it)  # 2
38
    third = await anext(it, "done")  # "done" (default value)
39
```
40

41
### Iterator Creation
42

43
Create async iterators from various input types.
44

45
```python { .api }
46
def iter(subject: AnyIterable[T]) -> AsyncIterator[T]: ...
47
def iter(subject: Callable[[], Awaitable[T | None]], sentinel: None) -> AsyncIterator[T]: ...
48
def iter(subject: Callable[[], Awaitable[T]], sentinel: T) -> AsyncIterator[T]:
49
    """
50
    Create an async iterator from subject.
51

52
    Parameters:
53
    - subject: AnyIterable[T] or Callable - Iterable or callable to create iterator from
54
    - sentinel: T, optional - Sentinel value for callable subjects
55

56
    Returns:
57
    AsyncIterator[T] - Async iterator yielding items from subject
58
    """
59
```
60

61
### Iteration and Enumeration
62

63
Transform and enumerate items from async iterables.
64

65
```python { .api }
66
def zip(*, strict: bool = False) -> AsyncIterator[Any]: ...
67
def zip(__it1: AnyIterable[T1], *, strict: bool = False) -> AsyncIterator[tuple[T1]]: ...
68
def zip(__it1: AnyIterable[T1], __it2: AnyIterable[T2], *, strict: bool = False) -> AsyncIterator[tuple[T1, T2]]: ...
69
def zip(__it1: AnyIterable[T1], __it2: AnyIterable[T2], __it3: AnyIterable[T3], *, strict: bool = False) -> AsyncIterator[tuple[T1, T2, T3]]: ...
70
def zip(__it1: AnyIterable[T1], __it2: AnyIterable[T2], __it3: AnyIterable[T3], __it4: AnyIterable[T4], *, strict: bool = False) -> AsyncIterator[tuple[T1, T2, T3, T4]]: ...
71
def zip(__it1: AnyIterable[T1], __it2: AnyIterable[T2], __it3: AnyIterable[T3], __it4: AnyIterable[T4], __it5: AnyIterable[T5], *, strict: bool = False) -> AsyncIterator[tuple[T1, T2, T3, T4, T5]]: ...
72
def zip(__it1: AnyIterable[Any], __it2: AnyIterable[Any], __it3: AnyIterable[Any], __it4: AnyIterable[Any], __it5: AnyIterable[Any], *iterables: AnyIterable[Any], strict: bool = False) -> AsyncIterator[tuple[Any, ...]]:
73
    """
74
    Zip multiple iterables together.
75

76
    Parameters:
77
    - *iterables: AnyIterable - Variable number of iterables to zip
78
    - strict: bool - If True, iterables must have same length
79

80
    Returns:
81
    AsyncIterator[tuple] - Iterator of tuples containing items from each iterable
82
    """
83

84
def map(function: Callable[[T1], Awaitable[R]], __it1: AnyIterable[T1], /) -> AsyncIterator[R]: ...
85
def map(function: Callable[[T1], R], __it1: AnyIterable[T1], /) -> AsyncIterator[R]: ...
86
def map(function: Callable[[T1, T2], Awaitable[R]], __it1: AnyIterable[T1], __it2: AnyIterable[T2], /) -> AsyncIterator[R]: ...
87
def map(function: Callable[[T1, T2], R], __it1: AnyIterable[T1], __it2: AnyIterable[T2], /) -> AsyncIterator[R]: ...
88
def map(function: Callable[[T1, T2, T3], Awaitable[R]], __it1: AnyIterable[T1], __it2: AnyIterable[T2], __it3: AnyIterable[T3], /) -> AsyncIterator[R]: ...
89
def map(function: Callable[[T1, T2, T3], R], __it1: AnyIterable[T1], __it2: AnyIterable[T2], __it3: AnyIterable[T3], /) -> AsyncIterator[R]: ...
90
def map(function: Callable[..., Awaitable[R]], __it1: AnyIterable[Any], __it2: AnyIterable[Any], __it3: AnyIterable[Any], __it4: AnyIterable[Any], __it5: AnyIterable[Any], /, *iterable: AnyIterable[Any]) -> AsyncIterator[R]: ...
91
def map(function: Callable[..., R], __it1: AnyIterable[Any], __it2: AnyIterable[Any], __it3: AnyIterable[Any], __it4: AnyIterable[Any], __it5: AnyIterable[Any], /, *iterable: AnyIterable[Any]) -> AsyncIterator[R]:
92
    """
93
    Apply function to items from iterables.
94

95
    Parameters:
96
    - function: Callable - Function to apply (can be sync or async)
97
    - *iterables: AnyIterable - Iterables to map over
98

99
    Returns:
100
    AsyncIterator[R] - Iterator of function results
101
    """
102

103
def filter(function: None, iterable: AnyIterable[T | None]) -> AsyncIterator[T]: ...
104
def filter(function: Callable[[T], TypeGuard[R]], iterable: AnyIterable[T]) -> AsyncIterator[R]: ...
105
def filter(function: Callable[[T], Any], iterable: AnyIterable[T]) -> AsyncIterator[T]:
106
    """
107
    Filter items based on predicate function.
108

109
    Parameters:
110
    - function: Callable[[T], bool] or None - Predicate function (None filters falsy values)
111
    - iterable: AnyIterable[T] - Iterable to filter
112

113
    Returns:
114
    AsyncIterator[T] - Iterator of items where predicate is True
115
    """
116

117
def enumerate(iterable: AnyIterable[T], start: int = 0) -> AsyncIterator[tuple[int, T]]:
118
    """
119
    Return enumerated async iterator with indices.
120

121
    Parameters:
122
    - iterable: AnyIterable[T] - Iterable to enumerate
123
    - start: int - Starting index value
124

125
    Returns:
126
    AsyncIterator[tuple[int, T]] - Iterator of (index, item) tuples
127
    """
128
```
129

130
### Aggregation Functions
131

132
Aggregate values from async iterables.
133

134
```python { .api }
135
async def all(iterable: AnyIterable[Any]) -> bool:
136
    """
137
    Check if all elements are truthy.
138

139
    Parameters:
140
    - iterable: AnyIterable[Any] - Iterable to check
141

142
    Returns:
143
    bool - True if all elements are truthy, False otherwise
144
    """
145

146
async def any(iterable: AnyIterable[Any]) -> bool:
147
    """
148
    Check if any element is truthy.
149

150
    Parameters:
151
    - iterable: AnyIterable[Any] - Iterable to check
152

153
    Returns:
154
    bool - True if any element is truthy, False otherwise
155
    """
156

157
async def max(iterable: AnyIterable[LT], *, key: None = None) -> LT: ...
158
async def max(iterable: AnyIterable[LT], *, key: None = None, default: T) -> LT | T: ...
159
async def max(iterable: AnyIterable[T1], *, key: Callable[[T1], LT]) -> T1: ...
160
async def max(iterable: AnyIterable[T1], *, key: Callable[[T1], LT], default: T2) -> T1 | T2:
161
    """
162
    Find maximum value in iterable.
163

164
    Parameters:
165
    - iterable: AnyIterable[T] - Iterable to find max in
166
    - key: Callable[[T], Any], optional - Key function for comparison
167
    - default: T, optional - Value to return if iterable is empty
168

169
    Returns:
170
    T - Maximum value
171

172
    Raises:
173
    ValueError - If iterable is empty and no default provided
174
    """
175

176
async def min(iterable: AnyIterable[LT], *, key: None = None) -> LT: ...
177
async def min(iterable: AnyIterable[LT], *, key: None = None, default: T) -> LT | T: ...
178
async def min(iterable: AnyIterable[T1], *, key: Callable[[T1], LT]) -> T1: ...
179
async def min(iterable: AnyIterable[T1], *, key: Callable[[T1], LT], default: T2) -> T1 | T2:
180
    """
181
    Find minimum value in iterable.
182

183
    Parameters:
184
    - iterable: AnyIterable[T] - Iterable to find min in
185
    - key: Callable[[T], Any], optional - Key function for comparison
186
    - default: T, optional - Value to return if iterable is empty
187

188
    Returns:
189
    T - Minimum value
190

191
    Raises:
192
    ValueError - If iterable is empty and no default provided
193
    """
194

195
async def sum(iterable: AnyIterable[int]) -> int: ...
196
async def sum(iterable: AnyIterable[float]) -> float: ...
197
async def sum(iterable: AnyIterable[ADD], start: ADD) -> ADD:
198
    """
199
    Sum numeric values from iterable.
200

201
    Parameters:
202
    - iterable: AnyIterable[Numeric] - Iterable of numeric values
203
    - start: Numeric - Starting value for summation
204

205
    Returns:
206
    Numeric - Sum of all values plus start
207
    """
208
```
209

210
### Collection Construction
211

212
Convert async iterables to Python collection types.
213

214
```python { .api }
215
async def list() -> list[Any]: ...
216
async def list(iterable: AnyIterable[T]) -> list[T]:
217
    """
218
    Convert async iterable to list.
219

220
    Parameters:
221
    - iterable: AnyIterable[T] - Iterable to convert
222

223
    Returns:
224
    list[T] - List containing all items from iterable
225
    """
226

227
async def dict() -> dict[Any, Any]: ...
228
async def dict(iterable: AnyIterable[tuple[HK, T]]) -> dict[HK, T]: ...
229
async def dict(iterable: AnyIterable[tuple[str, T]] = (), **kwargs: T) -> dict[str, T]:
230
    """
231
    Convert async iterable to dict.
232

233
    Parameters:
234
    - iterable: AnyIterable[tuple[K, V]] - Iterable of key-value pairs
235
    - **kwargs: V - Additional keyword arguments as key-value pairs
236

237
    Returns:
238
    dict[K, V] - Dictionary from iterable and kwargs
239
    """
240

241
async def set() -> set[Any]: ...
242
async def set(iterable: AnyIterable[T] = ()) -> set[T]:
243
    """
244
    Convert async iterable to set.
245

246
    Parameters:
247
    - iterable: AnyIterable[T] - Iterable to convert
248

249
    Returns:
250
    set[T] - Set containing unique items from iterable
251
    """
252

253
async def tuple() -> tuple[()]: ...
254
async def tuple(iterable: AnyIterable[T]) -> tuple[T, ...]:
255
    """
256
    Convert async iterable to tuple.
257

258
    Parameters:
259
    - iterable: AnyIterable[T] - Iterable to convert
260

261
    Returns:
262
    tuple[T, ...] - Tuple containing all items from iterable
263
    """
264

265
async def sorted(iterable: AnyIterable[LT], *, key: None = None, reverse: bool = False) -> list[LT]: ...
266
async def sorted(iterable: AnyIterable[T], *, key: Callable[[T], LT], reverse: bool = False) -> list[T]:
267
    """
268
    Return sorted list from iterable.
269

270
    Parameters:
271
    - iterable: AnyIterable[T] - Iterable to sort
272
    - key: Callable[[T], Any], optional - Key function for sorting
273
    - reverse: bool - If True, sort in descending order
274

275
    Returns:
276
    list[T] - Sorted list of items
277
    """
278
```
279

280
## Usage Examples
281

282
### Basic Aggregation
283
```python
284
async def aggregate_example():
285
    async def numbers():
286
        for i in range(10):
287
            yield i
288
    
289
    total = await sum(numbers())  # 45
290
    all_positive = await all(map(lambda x: x >= 0, numbers()))  # True
291
    has_five = await any(map(lambda x: x == 5, numbers()))  # True
292
```
293

294
### Collection Building
295
```python
296
async def collect_example():
297
    async def pairs():
298
        for i in range(5):
299
            yield (f"key_{i}", i * 2)
300
    
301
    items = await list(pairs())  # [('key_0', 0), ('key_1', 2), ...]
302
    lookup = await dict(pairs())  # {'key_0': 0, 'key_1': 2, ...}
303
    values = await set(map(lambda p: p[1], pairs()))  # {0, 2, 4, 6, 8}
304
```