classification
Title: functools.reduce signature uses `iterable`, documentation should use the same term
Type: enhancement Stage:
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bignose, docs@python, ncoghlan, rhettinger, terry.reedy, vreuter, xtreak
Priority: normal Keywords:

Created on 2018-03-24 00:05 by vreuter, last changed 2019-03-24 16:26 by xtreak.

Pull Requests
URL Status Linked Edit
PR 6204 closed vreuter, 2018-03-24 00:05
Messages (6)
msg314344 - (view) Author: Vince Reuter (vreuter) * Date: 2018-03-24 00:05
The signature for functools.reduce correctly refers to the collection parameter as an iterable, but the docstring refers to it as "sequence," which the input need not be and does not match the parameter name despite being italicized.
msg314713 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-03-30 20:33
inspect.signature(functools.reduce) raises, so I presume you mean the header for the reduce entry at
https://docs.python.org/3/library/functools.html#functools.reduce.  The first line of the docstring, functools.reduce.__doc__, also displayed by help(functools.reduce) has an old version of the signature, which disagrees also on the 3rd parameter name. 
doc header: functools.reduce(function, iterable[, initializer])
.__doc__:   reduce(function, sequence[, initial]) -> value

The current PR only touches the body of the doc entry, not what we call the docstring.  It replaces 'sequence' with 'iterable'.

Functools does not have a Python-coded backup for the C-coded reduce, which only accepts arguments by position.  I have not looked at the C code, whose names are not accessible from Python.  The doc and docstring should match, and should use the parameter names we would want to use of args were ever passed by name.  So I think the docstring (in the C code) should be changed to match the doc.

There should really be a '/,' to indicate that args must be passed by position, or do we only use that in ArgClinic signatures (which show up in help output)?
msg314763 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-04-01 06:38
+1 for switching over to `iterable` in the reduce docstring.

As a possible enhancement for 3.8+ only, it would be reasonable to start converting functools over to Argument Clinic in order to improve the introspection support. (Note that only some APIs could be converted though, as others have more complex signatures that AC doesn't yet support: https://bugs.python.org/issue20291)
msg330841 - (view) Author: Ben Finney (bignose) Date: 2018-12-01 03:48
The library documentation (e.g. file:///usr/share/doc/python3/html/library/functools.html#functools.reduce ) also has this dissonance:

>  functools.reduce(`function`, `iterable` [, `initializer` ])
>
>    Apply function of two arguments cumulatively to the items of `sequence`, from left to right, so as to reduce the sequence to a single value.
msg330842 - (view) Author: Ben Finney (bignose) Date: 2018-12-01 03:49
Hah, sorry to use a local-filesystem URL. (Hooray for locally-installed developer documentation!)

The same section is online at https://docs.python.org/3/library/functools.html#functools.reduce .
msg338740 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-03-24 16:26
The original report for documentation seems to have been fixed with https://github.com/python/cpython/pull/9634 and the linked PR is closed with no changes to be merged. So I would propose closing if this was only with respect to changing documentation and not docstring. As an additional note issue32321 added a python fallback implementation of functools.reduce that uses the same docstring like the C implementation. 

Thanks @vreuter for the report.
History
Date User Action Args
2019-03-24 16:26:19xtreaksetnosy: + xtreak
messages: + msg338740
2018-12-01 03:49:52bignosesetmessages: + msg330842
2018-12-01 03:48:04bignosesetnosy: + bignose

messages: + msg330841
title: functools.reduce signature/docstring discordance -> functools.reduce signature uses `iterable`, documentation should use the same term
2018-04-01 06:38:24ncoghlansetmessages: + msg314763
2018-03-30 20:33:28terry.reedysetnosy: + terry.reedy
messages: + msg314713
2018-03-24 05:21:38serhiy.storchakasetnosy: + rhettinger, ncoghlan

versions: - Python 3.5
2018-03-24 00:05:44vreutercreate