From: Raymond Hettinger <rhettinger@users.noreply.github.com>
Date: Fri, 7 Feb 2025 00:35:55 +0000 (-0600)
Subject: Add multinomial to the itertools recipes docs (gh-129760)
X-Git-Tag: v3.14.0a5~76
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e1e85204edbf8c0c9ba1e50c74ac8708553585d8;p=thirdparty%2FPython%2Fcpython.git

Add multinomial to the itertools recipes docs (gh-129760)
---

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index eb61453718bd..fbbec42ce9da 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -838,10 +838,10 @@ and :term:`generators <generator>` which incur interpreter overhead.
 
 .. testcode::
 
-   from collections import deque
+   from collections import Counter, deque
    from contextlib import suppress
    from functools import reduce
-   from math import sumprod, isqrt
+   from math import comb, prod, sumprod, isqrt
    from operator import itemgetter, getitem, mul, neg
 
    def take(n, iterable):
@@ -1127,6 +1127,12 @@ The following recipes have a more mathematical flavor:
            n -= n // prime
        return n
 
+   def multinomial(*counts):
+       "Number of distinct arrangements of a multiset."
+       # Counter('abracadabra').values() -> 5 2 1 1 2
+       # multinomial(5, 2, 1, 1, 2) → 83160
+       return prod(map(comb, accumulate(counts), counts))
+
 
 .. doctest::
     :hide:
@@ -1730,6 +1736,12 @@ The following recipes have a more mathematical flavor:
     >>> ''.join(it)
     'DEF1'
 
+    >>> multinomial(5, 2, 1, 1, 2)
+    83160
+    >>> word = 'coffee'
+    >>> multinomial(*Counter(word).values()) == len(set(permutations(word)))
+    True
+
 
 .. testcode::
     :hide: