1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
|
Metadata-Version: 2.1
Name: more-itertools
Version: 5.0.0
Summary: More routines for operating on iterables, beyond itertools
Home-page: https://github.com/erikrose/more-itertools
Author: Erik Rose
Author-email: erikrose@grinchcentral.com
License: MIT
Keywords: itertools,iterator,iteration,filter,peek,peekable,collate,chunk,chunked
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: six (<2.0.0,>=1.0.0)
==============
More Itertools
==============
.. image:: https://coveralls.io/repos/github/erikrose/more-itertools/badge.svg?branch=master
:target: https://coveralls.io/github/erikrose/more-itertools?branch=master
Python's ``itertools`` library is a gem - you can compose elegant solutions
for a variety of problems with the functions it provides. In ``more-itertools``
we collect additional building blocks, recipes, and routines for working with
Python iterables.
----
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Grouping | `chunked <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.chunked>`_, |
| | `sliced <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.sliced>`_, |
| | `distribute <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.distribute>`_, |
| | `divide <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.divide>`_, |
| | `split_at <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.split_at>`_, |
| | `split_before <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.split_before>`_, |
| | `split_after <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.split_after>`_, |
| | `bucket <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.bucket>`_, |
| | `grouper <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.grouper>`_, |
| | `partition <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.partition>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Lookahead and lookback | `spy <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.spy>`_, |
| | `peekable <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.peekable>`_, |
| | `seekable <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.seekable>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Windowing | `windowed <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.windowed>`_, |
| | `stagger <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.stagger>`_, |
| | `pairwise <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.pairwise>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Augmenting | `count_cycle <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.count_cycle>`_, |
| | `intersperse <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.intersperse>`_, |
| | `padded <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.padded>`_, |
| | `adjacent <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.adjacent>`_, |
| | `groupby_transform <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.groupby_transform>`_, |
| | `padnone <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.padnone>`_, |
| | `ncycles <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.ncycles>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Combining | `collapse <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.collapse>`_, |
| | `sort_together <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.sort_together>`_, |
| | `interleave <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.interleave>`_, |
| | `interleave_longest <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.interleave_longest>`_, |
| | `collate <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.collate>`_, |
| | `zip_offset <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.zip_offset>`_, |
| | `dotproduct <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.dotproduct>`_, |
| | `flatten <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.flatten>`_, |
| | `roundrobin <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.roundrobin>`_, |
| | `prepend <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.prepend>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Summarizing | `ilen <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.ilen>`_, |
| | `first <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.first>`_, |
| | `last <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.last>`_, |
| | `one <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.one>`_, |
| | `unique_to_each <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.unique_to_each>`_, |
| | `locate <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.locate>`_, |
| | `rlocate <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.rlocate>`_, |
| | `consecutive_groups <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.consecutive_groups>`_, |
| | `exactly_n <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.exactly_n>`_, |
| | `run_length <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.run_length>`_, |
| | `map_reduce <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.map_reduce>`_, |
| | `all_equal <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.all_equal>`_, |
| | `first_true <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.first_true>`_, |
| | `nth <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth>`_, |
| | `quantify <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.quantify>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Selecting | `islice_extended <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.islice_extended>`_, |
| | `strip <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.strip>`_, |
| | `lstrip <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.lstrip>`_, |
| | `rstrip <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.rstrip>`_, |
| | `take <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.take>`_, |
| | `tail <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.tail>`_, |
| | `unique_everseen <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertoo ls.unique_everseen>`_, |
| | `unique_justseen <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.unique_justseen>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Combinatorics | `distinct_permutations <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.distinct_permutations>`_, |
| | `circular_shifts <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.circular_shifts>`_, |
| | `powerset <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.powerset>`_, |
| | `random_product <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.random_product>`_, |
| | `random_permutation <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.random_permutation>`_, |
| | `random_combination <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.random_combination>`_, |
| | `random_combination_with_replacement <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.random_combination_with_replacement>`_, |
| | `nth_combination <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth_combination>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Wrapping | `always_iterable <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_iterable>`_, |
| | `consumer <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.consumer>`_, |
| | `with_iter <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.with_iter>`_, |
| | `iter_except <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.iter_except>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Others | `replace <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.replace>`_, |
| | `numeric_range <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.numeric_range>`_, |
| | `always_reversible <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_reversible>`_, |
| | `side_effect <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.side_effect>`_, |
| | `iterate <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.iterate>`_, |
| | `difference <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.difference>`_, |
| | `make_decorator <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.make_decorator>`_, |
| | `SequenceView <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.SequenceView>`_, |
| | `consume <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.consume>`_, |
| | `accumulate <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.accumulate>`_, |
| | `tabulate <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.tabulate>`_, |
| | `repeatfunc <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.repeatfunc>`_ |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Getting started
===============
To get started, install the library with `pip <https://pip.pypa.io/en/stable/>`_:
.. code-block:: shell
pip install more-itertools
The recipes from the `itertools docs <https://docs.python.org/3/library/itertools.html#itertools-recipes>`_
are included in the top-level package:
.. code-block:: python
>>> from more_itertools import flatten
>>> iterable = [(0, 1), (2, 3)]
>>> list(flatten(iterable))
[0, 1, 2, 3]
Several new recipes are available as well:
.. code-block:: python
>>> from more_itertools import chunked
>>> iterable = [0, 1, 2, 3, 4, 5, 6, 7, 8]
>>> list(chunked(iterable, 3))
[[0, 1, 2], [3, 4, 5], [6, 7, 8]]
>>> from more_itertools import spy
>>> iterable = (x * x for x in range(1, 6))
>>> head, iterable = spy(iterable, n=3)
>>> list(head)
[1, 4, 9]
>>> list(iterable)
[1, 4, 9, 16, 25]
For the full listing of functions, see the `API documentation <https://more-itertools.readthedocs.io/en/latest/api.html>`_.
Development
===========
``more-itertools`` is maintained by `@erikrose <https://github.com/erikrose>`_
and `@bbayles <https://github.com/bbayles>`_, with help from `many others <https://github.com/erikrose/more-itertools/graphs/contributors>`_.
If you have a problem or suggestion, please file a bug or pull request in this
repository. Thanks for contributing!
Version History
===============
5.0.0
-----
* New itertools:
* split_into (thanks to rovyko)
* unzip (thanks to bmintz)
* substrings (thanks to pylang)
* Changes to existing itertools:
* ilen was optimized a bit (thanks to MSeifert04, achampion, and bmintz)
* first_true now returns ``None`` by default. This is the reason for the major version bump - see below. (thanks to sk and OJFord)
* Other changes:
* Some code for old Python versions was removed (thanks to hugovk)
* Some documentation mistakes were corrected (thanks to belm0 and hugovk)
* Tests now run properly on 32-bit versions of Python (thanks to Millak)
* Newer versions of CPython and PyPy are now tested against
The major version update is due to the change in the default return value of
first_true. It's now ``None``.
.. code-block:: python
>>> from more_itertools import first_true
>>> iterable = [0, '', False, [], ()] # All these are False
>>> answer = first_true(iterable)
>>> print(answer)
None
4.3.0
-----
* New itertools:
* last (thanks to tmshn)
* replace (thanks to pylang)
* rlocate (thanks to jferard and pylang)
* Improvements to existing itertools:
* locate can now search for multiple items
* Other changes:
* The docs now include a nice table of tools (thanks MSeifert04)
4.2.0
-----
* New itertools:
* map_reduce (thanks to pylang)
* prepend (from the `Python 3.7 docs <https://docs.python.org/3.7/library/itertools.html#itertools-recipes>`_)
* Improvements to existing itertools:
* bucket now complies with PEP 479 (thanks to irmen)
* Other changes:
* Python 3.7 is now supported (thanks to irmen)
* Python 3.3 is no longer supported
* The test suite no longer requires third-party modules to run
* The API docs now include links to source code
4.1.0
-----
* New itertools:
* split_at (thanks to michael-celani)
* circular_shifts (thanks to hiqua)
* make_decorator - see the blog post `Yo, I heard you like decorators <https://sites.google.com/site/bbayles/index/decorator_factory>`_
for a tour (thanks to pylang)
* always_reversible (thanks to michael-celani)
* nth_combination (from the `Python 3.7 docs <https://docs.python.org/3.7/library/itertools.html#itertools-recipes>`_)
* Improvements to existing itertools:
* seekable now has an ``elements`` method to return cached items.
* The performance tradeoffs between roundrobin and
interleave_longest are now documented (thanks michael-celani,
pylang, and MSeifert04)
4.0.1
-----
* No code changes - this release fixes how the docs display on PyPI.
4.0.0
-----
* New itertools:
* consecutive_groups (Based on the example in the `Python 2.4 docs <https://docs.python.org/release/2.4.4/lib/itertools-example.html>`_)
* seekable (If you're looking for how to "reset" an iterator,
you're in luck!)
* exactly_n (thanks to michael-celani)
* run_length.encode and run_length.decode
* difference
* Improvements to existing itertools:
* The number of items between filler elements in intersperse can
now be specified (thanks to pylang)
* distinct_permutations and peekable got some minor
adjustments (thanks to MSeifert04)
* always_iterable now returns an iterator object. It also now
allows different types to be considered iterable (thanks to jaraco)
* bucket can now limit the keys it stores in memory
* one now allows for custom exceptions (thanks to kalekundert)
* Other changes:
* A few typos were fixed (thanks to EdwardBetts)
* All tests can now be run with ``python setup.py test``
The major version update is due to the change in the return value of always_iterable.
It now always returns iterator objects:
.. code-block:: python
>>> from more_itertools import always_iterable
# Non-iterable objects are wrapped with iter(tuple(obj))
>>> always_iterable(12345)
<tuple_iterator object at 0x7fb24c9488d0>
>>> list(always_iterable(12345))
[12345]
# Iterable objects are wrapped with iter()
>>> always_iterable([1, 2, 3, 4, 5])
<list_iterator object at 0x7fb24c948c50>
3.2.0
-----
* New itertools:
* lstrip, rstrip, and strip
(thanks to MSeifert04 and pylang)
* islice_extended
* Improvements to existing itertools:
* Some bugs with slicing peekable-wrapped iterables were fixed
3.1.0
-----
* New itertools:
* numeric_range (Thanks to BebeSparkelSparkel and MSeifert04)
* count_cycle (Thanks to BebeSparkelSparkel)
* locate (Thanks to pylang and MSeifert04)
* Improvements to existing itertools:
* A few itertools are now slightly faster due to some function
optimizations. (Thanks to MSeifert04)
* The docs have been substantially revised with installation notes,
categories for library functions, links, and more. (Thanks to pylang)
3.0.0
-----
* Removed itertools:
* ``context`` has been removed due to a design flaw - see below for
replacement options. (thanks to NeilGirdhar)
* Improvements to existing itertools:
* ``side_effect`` now supports ``before`` and ``after`` keyword
arguments. (Thanks to yardsale8)
* PyPy and PyPy3 are now supported.
The major version change is due to the removal of the ``context`` function.
Replace it with standard ``with`` statement context management:
.. code-block:: python
# Don't use context() anymore
file_obj = StringIO()
consume(print(x, file=f) for f in context(file_obj) for x in u'123')
# Use a with statement instead
file_obj = StringIO()
with file_obj as f:
consume(print(x, file=f) for x in u'123')
2.6.0
-----
* New itertools:
* ``adjacent`` and ``groupby_transform`` (Thanks to diazona)
* ``always_iterable`` (Thanks to jaraco)
* (Removed in 3.0.0) ``context`` (Thanks to yardsale8)
* ``divide`` (Thanks to mozbhearsum)
* Improvements to existing itertools:
* ``ilen`` is now slightly faster. (Thanks to wbolster)
* ``peekable`` can now prepend items to an iterable. (Thanks to diazona)
2.5.0
-----
* New itertools:
* ``distribute`` (Thanks to mozbhearsum and coady)
* ``sort_together`` (Thanks to clintval)
* ``stagger`` and ``zip_offset`` (Thanks to joshbode)
* ``padded``
* Improvements to existing itertools:
* ``peekable`` now handles negative indexes and slices with negative
components properly.
* ``intersperse`` is now slightly faster. (Thanks to pylang)
* ``windowed`` now accepts a ``step`` keyword argument.
(Thanks to pylang)
* Python 3.6 is now supported.
2.4.1
-----
* Move docs 100% to readthedocs.io.
2.4
-----
* New itertools:
* ``accumulate``, ``all_equal``, ``first_true``, ``partition``, and
``tail`` from the itertools documentation.
* ``bucket`` (Thanks to Rosuav and cvrebert)
* ``collapse`` (Thanks to abarnet)
* ``interleave`` and ``interleave_longest`` (Thanks to abarnet)
* ``side_effect`` (Thanks to nvie)
* ``sliced`` (Thanks to j4mie and coady)
* ``split_before`` and ``split_after`` (Thanks to astronouth7303)
* ``spy`` (Thanks to themiurgo and mathieulongtin)
* Improvements to existing itertools:
* ``chunked`` is now simpler and more friendly to garbage collection.
(Contributed by coady, with thanks to piskvorky)
* ``collate`` now delegates to ``heapq.merge`` when possible.
(Thanks to kmike and julianpistorius)
* ``peekable``-wrapped iterables are now indexable and sliceable.
Iterating through ``peekable``-wrapped iterables is also faster.
* ``one`` and ``unique_to_each`` have been simplified.
(Thanks to coady)
2.3
-----
* Added ``one`` from ``jaraco.util.itertools``. (Thanks, jaraco!)
* Added ``distinct_permutations`` and ``unique_to_each``. (Contributed by
bbayles)
* Added ``windowed``. (Contributed by bbayles, with thanks to buchanae,
jaraco, and abarnert)
* Simplified the implementation of ``chunked``. (Thanks, nvie!)
* Python 3.5 is now supported. Python 2.6 is no longer supported.
* Python 3 is now supported directly; there is no 2to3 step.
2.2
-----
* Added ``iterate`` and ``with_iter``. (Thanks, abarnert!)
2.1
-----
* Added (tested!) implementations of the recipes from the itertools
documentation. (Thanks, Chris Lonnen!)
* Added ``ilen``. (Thanks for the inspiration, Matt Basta!)
2.0
-----
* ``chunked`` now returns lists rather than tuples. After all, they're
homogeneous. This slightly backward-incompatible change is the reason for
the major version bump.
* Added ``@consumer``.
* Improved test machinery.
1.1
-----
* Added ``first`` function.
* Added Python 3 support.
* Added a default arg to ``peekable.peek()``.
* Noted how to easily test whether a peekable iterator is exhausted.
* Rewrote documentation.
1.0
-----
* Initial release, with ``collate``, ``peekable``, and ``chunked``. Could
really use better docs.
|
