itertools doc example "consume"

[Ian Kelly]

On Fri, Mar 8, 2013 at 1:28 PM, Skip Montanaro <skip at pobox.com> wrote:
> I've never really used itertools before.  While trying to figure out
> how to break a list up into equal pieces, I came across the consume
> function in the examples here:
>
> http://docs.python.org/2/library/itertools.html
>
> It seems to me that it should return whatever it consumes from the
> list.  I thought you would call it like this:
>
>     for chunk in consume(range(30), 5):
>         print chunk
>
> and see it print something like
>
> [0, 1, 2, 3, 4]
> [5, 6, 7, 8, 9]
> ...
> [25, 26, 27, 28, 29]

That's what the 'grouper' recipe does.  The 'consume' recipe is just
for removing unwanted things from the front of an iterator.

> If I call it like this:
>
> lst = range(30)
> consume(lst, 5)
>
> it doesn't actually consume anything from lst.  Am I missing
> something, or is that example missing a return or yield statement?

Depending on your Python version lst is either a range object or a
list, neither of which is an iterator.  If you pass to consume an
iterable object that is not an iterator, it will implicitly obtain an
iterator for it, consume from the iterator, and then discard the
iterator, with no effect on the original object.

In general the itertools functions will work equally well on iterators
and other iterables, but consume is special in that what it does is
only relevant to iterators.