classification
Title: reduce takes iterable, not just sequence
Type: enhancement Stage:
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Stefan Pochmann, docs@python, ncoghlan, rhettinger, serhiy.storchaka, terry.reedy
Priority: normal Keywords:

Created on 2017-07-30 21:06 by Stefan Pochmann, last changed 2017-08-09 07:38 by serhiy.storchaka.

Messages (5)
msg299520 - (view) Author: Stefan Pochmann (Stefan Pochmann) Date: 2017-07-30 21:06
functools.reduce has a parameter called "iterable" and it only needs to be an iterable, not a sequence.

The paragraph documenting it says "sequence" instead of "iterable" six times:
https://docs.python.org/3/library/functools.html#functools.reduce

The help shown by executing "help(functools.reduce)" in Python additionally actually names the parameter "sequence" in the signature.
msg299768 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-08-05 02:58
Serhiy, given that the parameters of reduce are currently positional only (by experiment, it has not gotten the C.A. treatment yet), can 'sequence' in the signature in the docstring be changes to 'iterable'?
msg299771 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-08-05 04:26
Yes, I think it can. But be aware that "sequence" is used not only in the signature, but in following description.

The term "sequence" in the documentation and the docstring looks to me like a synonym of "iterable", not a reference to collections.abc.Sequence. I don't know how the wording can be improved. Maybe looking at the documentation of builtins filter, map, zip, and itertools functions can help.
msg299825 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-08-07 05:20
Checking older versions of the docs, it looks like we simply haven't reworded those docs since Python 2.0 (when the "list" of the 1.5 docs became "sequence" for 2.0).

So I think the most appropriate resolution here would be to replace the current use of "sequence" with "iterable" in both the code and the documentation.
msg299974 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-08-09 07:38
The term "sequence" also is used in the docstring of itertools.starmap() (actually an iterable is accepted).
History
Date User Action Args
2017-08-09 07:38:57serhiy.storchakasetmessages: + msg299974
2017-08-07 05:20:01ncoghlansetmessages: + msg299825
2017-08-05 04:26:33serhiy.storchakasetnosy: + rhettinger, ncoghlan
messages: + msg299771
2017-08-05 02:58:12terry.reedysetnosy: + terry.reedy, serhiy.storchaka
messages: + msg299768
2017-07-30 21:06:27Stefan Pochmanncreate