[issue10029] "Equivalent to" code for zip is wrong in Python 3

[Alexander Belopolsky]

Alexander Belopolsky <belopolsky at users.sourceforge.net> added the comment:

As Daniel pointed out, the "equivalent to" code in builtins section comes from 2.x itertools documentation where and equivalent generator definition is presented for each function.  While these definitions are helpful when used for documenting a module oriented towards more advanced users, I doubt that exposing novices who are looking up builtins to the yield keyword and generators is a good idea.  The zip() example is particularly problematic.  Conceptually, zip is a very simple function, but the "equivalent to" code is not easy to decipher.   The reliance on StopIteration exception escaping from map to break out of the infinite loop is clever, but not obvious.  Moreover, as this bug demonstrates, this trick relies on subtle details that changed in 3.x.

I suggest removing the "equivalent to" code from the zip section and replacing it with an example showing how to use zip with a for loop similar to the example illustrating enumerate.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10029>
_______________________________________