bpo-37178: Allow a one argument form of math.perm() (GH-13905)

Author: rhettinger

Doc/library/math.rst

@@ -210,14 +210,17 @@ Number-theoretic and representation functions
    of *x* and are floats.
 
 
-.. function:: perm(n, k)
+.. function:: perm(n, k=None)
 
    Return the number of ways to choose *k* items from *n* items
    without repetition and with order.
 
    Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
    to zero when ``k > n``.
 
+   If *k* is not specified or is None, then *k* defaults to *n*
+   and the function returns ``n!``.
+
    Raises :exc:`TypeError` if either of the arguments are not integers.
    Raises :exc:`ValueError` if either of the arguments are negative.
 

Lib/test/test_math.py

@@ -1885,16 +1885,21 @@ def testPerm(self):
             self.assertEqual(perm(n, 1), n)
             self.assertEqual(perm(n, n), factorial(n))
 
+        # Test one argument form
+        for n in range(20):
+            self.assertEqual(perm(n), factorial(n))
+            self.assertEqual(perm(n, None), factorial(n))
+
         # Raises TypeError if any argument is non-integer or argument count is
-        # not 2
+        # not 1 or 2
         self.assertRaises(TypeError, perm, 10, 1.0)
         self.assertRaises(TypeError, perm, 10, decimal.Decimal(1.0))
         self.assertRaises(TypeError, perm, 10, "1")
         self.assertRaises(TypeError, perm, 10.0, 1)
         self.assertRaises(TypeError, perm, decimal.Decimal(10.0), 1)
         self.assertRaises(TypeError, perm, "10", 1)
 
-        self.assertRaises(TypeError, perm, 10)
+        self.assertRaises(TypeError, perm)
         self.assertRaises(TypeError, perm, 10, 1, 3)
         self.assertRaises(TypeError, perm)
 

Misc/NEWS.d/next/Library/2019-06-07-17-11-34.bpo-37178.b1StSv.rst

@@ -0,0 +1,2 @@
+For math.perm(n, k), let k default to n, giving the same result as
+factorial.

Misc/NEWS.d/next/Library/2019-06-07-17-16-09.bpo-37178.Day_oB.rst

@@ -0,0 +1,2 @@
+Give math.perm() a one argument form that means the same as
+math.factorial().

Modules/clinic/mathmodule.c.h

@@ -3002,26 +3002,32 @@ math_prod_impl(PyObject *module, PyObject *iterable, PyObject *start)
 math.perm
 
     n: object
-    k: object
+    k: object = None
     /
 
 Number of ways to choose k items from n items without repetition and with order.
 
 Evaluates to n! / (n - k)! when k <= n and evaluates
 to zero when k > n.
 
+If k is not specified or is None, then k defaults to n
+and the function returns n!.
+
 Raises TypeError if either of the arguments are not integers.
 Raises ValueError if either of the arguments are negative.
 [clinic start generated code]*/
 
 static PyObject *
 math_perm_impl(PyObject *module, PyObject *n, PyObject *k)
-/*[clinic end generated code: output=e021a25469653e23 input=b2e7729d9a1949cf]*/
+/*[clinic end generated code: output=e021a25469653e23 input=5311c5a00f359b53]*/
 {
     PyObject *result = NULL, *factor = NULL;
     int overflow, cmp;
     long long i, factors;
 
+    if (k == Py_None) {
+        return math_factorial(module, n);
+    }
     n = PyNumber_Index(n);
     if (n == NULL) {
         return NULL;