0
# Grouping Operations
1

2
Functions for dividing iterables into chunks, groups, and partitions.
3

4
## Capabilities
5

6
### Basic Chunking
7

8
Break iterables into fixed-size groups.
9

10
```python { .api }
11
def chunked(iterable, n, strict=False):
12
    """
13
    Break iterable into lists of length n.
14
    
15
    Args:
16
        iterable: Input iterable to chunk
17
        n: Size of each chunk
18
        strict: If True, raise ValueError if iterable length not divisible by n
19
        
20
    Returns:
21
        Iterator of lists, each of length n (except possibly the last)
22
    """
23

24
def ichunked(iterable, n):
25
    """
26
    Break iterable into iterators of length n.
27
    
28
    Args:
29
        iterable: Input iterable to chunk
30
        n: Size of each chunk
31
        
32
    Returns:
33
        Iterator of iterators, each yielding up to n items
34
    """
35

36
def batched(iterable, n, *, strict=False):
37
    """
38
    Group items into batches of size n.
39
    
40
    Args:
41
        iterable: Input iterable to batch
42
        n: Batch size
43
        strict: If True, raise ValueError if final batch is incomplete
44
        
45
    Returns:
46
        Iterator of tuples, each of length n (except possibly the last)
47
    """
48
```
49

50
**Usage Examples:**
51

52
```python
53
from more_itertools import chunked, ichunked, batched
54

55
# Basic chunking
56
data = [1, 2, 3, 4, 5, 6, 7, 8, 9]
57
chunks = list(chunked(data, 3))
58
# Result: [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
59

60
# Iterator chunking (memory efficient)
61
for chunk in ichunked(range(1000000), 1000):
62
    process_chunk(list(chunk))
63

64
# Batched processing
65
batches = list(batched('ABCDEFG', 3))
66
# Result: [('A', 'B', 'C'), ('D', 'E', 'F'), ('G',)]
67
```
68

69
### Advanced Chunking
70

71
More sophisticated chunking with constraints and even distribution.
72

73
```python { .api }
74
def chunked_even(iterable, n):
75
    """
76
    Break iterable into n evenly-sized chunks.
77
    
78
    Args:
79
        iterable: Input iterable to chunk
80
        n: Number of chunks to create
81
        
82
    Returns:
83
        Iterator of n iterators with sizes differing by at most 1
84
    """
85

86
def constrained_batches(iterable, max_size, max_count=None, strict=True):
87
    """
88
    Create batches with size and count constraints.
89
    
90
    Args:
91
        iterable: Input iterable to batch
92
        max_size: Maximum size of each batch
93
        max_count: Maximum number of batches (optional)
94
        strict: If True, raise ValueError on constraint violation
95
        
96
    Returns:
97
        Iterator of lists, each satisfying constraints
98
    """
99

100
def sliced(sequence, n, strict=False):
101
    """
102
    Slice sequence into n-length subsequences.
103
    
104
    Args:
105
        sequence: Input sequence to slice
106
        n: Length of each slice
107
        strict: If True, raise ValueError if length not divisible by n
108
        
109
    Returns:
110
        Iterator of sequence slices
111
    """
112
```
113

114
### Distribution and Partitioning
115

116
Distribute items into buckets or partition by criteria.
117

118
```python { .api }
119
def distribute(children, iterable):
120
    """
121
    Distribute items from iterable among children.
122
    
123
    Args:
124
        children: Number of child iterators to create
125
        iterable: Input iterable to distribute
126
        
127
    Returns:
128
        Tuple of children iterators
129
    """
130

131
def divide(n, iterable):
132
    """
133
    Divide iterable into n approximately equal parts.
134
    
135
    Args:
136
        n: Number of parts to create
137
        iterable: Input iterable to divide
138
        
139
    Returns:
140
        Iterator of n iterators
141
    """
142

143
def partition(pred, iterable):
144
    """
145
    Partition iterable based on predicate.
146
    
147
    Args:
148
        pred: Predicate function or None
149
        iterable: Input iterable to partition
150
        
151
    Returns:
152
        Tuple of (false_items, true_items) iterators
153
    """
154

155
def grouper(iterable, n, incomplete='fill', fillvalue=None):
156
    """
157
    Group iterable into fixed-length chunks.
158
    
159
    Args:
160
        iterable: Input iterable to group
161
        n: Size of each group
162
        incomplete: How to handle incomplete groups ('fill', 'strict', 'ignore')
163
        fillvalue: Value to use for padding when incomplete='fill'
164
        
165
    Returns:
166
        Iterator of n-tuples
167
    """
168
```
169

170
### Splitting Operations
171

172
Split iterables at specific points or conditions.
173

174
```python { .api }
175
def split_at(iterable, pred, maxsplit=-1, keep_separator=False):
176
    """
177
    Split iterable at items matching predicate.
178
    
179
    Args:
180
        iterable: Input iterable to split
181
        pred: Predicate function to identify split points
182
        maxsplit: Maximum number of splits (-1 for unlimited)
183
        keep_separator: Whether to keep separator items
184
        
185
    Returns:
186
        Iterator of sub-iterables
187
    """
188

189
def split_before(iterable, pred, maxsplit=-1):
190
    """
191
    Split iterable before items matching predicate.
192
    
193
    Args:
194
        iterable: Input iterable to split
195
        pred: Predicate function
196
        maxsplit: Maximum number of splits
197
        
198
    Returns:
199
        Iterator of sub-iterables
200
    """
201

202
def split_after(iterable, pred, maxsplit=-1):
203
    """
204
    Split iterable after items matching predicate.
205
    
206
    Args:
207
        iterable: Input iterable to split
208
        pred: Predicate function
209
        maxsplit: Maximum number of splits
210
        
211
    Returns:
212
        Iterator of sub-iterables
213
    """
214

215
def split_into(iterable, sizes):
216
    """
217
    Split iterable into groups of specified sizes.
218
    
219
    Args:
220
        iterable: Input iterable to split
221
        sizes: Iterable of group sizes
222
        
223
    Returns:
224
        Iterator of lists with specified sizes
225
    """
226

227
def split_when(iterable, pred, maxsplit=-1):
228
    """
229
    Split iterable when predicate becomes true.
230
    
231
    Args:
232
        iterable: Input iterable to split
233
        pred: Binary predicate function (prev_item, current_item)
234
        maxsplit: Maximum number of splits
235
        
236
    Returns:
237
        Iterator of sub-iterables
238
    """
239
```
240

241
### Grouping by Key
242

243
Group items by key functions or criteria.
244

245
```python { .api }
246
def bucket(iterable, key=None, validator=None):
247
    """
248
    Group items into buckets by key function.
249
    
250
    Args:
251
        iterable: Input iterable to bucket
252
        key: Key function (identity if None)
253
        validator: Function to validate keys
254
        
255
    Returns:
256
        Bucket object with keyed access to groups
257
    """
258

259
def consecutive_groups(iterable, key=None):
260
    """
261
    Group consecutive items that differ by 1.
262
    
263
    Args:
264
        iterable: Input iterable of numbers
265
        key: Key function to extract numeric values
266
        
267
    Returns:
268
        Iterator of iterators, each containing consecutive items
269
    """
270
```
271

272
### Restructuring Operations
273

274
Functions that restructure data organization.
275

276
```python { .api }
277
def unzip(iterable):
278
    """
279
    Reverse zip operation - split sequence of tuples.
280
    
281
    Args:
282
        iterable: Iterable of tuples/sequences
283
        
284
    Returns:
285
        Tuple of iterators, one for each position
286
    """
287

288
def transpose(iterable):
289
    """
290
    Transpose matrix-like iterable.
291
    
292
    Args:
293
        iterable: Iterable of iterables (matrix-like)
294
        
295
    Returns:
296
        Iterator of tuples (transposed rows)
297
    """
298
```