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

peps/pep-9999.rst

@@ -0,0 +1,111 @@
+PEP: 9999
+Title: imath --- module for number-theoretic functions
+Author: Sergey B Kirpichev
+Sponsor: TBD
+Discussions-To: Pending
+Status: Draft
+Type: Standards Track
+Created: 10-May-2025
+Python-Version: 3.15
+Post-History: `02-Jun-2019 <https://github.com/python/cpython/issues/81313>`__,
+              `09-May-2025 <https://discuss.python.org/t/91337>`__
+
+
+Abstract
+========
+
+This PEP describes new module for number-theoretic functions over integers,
+like :external+py3.14:func:`math.gcd` or :external+py3.14:func:`math.isqrt`.
+
+
+Motivation
+==========
+
+The :external+py3.14:mod:`math` documentaton 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 more
+harder to describe module scope, content and interfaces (e.g. returned
+values).
+
+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`.  Lets make same for integer-related
+functions.
+
+
+Specification
+=============
+
+The PEP propose moving functions for integers (now placed in subsection
+"Number-theoretic functions" [1]_) to a separate module, called `imath`.  As
+maintaining backward-compatible aliases in the :external+py3.14:mod:`math`
+module is not a problem --- they only soft-deprecated.
+
+Possible extensions for the new module and it's scope are discussed in the
+Open Issues section.
+
+
+Backwards Compatibility
+=======================
+
+No code breaks expected.
+
+
+Reference Implementation
+========================
+
+TBD
+
+
+Open Issues
+===========
+
+Module name
+-----------
+
+Another variants for name: `ntheory` (like SymPy's submodule), `intmath`.
+
+Possible renaming of isqrt
+--------------------------
+
+As there is no clash with floating-point version, it could be renamed to `sqrt`
+(Java-like).
+
+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.
+
+Among proposed in the initial discussion thread:
+
+* ``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 logarihm, 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()``.
+
+
+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
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.