New submission from Thibaut Horel <thibaut.ho...@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@python
components: Documentation
messages: 406693
nosy: docs@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 <rep...@bugs.python.org>
<https://bugs.python.org/issue45856>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
