Skip to content

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

Open
@hyperkai

Description

@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

Activity

skirpichev

skirpichev commented on Jun 9, 2025

@skirpichev
Contributor

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.

added a commit that references this issue on Jun 9, 2025

pythongh-135282: correct itertools.accumulate() signature in sphinx docs

rhettinger

rhettinger commented on Jun 16, 2025

@rhettinger
Contributor

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

skirpichev commented on Jun 17, 2025

@skirpichev
Contributor

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, 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! :-)

6 remaining items

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dirtype-bugAn unexpected behavior, bug, or error

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Using the `function` argument of `itertools.accumulate()` gets error against the doc · Issue #135282 · python/cpython

      Follow Lee on X/Twitter - Father, Husband, Serial builder creating AI, crypto, games & web tools. We are friends :) AI Will Come To Life!

      Check out: eBank.nz (Art Generator) | Netwrck.com (AI Tools) | Text-Generator.io (AI API) | BitBank.nz (Crypto AI) | ReadingTime (Kids Reading) | RewordGame | BigMultiplayerChess | WebFiddle | How.nz | Helix AI Assistant