diff --git a/README.rst b/README.rst index 9f61fcb1..f1552317 100644 --- a/README.rst +++ b/README.rst @@ -1,23 +1,53 @@ -============== 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 -I love itertools; it's one of the most beautiful, composable standard libs. -Whenever I have an iteration problem, there's almost always an itertools -routine that fits it perfectly. Sometimes, however, neither itertools nor the -recipes included in its docs do quite what I need. +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. + +Getting started +=============== + +To get started, install the library with `pip `_: + +.. code-block:: shell + + pip install more-itertools + +The recipes from the `itertools docs `_ +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 spy, chunked + >>> iterable = [0, 1, 2, 3, 4, 5, 6, 7] + >>> head, iterable = spy(iterable, n=2) + >>> head + [0, 1] + >>> list(chunked(iterable, 3)) + [[0, 1, 2], [3, 4, 5], [6, 7]] + +For the full listing of functions, see the API documentation at `more-itertools.readthedocs.io `_. -Here I've collected several routines I've reached for but not found. Since -they are deceptively tricky to get right, I've wrapped them up into a library. -We've also included implementations of the recipes from the itertools -documentation. Enjoy! Any additions are welcome; just file a pull request. +Development +=========== +``more-itertools`` is maintained by `@erikrose `_ +and `@bbayles `_, with help from `many others `_. +If you have a problem or suggestion, please file a bug or pull request in this +repository - thanks for contributing! -Full Documentation -================== -Please see https://more-itertools.readthedocs.io/en/latest/api.html for the -list of routines.