| 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) *  |
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: Alyssa Coghlan (ncoghlan) * |
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) * |
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 added a python fallback implementation of functools.reduce that uses the same docstring like the C implementation. Thanks @vreuter for the report. |
|
|