classification
Title: Change example of itertools.product
Type: Stage: resolved
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mark.Bell, docs@python, rhettinger
Priority: normal Keywords:

Created on 2020-02-25 23:53 by Mark.Bell, last changed 2020-02-26 07:24 by rhettinger. This issue is now closed.

Messages (2)
msg362672 - (view) Author: Mark Bell (Mark.Bell) * Date: 2020-02-25 23:53
The documentation for itertools.product at: https://docs.python.org/3/library/itertools.html#itertools.product
currently says that:

    For example, product(A, B) returns the same as ((x,y) for x in A for y in B)

While this is broadly correct, since product first converts its arguments to tuples, this is not true if A or B are infinite iterables. For example, when A = itertools.count() and B = range(2) then the former runs forever using infinite memory, whereas the latter returns the lazy generator immediately for use.

Would it be clearer / more correct to instead say:

    For example, product(A, B) returns the same as ((x,y) for x in tuple(A) for y in tuple(B))
msg362685 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-02-26 07:24
Thanks for the suggestion, but I will decline.  The existing wording communicates the intended mental relationship between the product() and nested for-loop.  IMO, the proposed change obfuscates that main point.  

The details of how product works are communicated in the pure python equivalent block that follows.  That code clearly shows that each pool is first converted to a tuple.  So, your point about infinite iterators is already covered and doesn't need to be said twice.

We could replace "the same as" with "roughly the same as", but I don't really think that would be an improvement.
History
Date User Action Args
2020-02-26 07:24:36rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg362685

stage: resolved
2020-02-26 02:30:59xtreaksetnosy: + rhettinger
2020-02-25 23:53:56Mark.Bellcreate