If yes, then, the Library Reference is misleading, at the page:
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?
x in y
y can be any iterable object. As an extreme example,
if "error\n" in file('msgs'):