gh-125916: Allow functools.reduce 'initial' to be a keyword argument

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

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
 ------
 

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 an iterable, from left to right.
 

Lib/test/test_functools.py

@@ -1005,6 +1005,29 @@ def __getitem__(self, i):
  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):

Misc/ACKS

@@ -485,6 +485,7 @@ Luke Dunstan
 Virgil Dupras
 Bruno Dupuis
 Andy Dustman
+Sayandip Dutta
 Gary Duzan
 Eugene Dvurechenski
 Karmen Dykstra

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.

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;