From 74f315edd01b4d6c6c99e50c03a90116820d8d47 Mon Sep 17 00:00:00 2001 From: Xuehai Pan Date: Tue, 19 Sep 2023 00:42:58 +0800 Subject: gh-102757: fix function signature mismatch for `functools.reduce` between code and documentation (#102759) --- Doc/library/functools.rst | 14 ++++++++------ Lib/functools.py | 2 +- .../2023-03-16-15-39-26.gh-issue-102759.ehpHw6.rst | 2 ++ Modules/_functoolsmodule.c | 2 +- 4 files changed, 12 insertions(+), 8 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2023-03-16-15-39-26.gh-issue-102759.ehpHw6.rst diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index f736eb0..69ec1eb 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 a2fc287..6cb5323 100644 --- a/Lib/functools.py +++ b/Lib/functools.py @@ -236,7 +236,7 @@ _initial_missing = object() 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 0000000..d3df6c8 --- /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 389ff43..8ea493a 100644 --- a/Modules/_functoolsmodule.c +++ b/Modules/_functoolsmodule.c @@ -725,7 +725,7 @@ Fail: } 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\ -- cgit v0.12