diff --git a/peps/pep-9999.rst b/peps/pep-9999.rst new file mode 100644 index 00000000000..2146b9f167b --- /dev/null +++ b/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 `__, + `09-May-2025 `__ + + +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.