diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index f736eb0aca1ac5..69ec1eb3ecd89d 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -403,25 +403,27 @@ The :mod:`functools` module defines the following functions: .. versionadded:: 3.4 -.. function:: reduce(function, iterable[, initializer]) +.. function:: reduce(function, iterable[, initial], /) Apply *function* of two arguments cumulatively to the items of *iterable*, from left to right, so as to reduce the iterable to a single value. For example, ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``. The left argument, *x*, is the accumulated value and the right argument, *y*, is - the update value from the *iterable*. If the optional *initializer* is present, + the update value from the *iterable*. If the optional *initial* is present, it is placed before the items of the iterable in the calculation, and serves as - a default when the iterable is empty. If *initializer* is not given and + a default when the iterable is empty. If *initial* is not given and *iterable* contains only one item, the first item is returned. Roughly equivalent to:: - def reduce(function, iterable, initializer=None): + initial_missing = object() + + def reduce(function, iterable, initial=initial_missing, /): it = iter(iterable) - if initializer is None: + if initial is initial_missing: value = next(it) else: - value = initializer + value = initial for element in it: value = function(value, element) return value diff --git a/Lib/functools.py b/Lib/functools.py index a2fc28779dbddc..6cb532323b1d67 100644 --- a/Lib/functools.py +++ b/Lib/functools.py @@ -236,7 +236,7 @@ def __ge__(self, other): def reduce(function, sequence, initial=_initial_missing): """ - reduce(function, iterable[, initial]) -> value + reduce(function, iterable[, initial], /) -> value Apply a function of two arguments cumulatively to the items of a sequence or iterable, from left to right, so as to reduce the iterable to a single diff --git a/Misc/NEWS.d/next/Documentation/2023-03-16-15-39-26.gh-issue-102759.ehpHw6.rst b/Misc/NEWS.d/next/Documentation/2023-03-16-15-39-26.gh-issue-102759.ehpHw6.rst new file mode 100644 index 00000000000000..d3df6c8997aa35 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2023-03-16-15-39-26.gh-issue-102759.ehpHw6.rst @@ -0,0 +1,2 @@ +Align function signature for ``functools.reduce`` in documentation and docstring +with the C implementation. diff --git a/Modules/_functoolsmodule.c b/Modules/_functoolsmodule.c index 389ff4391de0be..8ea493ad9ab278 100644 --- a/Modules/_functoolsmodule.c +++ b/Modules/_functoolsmodule.c @@ -725,7 +725,7 @@ functools_reduce(PyObject *self, PyObject *args) } PyDoc_STRVAR(functools_reduce_doc, -"reduce(function, iterable[, initial]) -> value\n\ +"reduce(function, iterable[, initial], /) -> value\n\ \n\ Apply a function of two arguments cumulatively to the items of a sequence\n\ or iterable, from left to right, so as to reduce the iterable to a single\n\