PEP 791: imath --- module for number-theoretic functions

Author: skirpichev

.github/CODEOWNERS

@@ -669,6 +669,7 @@ peps/pep-0788.rst  @ZeroIntensity @vstinner
 # ...
 peps/pep-0789.rst  @njsmith
 peps/pep-0790.rst  @hugovk
+peps/pep-0791.rst  @vstinner
 # ...
 peps/pep-0801.rst  @warsaw
 # ...

peps/pep-0791.rst

@@ -0,0 +1,165 @@
+PEP: 791
+Title: imath --- module for number-theoretic functions
+Author: Sergey B Kirpichev <skirpichev@gmail.com>
+Sponsor: Victor Stinner <vstinner@python.org>
+Discussions-To: Pending
+Status: Draft
+Type: Standards Track
+Created: 10-May-2025
+Python-Version: 3.15
+Post-History: 02-Jun-2019,
+              `09-May-2025 <https://discuss.python.org/t/91337>`__,
+
+
+Abstract
+========
+
+This PEP proposes a new module for number-theoretical, combinatorial and other
+integer-valued functions defined for integer arguments, like
+:external+py3.14:func:`math.gcd` or :external+py3.14:func:`math.isqrt`.
+
+
+Motivation
+==========
+
+The :external+py3.14:mod:`math` documentation says: "This module provides access
+to the mathematical functions defined by the C standard."  But as a state of
+art, over time the module was populated with functions that aren't related to
+the C standard or floating-point arithmetics.  Now it's much harder to describe
+module scope, content and interfaces (returned values or accepted arguments).
+
+For example, the :external+py3.14:mod:`math` module documentation says: "Except
+when explicitly noted otherwise, all return values are floats."  This is not
+longer true:  *None* of the functions listed in the "Number-theoretic
+functions" [1]_ subsection of the documentation returns a float, but the
+documentation doesn't say so.  In the proposed module a similar sentence "All
+return values are integers." could tell the truth once.  In a similar way we
+can simplify description of accepted arguments for both the
+:external+py3.14:mod:`math` and the new module.
+
+Apparently, the :external+py3.14:mod:`math` can't serve as a catch-all place
+for mathematical functions: we have also the :external+py3.14:mod:`cmath` and
+the :external+py3.14:mod:`statistics`.  Let's make same for integer-related
+functions.  It would provide shared context, which reduces verbosity in the
+documentation and conceptual load.  It also aids discoverability through
+grouping related functions and IDEs suggesting helpful completions.
+
+
+Specification
+=============
+
+The PEP proposes moving the following integer-related functions [1]_ in a new
+module, called ``imath``:
+
+* :external+py3.14:func:`~math.comb`
+* :external+py3.14:func:`~math.factorial`
+* :external+py3.14:func:`~math.gcd`
+* :external+py3.14:func:`~math.isqrt`
+* :external+py3.14:func:`~math.lcm`
+* :external+py3.14:func:`~math.perm`
+
+Their aliases in :external+py3.14:mod:`math` will be :term:`soft deprecated`.
+
+Modules functions will accept integers and objects that implement the
+:external+py3.14:meth:`~object.__index__` method which is used to convert the
+object to an integer number.
+
+Possible extensions for the new module and it's scope are discussed in the
+`Open Issues <Open Issues_>`_ section.  New functions are not part of the
+proposal.
+
+
+Backwards Compatibility
+=======================
+
+As aliases in :external+py3.14:mod:`math` will be kept for indefinite time
+(their use would be discouraged), there are no anticipated code breaks.
+
+
+Reference Implementation
+========================
+
+https://github.com/python/cpython/pull/133909
+
+
+Open Issues
+===========
+
+Module name
+-----------
+
+Chosen name seems consistent with other domain-specific mathematical module:
+:external+py3.14:mod:`cmath` (for complex numbers).
+
+There is already an ``imath`` project on PyPI, but only with two releases, with
+the most recent one 4 years ago.  Its repository is no longer accessible.
+The `Imath <https://github.com/AcademySoftwareFoundation/Imath>`_ C++ library
+include Python bindings with same name.
+
+`Polling shows <https://discuss.python.org/t/91337/35>`_ ``intmath`` as another
+popular name.  The argument made was that the normal mathematical spelling of
+the imaginary unit is ``i``, which makes imath ambiguous.  It also has no conflict
+with any PyPI module.  On the other hand, ``intmath`` may be confused with
+interval math or numerical integration.
+
+Other proposed names include ``ntheory`` (like SymPy's submodule),
+``integermath`` and ``imaths``.
+
+
+Module scope and possible extensions
+------------------------------------
+
+Unless we can just provide bindings to some well supported mathematical library
+like the GMP, the module scope should be limited.  For example, no primality
+testing and factorization.
+
+There are possible additions, among proposed in the initial discussion thread
+(see also [5]_):
+
+* ``c_div()`` --- for integer ceiling divide, see [2]_, [3]_.
+* ``gcdext()`` --- to solve linear Diophantine equation in two variables (the
+  :external+py3.14:class:`int` implementation actually include extended
+  Euclidean algorithm)
+* ``isqrt_rem()`` --- to return both integer square root and a remainder (if
+  integer isn't a perfect square)
+* ``ilog()`` --- integer logarithm, currently :external+py3.14:func:`math.log`
+  has a special handling for integer arguments.  It's unique (wrt other module
+  functions) and not documented so far, see [4]_
+* ``fibonacci()``.
+
+
+Rejected ideas
+==============
+
+There was a brief discussion about exposing :external+py3.14:func:`math.isqrt`
+as ``imath.sqrt`` in the same way that :external+py3.14:func:`cmath.sqrt` is
+the complex version of :external+py3.14:func:`math.sqrt`.  However, ``isqrt``
+is ultimately a different function: it is the floor of the square root.  It
+would be confusing to give it the same name (under a different module).
+
+
+Acknowledgements
+================
+
+Thanks to Tim Peters for reviving the idea of the :external+py3.14:mod:`math`
+splitting.  Thanks to Neil Girdhar for substantial improvements of
+the initial draft.
+
+
+Footnotes
+=========
+
+.. [1] Number-theoretic functions
+       (https://docs.python.org/3.14/library/math.html#number-theoretic-functions)
+.. [2] Integer ceiling divide
+       (https://discuss.python.org/t/91269)
+.. [3] https://gmpy2.readthedocs.io/en/stable/mpz.html#gmpy2.c_div
+.. [4] https://github.com/python/cpython/issues/120950
+.. [5] https://github.com/python/cpython/issues/81313
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.