[docs] [issue33130] functools.reduce signature/docstring discordance

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

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)?

----------
nosy: +terry.reedy

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