I think this is a better alternative, if we decide to change anything. None is misleading: the prose notes that the function defaults to addition. This is a good example of the function de facto having multiple signatures. The simple case is summation, the intermediate case is summation from an initial condition, and the advanced case is a custom accumulator.

The linked issue is a user using keyword-arguments for both iterable and func, which should probably be discouraged. I personally find it clearer to have 'function' throughout in the prose documentation, and I wonder if func is less clear to non-native speakers of English.

Arguably, it should note that initial is only used if not None, too, but this is somewhat obvious from context.

A second, simpler suggestion would be as follows:

This is a good example of the function de facto having multiple signatures.

Yet it has one.

The linked issue is a user using keyword-arguments for both iterable and func, which should probably be discouraged.

Both argument names are part of the API.

I personally find it clearer to have 'function' throughout in the prose documentation

We can change argument name, but it looks as a compatibility break for me.

Sorry, neither suggestion is acceptable for me.

.. function:: accumulate(iterable, *, initial=None)
              accumulate(iterable, func, *, initial=None)

This suggestion is IMO the best because it hides the implementation detail of func=None.

"reference material should prioritize precision and completeness" (c)

Proposed changes aren't precise. Are you suggesting to change actual function signature?

No, I meant to hide the implementation detail. I don't think anyone is expected to do accumulate(iterable, None) (the current docs do not expose that detail for instance).

Even if the EB's decision is about "reference material should prioritize precision and completeness", it's a "SHOULD" not a "MUST", which I consider it as a recommendation and not a strict rule. When it comes at the cost of exposing implementation details, I think it's better not to.

Now, itertools.groupby explicitly documents key as being allowed to be None and says:

If not specified or is None, key defaults to an identity function and returns the element unchanged

So, if you want to keep func=None, I'd suggest stating that None defaults to addition. This would avoid two signatures in the docs and would be aligned with itertools.groupby.

which I consider it as a recommendation and not a strict rule

Given the fate of #131885 - I guess you are right :(

When it comes at the cost of exposing implementation details, I think it's better not to.

Where is the difference between implementation details and API? These "details" could be discovered anyway by standard tools for introspection.

Now function has a valid (for the inspect module) signature. Why should we lie in docs, that func=None is not accepted?

I'd suggest stating that None defaults to addition.

But that seems to be documented: "The func defaults to addition." (and default argument for func shown in the signature)

Don't change this to func. I have intentionally spelled-out function in multiple places in the itertools docs.

I reverted this and other examples in the function description. (Not sure if this is a good idea: *function* clearly refers to the argument name.)

I also modified example per suggestion in the issue thread.