Add clarification to zip's documentation

Documentation

Using zip on iterators of variable length results in a behavior that I believe would benefit from some additional clarification in the documentation. Take the following example:

>>> a = list(range(3))
>>> b = iter(range(100))
>>> list(zip(a, b))
[(0, 0), (1, 1), (2, 2)]
>>> list(zip(a, b))
[(0, 3), (1, 4), (2, 5)]

This is expected behavior as zip simply stops at the end of the shortest iterable, in this case a. When calling zip again a is restarted whilst b carries on from 3.

The unexpected behavior comes about when we swap the arguments putting the longer iterator as the first argument.

>>> a = list(range(3))
>>> b = iter(range(100))
>>> list(zip(b, a))
[(0, 0), (1, 1), (2, 2)]
>>> list(zip(b, a))
[(4, 0), (5, 1), (6, 2)]

Rather than carrying on from 3 like in the previous example we get a 4. I understand this is due to b being consumed during the zip and there is no way to know which iterator will yield a StopIteration first and so this is the intended behavior.

It may be beneficial to highlight this edge case in the documentation and make the recommendation to try and put the shortest iterator first.

Inizia dalla documentazione della funzione integrata zip di Python e verifica come descrive l’arresto all’iterabile più corto. Chiarisci che gli iteratori possono essere consumati prima che venga raggiunto StopIteration e documenta l’edge case mostrato relativo all’ordine degli argomenti, inclusa la raccomandazione di mettere per primo l’iteratore più corto. Il lavoro è completato quando il comportamento e la raccomandazione sono chiari nella documentazione di zip.