[issue45856] [doc] map() documentation ambiguous about consumption order

[Thibaut Horel]

New submission from Thibaut Horel <thibaut.horel at gmail.com>:

In cases where multiple iterables are passed to the built-in function map(), the documentation is ambiguous about the order in which they are consumed [1]. Although the order of evaluation of function arguments is documented to be left-to-right in general [2], this does not necessarily imply that the __next__() functions of the underlying iterators are called from left to right *before* passing the returned elements to the function being mapped. This is particularly relevant when the same iterator is passed multiple times, or when there are side effects to consuming the iterables.

I suggest adding the sentence “The iterables are consumed in left-to-right order at each iteration.”, similar to how it is done for the function zip() [3]. Furthermore, I think providing the following (roughly) equivalent implementation in pure Python might be illuminating:

    def map(function, *iterables):
        iterators = tuple(iter(it) for it in iterables)
        while True:
            try:
                args = [next(it) for it in iterators]
            except StopIteration:
                break
            yield func(*args)


Finally, the following example could be added. “This makes it possible to apply a function to consecutive groups of elements from the same iterator by passing it multiple times to `map`:

    from itertools import count

    ctr = count()
    # map(func, ctr, ctr) -> func(0, 1), func(2, 3), ...
 
”

I am happy to submit a pull request once we reach a consensus on the formulation.

[1] https://docs.python.org/3/library/functions.html#map
[2] https://docs.python.org/3/reference/expressions.html#evaluation-order
[3] https://docs.python.org/3/library/functions.html#zip

----------
assignee: docs at python
components: Documentation
messages: 406693
nosy: docs at python, eric.araujo, ezio.melotti, mdk, thibaut.horel, willingc
priority: normal
severity: normal
status: open
title: [doc] map() documentation ambiguous about consumption order
type: enhancement
versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue45856>
_______________________________________