gh-125916: Allow functools.reduce() 'initial' to be a keyword argument (#125917)

8 files changed, 76 insertions, 13 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index e26a222..a9aceee 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -453,7 +453,7 @@ The :mod:`functools` module defines the following functions:
    .. versionadded:: 3.4
 
 
-.. function:: reduce(function, iterable[, initial], /)
+.. 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,
@@ -468,7 +468,7 @@ The :mod:`functools` module defines the following functions:
 
       initial_missing = object()
 
-      def reduce(function, iterable, initial=initial_missing, /):
+      def reduce(function, iterable, /, initial=initial_missing):
           it = iter(iterable)
           if initial is initial_missing:
               value = next(it)
@@ -481,6 +481,9 @@ The :mod:`functools` module defines the following functions:
    See :func:`itertools.accumulate` for an iterator that yields all intermediate
    values.
 
+   .. versionchanged:: next
+      *initial* is now supported as a keyword argument.
+
 .. decorator:: singledispatch
 
    Transform a function into a :term:`single-dispatch <single
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index 9c03263..66f8c432 100644
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -320,6 +320,11 @@ functools
   to reserve a place for positional arguments.
   (Contributed by Dominykas Grigonis in :gh:`119127`.)
 
+* Allow the *initial* parameter of :func:`functools.reduce` to be passed
+  as a keyword argument.
+  (Contributed by Sayandip Dutta in :gh:`125916`.)
+
+
 getopt
 ------
 
diff --git a/Lib/functools.py b/Lib/functools.py
index 27abd62..bde0a3e 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 an iterable, from left to right.
 
diff --git a/Lib/test/test_functools.py b/Lib/test/test_functools.py
index d590af0..6d60f69 100644
--- a/Lib/test/test_functools.py
+++ b/Lib/test/test_functools.py
@@ -1005,6 +1005,29 @@ class TestReduce:
         d = {"one": 1, "two": 2, "three": 3}
         self.assertEqual(self.reduce(add, d), "".join(d.keys()))
 
+    # test correctness of keyword usage of `initial` in `reduce`
+    def test_initial_keyword(self):
+        def add(x, y):
+            return x + y
+        self.assertEqual(
+            self.reduce(add, ['a', 'b', 'c'], ''),
+            self.reduce(add, ['a', 'b', 'c'], initial=''),
+        )
+        self.assertEqual(
+            self.reduce(add, [['a', 'c'], [], ['d', 'w']], []),
+            self.reduce(add, [['a', 'c'], [], ['d', 'w']], initial=[]),
+        )
+        self.assertEqual(
+            self.reduce(lambda x, y: x*y, range(2,8), 1),
+            self.reduce(lambda x, y: x*y, range(2,8), initial=1),
+        )
+        self.assertEqual(
+            self.reduce(lambda x, y: x*y, range(2,21), 1),
+            self.reduce(lambda x, y: x*y, range(2,21), initial=1),
+        )
+        self.assertRaises(TypeError, self.reduce, add, [0, 1], initial="")
+        self.assertEqual(self.reduce(42, "", initial="1"), "1") # func is never called with one item
+
 
 @unittest.skipUnless(c_functools, 'requires the C _functools module')
 class TestReduceC(TestReduce, unittest.TestCase):
diff --git a/Misc/ACKS b/Misc/ACKS
index 6b5d7bf..dce322f 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -485,6 +485,7 @@ Luke Dunstan
 Virgil Dupras
 Bruno Dupuis
 Andy Dustman
+Sayandip Dutta
 Gary Duzan
 Eugene Dvurechenski
 Karmen Dykstra
diff --git a/Misc/NEWS.d/next/Library/2024-10-24-13-40-20.gh-issue-126916.MAgz6D.rst b/Misc/NEWS.d/next/Library/2024-10-24-13-40-20.gh-issue-126916.MAgz6D.rst
new file mode 100644
index 0000000..cbe2fc1
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-10-24-13-40-20.gh-issue-126916.MAgz6D.rst
@@ -0,0 +1,2 @@
+Allow the *initial* parameter of :func:`functools.reduce` to be passed as a keyword argument.
+Patch by Sayandip Dutta.
diff --git a/Modules/_functoolsmodule.c b/Modules/_functoolsmodule.c
index d2afe1a..5e0cf05 100644
--- a/Modules/_functoolsmodule.c
+++ b/Modules/_functoolsmodule.c
@@ -937,8 +937,8 @@ _functools.reduce
 
     function as func: object
     iterable as seq: object
-    initial as result: object = NULL
     /
+    initial as result: object = NULL
 
 Apply a function of two arguments cumulatively to the items of an iterable, from left to right.
 
@@ -953,7 +953,7 @@ calculates ((((1 + 2) + 3) + 4) + 5).
 static PyObject *
 _functools_reduce_impl(PyObject *module, PyObject *func, PyObject *seq,
                        PyObject *result)
-/*[clinic end generated code: output=30d898fe1267c79d input=d233c2670cba7f66]*/
+/*[clinic end generated code: output=30d898fe1267c79d input=1511e9a8c38581ac]*/
 {
     PyObject *args, *it;
 
diff --git a/Modules/clinic/_functoolsmodule.c.h b/Modules/clinic/_functoolsmodule.c.h
index 7608779..afd5eb4 100644
--- a/Modules/clinic/_functoolsmodule.c.h
+++ b/Modules/clinic/_functoolsmodule.c.h
@@ -69,7 +69,7 @@ exit:
 }
 
 PyDoc_STRVAR(_functools_reduce__doc__,
-"reduce($module, function, iterable, initial=<unrepresentable>, /)\n"
+"reduce($module, function, iterable, /, initial=<unrepresentable>)\n"
 "--\n"
 "\n"
 "Apply a function of two arguments cumulatively to the items of an iterable, from left to right.\n"
@@ -82,30 +82,59 @@ PyDoc_STRVAR(_functools_reduce__doc__,
 "calculates ((((1 + 2) + 3) + 4) + 5).");
 
 #define _FUNCTOOLS_REDUCE_METHODDEF    \
-    {"reduce", _PyCFunction_CAST(_functools_reduce), METH_FASTCALL, _functools_reduce__doc__},
+    {"reduce", _PyCFunction_CAST(_functools_reduce), METH_FASTCALL|METH_KEYWORDS, _functools_reduce__doc__},
 
 static PyObject *
 _functools_reduce_impl(PyObject *module, PyObject *func, PyObject *seq,
                        PyObject *result);
 
 static PyObject *
-_functools_reduce(PyObject *module, PyObject *const *args, Py_ssize_t nargs)
+_functools_reduce(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
 {
     PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(initial), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"", "", "initial", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "reduce",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[3];
+    Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 2;
     PyObject *func;
     PyObject *seq;
     PyObject *result = NULL;
 
-    if (!_PyArg_CheckPositional("reduce", nargs, 2, 3)) {
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser,
+            /*minpos*/ 2, /*maxpos*/ 3, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
+    if (!args) {
         goto exit;
     }
     func = args[0];
     seq = args[1];
-    if (nargs < 3) {
-        goto skip_optional;
+    if (!noptargs) {
+        goto skip_optional_pos;
     }
     result = args[2];
-skip_optional:
+skip_optional_pos:
     return_value = _functools_reduce_impl(module, func, seq, result);
 
 exit:
@@ -159,4 +188,4 @@ _functools__lru_cache_wrapper_cache_clear(PyObject *self, PyObject *Py_UNUSED(ig
 
     return return_value;
 }
-/*[clinic end generated code: output=0c3df7e5131200b7 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=e6edcc01f0720daf input=a9049054013a1b77]*/