Add optional *func* argument to itertools.accumulate().

1 files changed, 28 insertions, 5 deletions

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 757823d..07378d1 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -46,7 +46,7 @@ Iterator            Arguments               Results
 ====================    ============================    =================================================   =============================================================
 Iterator                Arguments                       Results                                             Example
 ====================    ============================    =================================================   =============================================================
-:func:`accumulate`      p                               p0, p0+p1, p0+p1+p2, ...                            ``accumulate([1,2,3,4,5]) --> 1 3 6 10 15``
+:func:`accumulate`      p [,func]                       p0, p0+p1, p0+p1+p2, ...                            ``accumulate([1,2,3,4,5]) --> 1 3 6 10 15``
 :func:`chain`           p, q, ...                       p0, p1, ... plast, q0, q1, ...                      ``chain('ABC', 'DEF') --> A B C D E F``
 :func:`compress`        data, selectors                 (d[0] if s[0]), (d[1] if s[1]), ...                 ``compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F``
 :func:`dropwhile`       pred, seq                       seq[n], seq[n+1], starting when pred fails          ``dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1``
@@ -84,23 +84,46 @@ The following module functions all construct and return iterators. Some provide
 streams of infinite length, so they should only be accessed by functions or
 loops that truncate the stream.
 
-.. function:: accumulate(iterable)
+.. function:: accumulate(iterable[, func])
 
     Make an iterator that returns accumulated sums. Elements may be any addable
-    type including :class:`Decimal` or :class:`Fraction`.  Equivalent to::
+    type including :class:`Decimal` or :class:`Fraction`.  If the optional
+    *func* argument is supplied, it should be a function of two arguments
+    and it will be used instead of addition.
 
-        def accumulate(iterable):
+    Equivalent to::
+
+        def accumulate(iterable, func=operator.add):
             'Return running totals'
             # accumulate([1,2,3,4,5]) --> 1 3 6 10 15
+            # accumulate([1,2,3,4,5], operator.mul) --> 1 2 6 24 120
             it = iter(iterable)
             total = next(it)
             yield total
             for element in it:
-                total = total + element
+                total = func(total, element)
                 yield total
 
+    Uses for the *func* argument include :func:`min` for a running minimum,
+    :func:`max` for a running maximum, and :func:`operator.mul` for a running
+    product::
+
+      >>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
+      >>> list(accumulate(data, operator.mul))     # running product
+      [3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]
+      >>> list(accumulate(data, max))              # running maximum
+      [3, 4, 6, 6, 6, 9, 9, 9, 9, 9]
+
+      # Amortize a 5% loan of 1000 with 4 annual payments of 90
+      >>> cashflows = [1000, -90, -90, -90, -90]
+      >>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt))
+      [1000, 960.0, 918.0, 873.9000000000001, 827.5950000000001]
+
     .. versionadded:: 3.2
 
+    .. versionchanged:: 3.3
+       Added the optional *func* parameter.
+
 .. function:: chain(*iterables)
 
    Make an iterator that returns elements from the first iterable until it is