gh-135282: change documented signature of itertools.accumulate()
#135283
Conversation
Now it's in sync with docstring/inspect output.
|
@rhettinger, I know you usually against changes in docs, that introduce "advanced" function signatures (despite PDEB decision), but I think this change worth it.
Before: BTW, most examples in the module (except for islice/repeat) use AC and could be easily converted to use signatures as in the sphinx docs (i.e., no slashes). |
itertools.accumulate()
| @@ -93,12 +93,12 @@ streams of infinite length, so they should only be accessed by functions or | |||
| loops that truncate the stream. | |||
|
|
|||
|
|
|||
| .. function:: accumulate(iterable[, function, *, initial=None]) | |||
| .. function:: accumulate(iterable, func=None, *, initial=None) | |||
There was a problem hiding this comment.
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.
| .. function:: accumulate(iterable, func=None, *, initial=None) | |
| .. function:: accumulate(iterable) | |
| accumulate(iterable, *, initial) | |
| accumulate(iterable, func, *, initial=None) |
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:
| .. function:: accumulate(iterable, func=None, *, initial=None) | |
| .. function:: accumulate(iterable, *, initial=None) | |
| accumulate(iterable, func, *, initial=None) |
Now it's in sync with docstring/inspect output.
functionargument ofitertools.accumulate()gets error against the doc #135282📚 Documentation preview 📚: https://cpython-previews--135283.org.readthedocs.build/
https://cpython-previews--135283.org.readthedocs.build/en/135283/library/itertools.html#itertools.accumulate