Document when to use izip_longest().

1 files changed, 7 insertions, 16 deletions

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index e797aab..419e8e5 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -269,22 +269,13 @@ loops that truncate the stream.
       When no iterables are specified, returns a zero length iterator instead of
       raising a :exc:`TypeError` exception.
 
-   Note, the left-to-right evaluation order of the iterables is guaranteed. This
-   makes possible an idiom for clustering a data series into n-length groups using
-   ``izip(*[iter(s)]*n)``.  For data that doesn't fit n-length groups exactly, the
-   last tuple can be pre-padded with fill values using ``izip(*[chain(s,
-   [None]*(n-1))]*n)``.
-
-   Note, when :func:`izip` is used with unequal length inputs, subsequent
-   iteration over the longer iterables cannot reliably be continued after
-   :func:`izip` terminates.  Potentially, up to one entry will be missing from
-   each of the left-over iterables. This occurs because a value is fetched from
-   each iterator in turn, but the process ends when one of the iterators
-   terminates.  This leaves the last fetched values in limbo (they cannot be
-   returned in a final, incomplete tuple and they are cannot be pushed back into
-   the iterator for retrieval with ``it.next()``).  In general, :func:`izip`
-   should only be used with unequal length inputs when you don't care about
-   trailing, unmatched values from the longer iterables.
+   The left-to-right evaluation order of the iterables is guaranteed. This
+   makes possible an idiom for clustering a data series into n-length groups
+   using ``izip(*[iter(s)]*n)``.
+
+   :func:`izip` should only be used with unequal length inputs when you don't
+   care about trailing, unmatched values from the longer iterables.  If those
+   values are important, use :func:`izip_longest` instead.
 
 
 .. function:: izip_longest(*iterables[, fillvalue])