gh-81313: Add the math.integer module (PEP-791) (GH-133909)

Author: serhiy-storchaka

Doc/library/math.integer.rst

@@ -0,0 +1,85 @@
+:mod:`math.integer` --- integer-specific mathematics functions
+==============================================================
+
+.. module:: math.integer
+   :synopsis: Integer-specific mathematics functions.
+
+.. versionadded:: next
+
+--------------
+
+This module provides access to the mathematical functions defined for integer arguments.
+These functions accept integers and objects that implement the
+:meth:`~object.__index__` method which is used to convert the object to an integer
+number.
+
+The following functions are provided by this module.  All return values are
+computed exactly and are integers.
+
+
+.. function:: comb(n, k, /)
+
+   Return the number of ways to choose *k* items from *n* items without repetition
+   and without order.
+
+   Evaluates to ``n! / (k! * (n - k)!)`` when ``k <= n`` and evaluates
+   to zero when ``k > n``.
+
+   Also called the binomial coefficient because it is equivalent
+   to the coefficient of k-th term in polynomial expansion of
+   ``(1 + x)ⁿ``.
+
+   Raises :exc:`ValueError` if either of the arguments are negative.
+
+
+.. function:: factorial(n, /)
+
+   Return factorial of the nonnegative integer *n*.
+
+
+.. function:: gcd(*integers)
+
+   Return the greatest common divisor of the specified integer arguments.
+   If any of the arguments is nonzero, then the returned value is the largest
+   positive integer that is a divisor of all arguments.  If all arguments
+   are zero, then the returned value is ``0``.  ``gcd()`` without arguments
+   returns ``0``.
+
+
+.. function:: isqrt(n, /)
+
+   Return the integer square root of the nonnegative integer *n*. This is the
+   floor of the exact square root of *n*, or equivalently the greatest integer
+   *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
+
+   For some applications, it may be more convenient to have the least integer
+   *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
+   the exact square root of *n*. For positive *n*, this can be computed using
+   ``a = 1 + isqrt(n - 1)``.
+
+
+   .. |nbsp| unicode:: 0xA0
+      :trim:
+
+
+.. function:: lcm(*integers)
+
+   Return the least common multiple of the specified integer arguments.
+   If all arguments are nonzero, then the returned value is the smallest
+   positive integer that is a multiple of all arguments.  If any of the arguments
+   is zero, then the returned value is ``0``.  ``lcm()`` without arguments
+   returns ``1``.
+
+
+.. 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:`ValueError` if either of the arguments are negative.

Doc/library/math.rst

@@ -27,15 +27,6 @@ noted otherwise, all return values are floats.
 
 
 ====================================================  ============================================
-**Number-theoretic functions**
---------------------------------------------------------------------------------------------------
-:func:`comb(n, k) <comb>`                             Number of ways to choose *k* items from *n* items without repetition and without order
-:func:`factorial(n) <factorial>`                      *n* factorial
-:func:`gcd(*integers) <gcd>`                          Greatest common divisor of the integer arguments
-:func:`isqrt(n) <isqrt>`                              Integer square root of a nonnegative integer *n*
-:func:`lcm(*integers) <lcm>`                          Least common multiple of the integer arguments
-:func:`perm(n, k) <perm>`                             Number of ways to choose *k* items from *n* items without repetition and with order
-
 **Floating point arithmetic**
 --------------------------------------------------------------------------------------------------
 :func:`ceil(x) <ceil>`                                Ceiling of *x*, the smallest integer greater than or equal to *x*
@@ -126,92 +117,6 @@ noted otherwise, all return values are floats.
 ====================================================  ============================================
 
 
-Number-theoretic functions
---------------------------
-
-.. function:: comb(n, k)
-
-   Return the number of ways to choose *k* items from *n* items without repetition
-   and without order.
-
-   Evaluates to ``n! / (k! * (n - k)!)`` when ``k <= n`` and evaluates
-   to zero when ``k > n``.
-
-   Also called the binomial coefficient because it is equivalent
-   to the coefficient of k-th term in polynomial expansion of
-   ``(1 + x)ⁿ``.
-
-   Raises :exc:`TypeError` if either of the arguments are not integers.
-   Raises :exc:`ValueError` if either of the arguments are negative.
-
-   .. versionadded:: 3.8
-
-
-.. function:: factorial(n)
-
-   Return factorial of the nonnegative integer *n*.
-
-   .. versionchanged:: 3.10
-      Floats with integral values (like ``5.0``) are no longer accepted.
-
-
-.. function:: gcd(*integers)
-
-   Return the greatest common divisor of the specified integer arguments.
-   If any of the arguments is nonzero, then the returned value is the largest
-   positive integer that is a divisor of all arguments.  If all arguments
-   are zero, then the returned value is ``0``.  ``gcd()`` without arguments
-   returns ``0``.
-
-   .. versionadded:: 3.5
-
-   .. versionchanged:: 3.9
-      Added support for an arbitrary number of arguments. Formerly, only two
-      arguments were supported.
-
-
-.. function:: isqrt(n)
-
-   Return the integer square root of the nonnegative integer *n*. This is the
-   floor of the exact square root of *n*, or equivalently the greatest integer
-   *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
-
-   For some applications, it may be more convenient to have the least integer
-   *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
-   the exact square root of *n*. For positive *n*, this can be computed using
-   ``a = 1 + isqrt(n - 1)``.
-
-   .. versionadded:: 3.8
-
-
-.. function:: lcm(*integers)
-
-   Return the least common multiple of the specified integer arguments.
-   If all arguments are nonzero, then the returned value is the smallest
-   positive integer that is a multiple of all arguments.  If any of the arguments
-   is zero, then the returned value is ``0``.  ``lcm()`` without arguments
-   returns ``1``.
-
-   .. versionadded:: 3.9
-
-
-.. 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.
-
-   .. versionadded:: 3.8
-
-
 Floating point arithmetic
 -------------------------
 
@@ -812,6 +717,75 @@ Special functions
    .. versionadded:: 3.2
 
 
+Number-theoretic functions
+--------------------------
+
+For backward compatibility, the :mod:`math` module provides also aliases of
+the following functions from the :mod:`math.integer` module:
+
+.. list-table::
+
+   * - .. function:: comb(n, k)
+          :no-typesetting:
+
+       :func:`comb(n, k) <math.integer.comb>`
+     - Number of ways to choose *k* items from *n* items without repetition
+       and without order
+
+   * - .. function:: factorial(n)
+          :no-typesetting:
+
+       :func:`factorial(n) <math.integer.factorial>`
+     - *n* factorial
+
+   * - .. function:: gcd(*integers)
+          :no-typesetting:
+
+       :func:`gcd(*integers) <math.integer.gcd>`
+     - Greatest common divisor of the integer arguments
+
+   * - .. function:: isqrt(n)
+          :no-typesetting:
+
+       :func:`isqrt(n) <math.integer.isqrt>`
+     - Integer square root of a nonnegative integer *n*
+
+   * - .. function:: lcm(*integers)
+          :no-typesetting:
+
+       :func:`lcm(*integers) <math.integer.lcm>`
+     - Least common multiple of the integer arguments
+
+   * - .. function:: perm(n, k)
+          :no-typesetting:
+
+       :func:`perm(n, k) <math.integer.perm>`
+     - Number of ways to choose *k* items from *n* items without repetition
+       and with order
+
+.. versionadded:: 3.5
+   The :func:`gcd` function.
+
+.. versionadded:: 3.8
+   The :func:`comb`, :func:`perm` and :func:`isqrt` functions.
+
+.. versionadded:: 3.9
+   The :func:`lcm` function.
+
+.. versionchanged:: 3.9
+   Added support for an arbitrary number of arguments in the :func:`gcd`
+   function.
+   Formerly, only two arguments were supported.
+
+.. versionchanged:: 3.10
+   Floats with integral values (like ``5.0``) are no longer accepted in the
+   :func:`factorial` function.
+
+.. deprecated:: next
+   These aliases are :term:`soft deprecated` in favor of the
+   :mod:`math.integer` functions.
+
+
 Constants
 ---------
 
@@ -894,5 +868,5 @@ Constants
    Module :mod:`cmath`
       Complex number versions of many of these functions.
 
-.. |nbsp| unicode:: 0xA0
-   :trim:
+   Module :mod:`math.integer`
+      Integer-specific mathematics functions.

Doc/library/numeric.rst

@@ -19,6 +19,7 @@ The following modules are documented in this chapter:
 
    numbers.rst
    math.rst
+   math.integer.rst
    cmath.rst
    decimal.rst
    fractions.rst

Doc/whatsnew/3.15.rst

@@ -311,7 +311,12 @@ Other language changes
 New modules
 ===========
 
-* None yet.
+math.integer
+------------
+
+This module provides access to the mathematical functions for integer
+arguments (:pep:`791`).
+(Contributed by Serhiy Storchaka in :gh:`81313`.)
 
 
 Improved modules

Include/internal/pycore_import.h

@@ -17,7 +17,8 @@ extern int _PyImport_IsInitialized(PyInterpreterState *);
 // Export for 'pyexpat' shared extension
 PyAPI_FUNC(int) _PyImport_SetModule(PyObject *name, PyObject *module);
 
-extern int _PyImport_SetModuleString(const char *name, PyObject* module);
+// Export for 'math' shared extension
+PyAPI_FUNC(int) _PyImport_SetModuleString(const char *name, PyObject* module);
 
 extern void _PyImport_AcquireLock(PyInterpreterState *interp);
 extern void _PyImport_ReleaseLock(PyInterpreterState *interp);

Lib/test/test_capi/test_misc.py

@@ -307,7 +307,7 @@ def test_getitem_with_error(self):
                     CURRENT_THREAD_REGEX +
                     r'  File .*, line 6 in <module>\n'
                     r'\n'
-                    r'Extension modules: _testcapi \(total: 1\)\n')
+                    r'Extension modules: ')
         else:
             # Python built with NDEBUG macro defined:
             # test _Py_CheckFunctionResult() instead.