0
# More Itertools
1

2
More-itertools provides an extensive collection of utility functions for working with Python iterables that extend beyond the standard itertools library. It offers over 150 carefully designed functions organized into categories including grouping operations, windowing functions, combining and augmenting iterables, summarizing tools, selecting and filtering functions, mathematical operations, combinatorics utilities, and various wrapping and utility functions.
3

4
## Package Information
5

6
- **Package Name**: more-itertools
7
- **Type**: Library
8
- **Language**: Python  
9
- **Installation**: `pip install more-itertools`
10

11
## Core Imports
12

13
```python
14
import more_itertools
15
```
16

17
For specific functions:
18

19
```python
20
from more_itertools import chunked, windowed, peekable, take, unique_everseen
21
```
22

23
## Basic Usage
24

25
```python
26
from more_itertools import chunked, windowed, peekable, take, first
27

28
# Break data into chunks
29
data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
30
chunks = list(chunked(data, 3))
31
print(chunks)  # [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]
32

33
# Create sliding windows
34
windows = list(windowed(data, 3))
35
print(windows)  # [(1, 2, 3), (2, 3, 4), (3, 4, 5), ...]
36

37
# Peek ahead in an iterator
38
p = peekable(iter(data))
39
print(p.peek())  # 1 (without consuming)
40
print(next(p))   # 1 (now consumed)
41

42
# Take first n items
43
first_five = take(5, data)
44
print(first_five)  # [1, 2, 3, 4, 5]
45

46
# Get first item safely
47
print(first(data))        # 1
48
print(first([], 'none'))  # 'none'
49
```
50

51
## Architecture
52

53
More-itertools is built around several key design principles:
54

55
- **Composability**: Functions can be easily chained and combined
56
- **Memory Efficiency**: Most functions return iterators rather than lists
57
- **Type Safety**: Comprehensive type hints for all functions
58
- **Compatibility**: Works with any iterable, including custom iterators
59
- **Lazy Evaluation**: Operations are performed on-demand when possible
60

61
The library is organized into two main modules:
62
- **more.py**: Advanced iteration utilities and specialized functions
63
- **recipes.py**: Implementations of itertools documentation recipes and mathematical operations
64

65
## Capabilities
66

67
### Grouping Operations
68

69
Core functionality for breaking iterables into chunks, groups, and partitions.
70

71
```python { .api }
72
def chunked(iterable, n, strict=False):
73
    """Break iterable into lists of length n"""
74

75
def batched(iterable, n, *, strict=False):
76
    """Group items into batches of size n"""
77

78
def grouper(iterable, n, incomplete='fill', fillvalue=None):
79
    """Group into fixed-length chunks with fillvalue"""
80

81
def partition(pred, iterable):
82
    """Partition into false and true groups"""
83
```
84

85
[Grouping Operations](./grouping.md)
86

87
### Windowing Operations
88

89
Functions for creating sliding windows and overlapping views of data.
90

91
```python { .api }
92
def windowed(iterable, n, fillvalue=None, step=1):
93
    """Create sliding window of size n"""
94

95
def pairwise(iterable):
96
    """Return successive overlapping pairs"""
97

98
def stagger(iterable, offsets=(0, 1), longest=False, fillvalue=None):
99
    """Create lagged iterables"""
100
```
101

102
[Windowing Operations](./windowing.md)
103

104
### Lookahead and Lookback
105

106
Advanced iterator wrappers that provide peek and seek capabilities.
107

108
```python { .api }
109
class peekable:
110
    """Iterator that allows peeking ahead"""
111
    def peek(self, default=None): ...
112
    def prepend(self, *values): ...
113

114
class seekable:
115
    """Iterator that allows seeking to positions"""
116
    def seek(self, index): ...
117
    def relative_seek(self, count): ...
118

119
def spy(iterable, n=1):
120
    """Return first n items and iterator"""
121
```
122

123
[Lookahead and Lookback](./lookahead.md)
124

125
### Selecting and Filtering
126

127
Functions for extracting, filtering, and selecting elements from iterables.
128

129
```python { .api }
130
def take(n, iterable):
131
    """Return first n items as list"""
132

133
def first(iterable, default=None):
134
    """Return first item or default"""
135

136
def nth(iterable, n, default=None):
137
    """Return nth item or default"""
138

139
def filter_except(function, iterable, *exceptions):
140
    """Filter with exception handling"""
141
```
142

143
[Selecting and Filtering](./selecting.md)
144

145
### Combining and Augmenting
146

147
Functions for merging, combining, and augmenting iterables.
148

149
```python { .api }
150
def interleave(*iterables):
151
    """Round-robin interleaving"""
152

153
def zip_equal(*iterables):
154
    """Zip ensuring equal lengths"""
155

156
def intersperse(element, iterable):
157
    """Insert element between items"""
158

159
def prepend(value, iterator):
160
    """Prepend value to iterator"""
161
```
162

163
[Combining and Augmenting](./combining.md)
164

165
### Mathematical Operations
166

167
Mathematical computations and operations on iterables.
168

169
```python { .api }
170
def dotproduct(vec1, vec2):
171
    """Compute dot product"""
172

173
def convolve(signal, kernel):
174
    """Compute convolution"""
175

176
def polynomial_eval(coefficients, x):
177
    """Evaluate polynomial at x"""
178

179
def sum_of_squares(iterable):
180
    """Sum the squares of items"""
181

182
def nth_prime(n, *, approximate=False):
183
    """Return nth prime number (0-indexed)"""
184
```
185

186
[Mathematical Operations](./mathematical.md)
187

188
### Combinatorics
189

190
Functions for generating permutations, combinations, and related structures.
191

192
```python { .api }
193
def powerset(iterable):
194
    """Generate powerset of items"""
195

196
def distinct_combinations(iterable, r):
197
    """Combinations of distinct items"""
198

199
def partitions(n):
200
    """Integer partitions of n"""
201

202
def circular_shifts(iterable):
203
    """All circular shifts"""
204
```
205

206
[Combinatorics](./combinatorics.md)
207

208
### Uniqueness and Duplicates
209

210
Functions for handling unique elements and finding duplicates.
211

212
```python { .api }
213
def unique_everseen(iterable, key=None):
214
    """Unique items preserving order"""
215

216
def duplicates_everseen(iterable, key=None):
217
    """Duplicate items preserving order"""
218

219
def all_unique(iterable, key=None):
220
    """Check if all items unique"""
221
```
222

223
[Uniqueness Operations](./uniqueness.md)
224

225
### Summarizing Operations
226

227
Functions that compute summaries and statistics over iterables.
228

229
```python { .api }
230
def ilen(iterable):
231
    """Length of iterable"""
232

233
def quantify(iterable, pred=bool):
234
    """Count matching items"""
235

236
def minmax(iterable, *, default=None, key=None):
237
    """Find min and max in single pass"""
238

239
def all_equal(iterable):
240
    """Check if all elements equal"""
241
```
242

243
[Summarizing Operations](./summarizing.md)
244

245
### Sequence Utilities
246

247
Functions specifically for working with sequences and sequence-like objects.
248

249
```python { .api }
250
def always_iterable(obj, base_type=(str, bytes)):
251
    """Ensure input is iterable"""
252

253
def is_sorted(iterable, *, key=None, reverse=False, strict=False):
254
    """Check if sequence is sorted"""
255

256
def mark_ends(iterable):
257
    """Mark first and last elements"""
258

259
def sort_together(iterables, *, key_list=None, reverse=False):
260
    """Sort multiple sequences together"""
261
```
262

263
[Sequence Utilities](./sequence-utilities.md)
264

265
### Indexing and Position Operations
266

267
Functions for working with indices and positions in sequences.
268

269
```python { .api }
270
def combination_index(element, pool):
271
    """Get index of combination"""
272

273
def nth_combination(iterable, r, index):
274
    """Get combination at index"""
275

276
def permutation_index(element, pool):
277
    """Get index of permutation"""
278

279
def iter_index(iterable, value, *, start=0, stop=None):
280
    """Find all indices of value"""
281
```
282

283
[Indexing Operations](./indexing.md)
284

285
### Random Operations
286

287
Functions for generating random selections and samples.
288

289
```python { .api }
290
def random_product(*iterables, repeat=1):
291
    """Random Cartesian product element"""
292

293
def random_combination(iterable, r):
294
    """Random combination"""
295

296
def sample(iterable, k, *, counts=None):
297
    """Sample k elements"""
298
```
299

300
[Random Operations](./random-operations.md)
301

302
### Iteration Utilities
303

304
Core iteration utilities and helpers for advanced patterns.
305

306
```python { .api }
307
def iterate(func, value):
308
    """Generate sequence by applying function"""
309

310
def tabulate(func, start=0):
311
    """Tabulate function results"""
312

313
def iter_except(func, exception, first=None):
314
    """Iterate until exception"""
315
```
316

317
[Iteration Utilities](./iteration-utilities.md)
318

319
### Special Purpose Classes and Decorators
320

321
Classes and decorators providing specialized functionality.
322

323
```python { .api }
324
class countable:
325
    """Iterator wrapper that tracks items seen"""
326
    def items_seen(self): ...
327

328
def consumer(func):
329
    """Decorator for coroutine consumers"""
330

331
def raise_(exception):
332
    """Utility for raising exceptions in expressions"""
333
```
334

335
[Special Purpose](./special-purpose.md)
336

337
### Comparison and Equality Operations
338

339
Functions for comparing and testing equality between iterables.
340

341
```python { .api }
342
def iequals(*iterables):
343
    """Test if iterables produce same elements"""
344

345
def difference(iterable, *others):
346
    """Elements in first not in others"""
347

348
def before_and_after(predicate, iterable):
349
    """Split at first matching element"""
350
```
351

352
[Comparison Operations](./comparison.md)
353

354
### Advanced Utilities
355

356
Specialized utilities for complex operations.
357

358
```python { .api }
359
def flatten(iterable):
360
    """Flatten one level of nesting"""
361

362
def collapse(iterable, base_type=None, levels=None):
363
    """Deep flattening of nested structures"""
364

365
def map_reduce(iterable, keyfunc, valuefunc=None, reducefunc=None):
366
    """Map-reduce operation"""
367

368
class time_limited:
369
    """Time-limited iteration class"""
370

371
def interleave_randomly(*iterables):
372
    """Randomly interleave multiple iterables"""
373

374
def takewhile_inclusive(predicate, iterable):
375
    """Takewhile including first failing element"""
376

377
def with_iter(context_manager):
378
    """Context-managed iteration"""
379

380
def iter_suppress(iterable, *exceptions):
381
    """Exception suppression during iteration"""
382
```
383

384
[Advanced Utilities](./advanced-utilities.md)
385

386
## Types
387

388
```python { .api }
389
from collections.abc import Iterable, Iterator
390
from typing import TypeVar, Any, Callable, Optional
391

392
T = TypeVar('T')
393
U = TypeVar('U')
394

395
class UnequalIterablesError(ValueError):
396
    """Raised when iterables have unequal lengths"""
397

398
class SequenceView:
399
    """Provides view into sequence with lazy slicing"""
400
    def __init__(self, target): ...
401
    def __getitem__(self, index): ...
402
    def __len__(self): ...
403

404
class bucket:
405
    """Dynamic bucketing of iterable items by key function"""
406
    def __init__(self, iterable, key, validator=None): ...
407
    def __contains__(self, value): ...
408
    def __getitem__(self, value): ...
409

410
class callback_iter:
411
    """Convert callback-based function to iterator"""
412
    def __init__(self, func, callback_kwd='callback', wait_seconds=0.1): ...
413
    def __enter__(self): ...
414
    def __exit__(self, exc_type, exc_value, traceback): ...
415

416
class run_length:
417
    """Run-length encoding and decoding operations"""
418
    @staticmethod
419
    def encode(iterable): ...
420
    @staticmethod
421
    def decode(iterable): ...
422

423
class islice_extended:
424
    """Extended islice with negative index support"""
425
    def __init__(self, iterable, *args): ...
426
    def __getitem__(self, key): ...
427

428
class numeric_range:
429
    """Extended range() for any numeric types"""
430
    def __init__(self, *args): ...
431
    def __contains__(self, value): ...
432
```
433

434
[Utility Classes and Exceptions](./utility-classes.md)