[Python-Dev] Re: Single- vs. Multi-pass iterability

[Tim Peters]

[François Pinard]
> If yes, then, the Library Reference is misleading, at the page:
>
>    http://www.python.org/dev/doc/devel/lib/typeiter.html
>
> when it strongly says that any iterator's __iter__ method is "required".
> I guess this is a possible source of confusion.

This is how Python the language is defined.  The current C Python
implementation doesn't enforce it, and you may be able to get away with
defining an iterator that doesn't supply an __iter__ method in some contexts
under the current C implementation.  If you do, though, you're breaking the
rules, and there's no guarantee your code will continue to work.

> The context does not make it clear that the iterator's __iter__ method is
> *only* required whenever one *also* wants to use an iterator as an
> iterable.

That's not how the iteration protocol is defined, and isn't how it should be
defined either.  Requiring *some* method with a reserved name is an aid to
introspection, lest it become impossible to distinguish, say, an iterator
from an instance of a doubly-linked list node class that just happens to
supply methods named .prev() and .next() for an unrelated purpose.

> Better would be to describe __iter__ only once, the first time through,
> saying everything there that has to be said, and only retain for iterators
> the requirement of having a `next()' method.  We should describe
> the truth.

Except that iterators are required to have an __iter__ method:  this is a
matter of definition, not just of reverse-engineering the minimum you can
get away with under the current implementation in assorted contexts.  You'll
discover this hard way the first time you try to pass an iterator without an
__iter__ method to a routine you didn't write that says it accepts any
iterable object as an argument.  Such a routine is entitled-- by the
documented requirements --to rely on its argument responding sensibly to an
__iter__ message.

> P.S. - Also, I do not understand the tiny bit about the `in'
> statement in the above page.  Has `in' ever been a statement?

I figure you're talking about this:

    ... to be used with the for and in statements

The tail end of that is indeed worded poorly; 'in' isn't a statement.

> If it refers to the comparison operator `in',

Yes, that's the intent.

> then has it any special properties when used with iterators?

In

    x in y

y can be any iterable object.  As an extreme example,

    if "error\n" in file('msgs'):