more-itertools

============== More Itertools

.. image:: https://readthedocs.org/projects/more-itertools/badge/?version=latest :target: https://more-itertools.readthedocs.io/en/stable/

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>, | | | ichunked <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.ichunked>, | | | chunked_even <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.chunked_even>, | | | sliced <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.sliced>, | | | constrained_batches <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.constrained_batches>, | | | 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>, | | | split_into <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.split_into>, | | | split_when <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.split_when>, | | | bucket <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.bucket>, | | | unzip <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.unzip>, | | | batched <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.batched>, | | | 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>, | | | transpose <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.transpose> | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 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>, | | | substrings <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.substrings>, | | | substrings_indexes <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.substrings_indexes>, | | | stagger <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.stagger>, | | | windowed_complete <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.windowed_complete>, | | | pairwise <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.pairwise>, | | | triplewise <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.triplewise>, | | | sliding_window <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.sliding_window>, | | | subslices <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.subslices>_ | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 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>, | | | repeat_each <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.repeat_each>, | | | mark_ends <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.mark_ends>, | | | repeat_last <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.repeat_last>, | | | 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>, | | | pad_none <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.pad_none>, | | | 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>, | | | interleave_evenly <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.interleave_evenly>, | | | zip_offset <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.zip_offset>, | | | zip_equal <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.zip_equal>, | | | zip_broadcast <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.zip_broadcast>, | | | 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>, | | | value_chain <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.value_chain>, | | | partial_product <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.partial_product>_ | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Summarizing | ilen <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.ilen>, | | | unique_to_each <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.unique_to_each>, | | | sample <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.sample>, | | | consecutive_groups <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.consecutive_groups>, | | | 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>, | | | join_mappings <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.join_mappings>, | | | exactly_n <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.exactly_n>, | | | is_sorted <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.is_sorted>, | | | all_equal <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.all_equal>, | | | all_unique <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.all_unique>, | | | minmax <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.minmax>, | | | first_true <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.first_true>, | | | quantify <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.quantify>, | | | iequals <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.iequals>_ | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Selecting | islice_extended <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.islice_extended>, | | | 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>, | | | only <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.only>, | | | strictly_n <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.strictly_n>, | | | 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>, | | | filter_except <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.filter_except>, | | | map_except <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.map_except>, | | | filter_map <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.filter_map>, | | | iter_suppress <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.iter_suppress>, | | | nth_or_last <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth_or_last>, | | | unique_in_window <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.unique_in_window>, | | | before_and_after <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.before_and_after>, | | | nth <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth>, | | | 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_itertools.unique_everseen>, | | | unique_justseen <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.unique_justseen>, | | | unique <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.unique>, | | | duplicates_everseen <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.duplicates_everseen>, | | | duplicates_justseen <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.duplicates_justseen>, | | | classify_unique <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.classify_unique>, | | | longest_common_prefix <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.longest_common_prefix>, | | | takewhile_inclusive <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.takewhile_inclusive>_ | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Math | dft <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.dft>, | | | idft <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.idft>, | | | convolve <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.convolve>, | | | dotproduct <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.dotproduct>, | | | factor <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.factor>, | | | matmul <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.matmul>, | | | polynomial_from_roots <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.polynomial_from_roots>, | | | polynomial_derivative <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.polynomial_derivative>, | | | polynomial_eval <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.polynomial_eval>, | | | sieve <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.sieve>, | | | sum_of_squares <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.sum_of_squares>, | | | totient <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.totient> | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Combinatorics | distinct_permutations <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.distinct_permutations>, | | | distinct_combinations <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.distinct_combinations>, | | | circular_shifts <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.circular_shifts>, | | | partitions <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.partitions>, | | | set_partitions <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.set_partitions>, | | | product_index <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.product_index>, | | | combination_index <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.combination_index>, | | | permutation_index <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.permutation_index>, | | | combination_with_replacement_index <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.combination_with_replacement_index>, | | | gray_product <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.gray_product>, | | | outer_product <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.outer_product>, | | | powerset <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.powerset>, | | | powerset_of_sets <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.powerset_of_sets>, | | | 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_product <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth_product>, | | | nth_permutation <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth_permutation>, | | | nth_combination <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth_combination>, | | | nth_combination_with_replacement <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.nth_combination_with_replacement>_ | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Wrapping | always_iterable <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_iterable>, | | | always_reversible <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_reversible>, | | | countable <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.countable>, | | | 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 | 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>, | | | 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>, | | | 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>, | | | time_limited <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.time_limited>, | | | map_if <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.map_if>, | | | iter_index <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.iter_index>, | | | consume <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.consume>, | | | 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>, | | | reshape <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.reshape> | | | doublestarmap <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.doublestarmap>_ | +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

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/stable/api.html>_.

Links elsewhere

Blog posts about more-itertools:

• Yo, I heard you like decorators <https://www.bbayles.com/index/decorator_factory>__
• Tour of Python Itertools <https://martinheinz.dev/blog/16>__ (Alternate <https://dev.to/martinheinz/tour-of-python-itertools-4122>__)
• Real-World Python More Itertools <https://python.plainenglish.io/real-world-more-itertools-gideons-blog-a3901c607550>_

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/more-itertools/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

The version history can be found in documentation <https://more-itertools.readthedocs.io/en/stable/versions.html>_.