From 1581c9d936a665dad9a5481ba880ac3b8fb2b824 Mon Sep 17 00:00:00 2001
From: =?utf8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Sat, 8 Feb 2025 15:10:41 +0100
Subject: [PATCH] [3.12] Add multinomial to the itertools recipes docs
 (gh-129760) (gh-129854)

---
 Doc/library/itertools.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index a82fd8630b7b..b1b7b630a5ec 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -1082,6 +1082,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 math.prod(map(math.comb, accumulate(counts), counts))
+
 
 .. doctest::
     :hide:
@@ -1644,6 +1650,12 @@ The following recipes have a more mathematical flavor:
     >>> ''.join(it)
     'DEF1'
 
+    >>> multinomial(5, 2, 1, 1, 2)
+    83160
+    >>> word = 'coffee'
+    >>> multinomial(*collections.Counter(word).values()) == len(set(permutations(word)))
+    True
+
 
 .. testcode::
     :hide:
-- 
2.47.3