Using the `function` argument of `itertools.accumulate()` gets error against the doc

[hyperkai]

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

• gh-135282: change documented signature of itertools.accumulate() #135283

[skirpichev]

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:

>>> help(itertools.accumulate)
Help on class accumulate in module itertools:

class accumulate(builtins.object)
 |  accumulate(iterable, func=None, *, initial=None)
 |
 |  Return series of accumulated sums (or other binary function results).
 |
 |  Methods defined here:
 |
 |  __getattribute__(self, name, /)
 |      Return getattr(self, name).
 |
 |  __iter__(self, /)
 |      Implement iter(self).
 |
 |  __next__(self, /)
 |      Implement next(self).
 |
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |
 |  __new__(*args, **kwargs)
 |      Create and return a new object.  See help(type) for accurate signature.

In this case - you are using wrong keyword name. Should be func, not function.

[rhettinger]

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]

It is not wrong to use square brackets, we use that is multiple places in the itertools docs.

@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.

To me, this doc makes the pure python equivalent harder to read and makes the docs worse.

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 per docs expert index)

Until the OP's report, no one have ever had an issue with correctly reading this.

1. It's not a strong argument per se. Python community grow, someone eventually will read incorrectly something that aren't explained somewhere.
2. And it's not that actually happened.
3. OP correctly read docs: they say accumulate() has optional argument, named function.
4. And this is wrong. Documentation lies.
5. Last but not least, sphinx docs also inconsistent with help(), inspect and friends, which show correct function signature.

PS: @picnixz, I'm thinking about reopening the issue.

[AA-Turner]

Sergey, thank you for your thoughts here and on the linked PR. I think though that we can adopt a more constructive discussion.

Raymond is correct that the current documentation is fine as-is. Any change should not confuse the situation or make the documentation less intelligable. I don't believe that the square-bracket syntax is verboten or requires guesswork on the part of the reader; all forms of syntax are initially unfamiliar, including the slash-star syntax that we are now using for new documentation.

Addressing some specific points:

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.

I don't recall coming to consensus on rejecting this. The function does have multiple call signatures from a conceptual perspective. The documentation tool that we use (Sphinx) was designed for use in this project, explicitly including support for documenting multiple signatures for a single object. This feature is used in several places in the documentation.

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
...
Last but not least, sphinx docs also inconsistent with help(), inspect and friends, which show correct function signature.

Along with Raymond, I also raised the concern of blanket-renaming func to function. Personally, I think a reasonable compromise position is to supply func as the name in the documented signature, but use function throughout in the prose. An alternative as mentioned is to rename the func parameter to function, but I think this goes too far.

In this vein, it is fine to document a different signature than help or inspect.signature provide. The obvious example is range().

Until the OP's report, no one have ever had an issue with correctly reading this.
It's not a strong argument per se. Python community grow, someone eventually will read incorrectly something that aren't explained somewhere.

On the contrary, this is a fairly strong argument -- in practice, this is not an issue that people face. We should prioritise solving common problems reported and faced by users, whereas this is a very rare case.

OP correctly read docs: they say accumulate() has optional argument, named function.
And this is wrong. Documentation lies.

I would phrase this as that the documentation is unclear. I think it is unfair to say that it lies. The key is that the current documentation suggests (if I understand correctly) that function should be used as a positional-only argument, whereas the user attempted to use it as a keyword argument.

I would support a more limited PR that removed some of the ambiguity I've mentioned, but I also think closing this issue for now is a reasonable choice.

A

[skirpichev]

I don't believe that the square-bracket syntax is verboten or requires guesswork on the part of the reader; all forms of syntax are initially unfamiliar, including the slash-star syntax that we are now using for new documentation.

The Python syntax is explained in docs. While the square-bracket syntax is not. And it turns even you guess about it's meaning (see below).

But it's not the main part of issue and, probably, should be discussed rather in the d.p.o thread.

I think a reasonable compromise position is to supply func as the name in the documented signature, but use function throughout in the prose.

All this means - people can't use name of this argument. Either in the Sphinx docs on in help()/IDE suggestions - it will be invalid.

Then lets remove argument name from the API!

@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.

Along with Raymond, I also raised the concern of blanket-renaming func to function.

That solution was chosen, assuming help()/inspect output is precise. But we can instead correct the implementation, i.e. rename func keyword argument to function.

The obvious example is range().

Yeah. In this case we have different signatures even in the Sphinx docs... :-(

The key is that the current documentation suggests that function should be used as a positional-only argument

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.

(if I understand correctly)

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:

• range - here you are right, no keyword arguments are allowed.
• itertools.repeat - Oops, here you are wrong, this function supports object and times keywords.

What we have learned? We can only guess that means this syntax! :-)