Open
Description
Bug report
Bug description:
The doc of itertools.accumulate()
says the 2nd parameter is function
as shown below:
itertools.accumulate(iterable[, function, *, initial=None])
But using function
argument gets the error against the doc as shown below:
from itertools import accumulate
from operator import mul
# ↓↓↓↓↓↓↓↓
for x in accumulate(iterable=[1, 2, 3, 4, 5], function=mul):
print(x)
# TypeError: 'function' is an invalid keyword argument for accumulate()
So, I used func
argument, then it works as shown below:
from itertools import accumulate
from operator import mul
# ↓↓↓↓
for x in accumulate(iterable=[1, 2, 3, 4, 5], func=mul):
print(x)
# 1
# 2
# 6
# 24
# 120
CPython versions tested on:
3.13
Operating systems tested on:
Windows
Linked PRs
Metadata
Metadata
Assignees
Projects
Status
Todo
Activity
skirpichev commentedon Jun 9, 2025
That's because many functions in the itertools docs have funny syntax with brackets instead of correct signatures. See also #131885.
But help() and inspect.signature() will show you a correct signature:
In this case - you are using wrong keyword name. Should be func, not function.
pythongh-135282: correct itertools.accumulate() signature in sphinx docs
itertools.accumulate()
#135283rhettinger commentedon Jun 16, 2025
I prefer that docs as they are now. It is not wrong to use square brackets, we use that is multiple places in the itertools docs.
To me, this doc makes the pure python equivalent harder to read and makes the docs worse. Until the OP's report, no one have ever had an issue with correctly reading this.
skirpichev commentedon Jun 17, 2025
@rhettinger, I think it's wrong to have syntax in docs, for which people have to guess it's meaning. But there is a discussion thread: https://discuss.python.org/t/95015
And this funny syntax is not the whole story.
The
func
argument name is a part of API. It's shown in the inspect.signature(), in help() output, it's suggested in IDE's...Lets rename this argument to
function
. If the argument name is not a part of API - lets also change the accumulate() signature accordingly.In the pr thread it was suggested, that this case is better described by multiple signatures, i.e.
func=None
default should be hidden. This was rejected on ground of backward compatibility, but if this is not an issue - I think it's a good idea.(CC @AA-Turner, I can understand reasons to keep a "reasonable compromise" if Python had no syntax for positional-only arguments. But the Python has a dedicated syntax for this and the AC supports it.
That solution was chosen, assuming help()/inspect output is precise. But we can instead correct the implementation, i.e. rename
func
keyword argument tofunction
.Yeah. In this case we have different signatures even in the Sphinx docs... :-(
Great example! Now you guess about the square-bracket syntax ;-)
But anyway IDE suggestions, help() output and so on - suggest a different view: the function has named arguments. And they names are different wrt the Sphinx docs.
I don't know) We have to guess, as this syntax is not documented somewhere. Anyone will have to guess.
Lets learn it by examples:
object
andtimes
keywords.What we have learned? We can only guess that means this syntax! :-)
6 remaining items