From d72681fc4595b7b58e087655bc46b43122eb17c8 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 21 May 2025 07:22:39 +0300 Subject: [PATCH 01/12] PEP 791: address PEP review comments * add submodule variant --- peps/pep-0791.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index aea9a6669d3..bb044c6b794 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -131,6 +131,10 @@ interval math or numerical integration. Other proposed names include ``ntheory`` (like SymPy's submodule), ``integermath`` and ``imaths``. +As a variant, new module can be added as a submodule of the +:external+py3.14:mod:`math`. The main module itself will preserve "catch-all" +role for mathematics in the stdlib. + Module scope and possible extensions ------------------------------------ From 5d3c1290208491c07b7d947dabd2da4422fc9465 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 24 May 2025 09:06:13 +0300 Subject: [PATCH 02/12] add Rationale section --- peps/pep-0791.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index bb044c6b794..16a8bff2765 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -54,6 +54,22 @@ simple wrapper to the ``libm``, as most functions in the :external+py3.14:mod:`math` module. +Rationale +========= + +Why not fix the :external+py3.14:mod:`math` module documentation instead? +Sure, we can be much more vague in the module preamble (i.e. roughly say +that "the :external+py3.14:mod:`math` module contains some mathematical +functions") and we can accurately describe input/output for each function. + +But the major issue is that current module mix different, almost non-interlaced +application domains. Adding more documentation will just highlight this and +make the issue worse for end users (more stuff to read/skip). And it will not +fix issue with discoverability (to know in which module to find a function, and +that it can be found at all, you need to look at all the functions in the +module), nor with tab-completion. + + Specification ============= From 8cdce7a94481f6fbfcb08c979092d9c0d2162fd0 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 24 May 2025 09:12:48 +0300 Subject: [PATCH 03/12] expand Motivation --- peps/pep-0791.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 16a8bff2765..d7383047254 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -38,7 +38,10 @@ subsection of the documentation return a float, but the documentation doesn't say so. In the documentation for the proposed ``imath`` module the sentence "All return values are integers." would be accurate. In a similar way we can simplify the description of the accepted arguments for functions in both the -:external+py3.14:mod:`math` and the new module. +new module and the :external+py3.14:mod:`math`. +Which content, as in beginning, will be again related to work with "just +numbers" --- that for most people with basic education means some model of real +numbers). Apparently, the :external+py3.14:mod:`math` module can't serve as a catch-all place for mathematical functions since we also have the :external+py3.14:mod:`cmath` and @@ -52,6 +55,14 @@ Currently the :external+py3.14:mod:`math` module code in the CPython is around comparable with the :external+py3.14:mod:`cmath` (1340LOC), which is *not* a simple wrapper to the ``libm``, as most functions in the :external+py3.14:mod:`math` module. +And this situation tends to be worse. When the module split `was first +proposed +`_, +there were only two integer-related functions: +:external+py3.14:func:`~math.factorial` and :external+py3.14:func:`~math.gcd`. +Now there are six, :external+py3.14:func:`~math.factorial` doesn't accept +:class:`float`'s anymore and :external+py3.14:func:`~math.gcd` changed it's +signature. Rationale From 58a6938b1a35c3829a8ab19f61e71681e6afd55a Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 24 May 2025 11:10:35 +0300 Subject: [PATCH 04/12] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- peps/pep-0791.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index d7383047254..7436311e80d 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -38,7 +38,7 @@ subsection of the documentation return a float, but the documentation doesn't say so. In the documentation for the proposed ``imath`` module the sentence "All return values are integers." would be accurate. In a similar way we can simplify the description of the accepted arguments for functions in both the -new module and the :external+py3.14:mod:`math`. +new module and in :external+py3.14:mod:`math`. Which content, as in beginning, will be again related to work with "just numbers" --- that for most people with basic education means some model of real numbers). @@ -55,7 +55,7 @@ Currently the :external+py3.14:mod:`math` module code in the CPython is around comparable with the :external+py3.14:mod:`cmath` (1340LOC), which is *not* a simple wrapper to the ``libm``, as most functions in the :external+py3.14:mod:`math` module. -And this situation tends to be worse. When the module split `was first +And this situation tends to get worse. When the module split `was first proposed `_, there were only two integer-related functions: @@ -73,9 +73,9 @@ Sure, we can be much more vague in the module preamble (i.e. roughly say that "the :external+py3.14:mod:`math` module contains some mathematical functions") and we can accurately describe input/output for each function. -But the major issue is that current module mix different, almost non-interlaced +But the major issue is that the current module mixes different, almost non-interlaced application domains. Adding more documentation will just highlight this and -make the issue worse for end users (more stuff to read/skip). And it will not +make the issue worse for end users (more text to read/skip). And it will not fix issue with discoverability (to know in which module to find a function, and that it can be found at all, you need to look at all the functions in the module), nor with tab-completion. @@ -158,8 +158,8 @@ interval math or numerical integration. Other proposed names include ``ntheory`` (like SymPy's submodule), ``integermath`` and ``imaths``. -As a variant, new module can be added as a submodule of the -:external+py3.14:mod:`math`. The main module itself will preserve "catch-all" +As a variant, the new module can be added as a submodule of the +:external+py3.14:mod:`math`. The main module itself will preserve a "catch-all" role for mathematics in the stdlib. From 64e2db3b569c6e7b2cae03b01d8e36786aec2dba Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 24 May 2025 11:19:08 +0300 Subject: [PATCH 05/12] address review: -gcd() --- peps/pep-0791.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 7436311e80d..c99a71e07f8 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -60,9 +60,8 @@ proposed `_, there were only two integer-related functions: :external+py3.14:func:`~math.factorial` and :external+py3.14:func:`~math.gcd`. -Now there are six, :external+py3.14:func:`~math.factorial` doesn't accept -:class:`float`'s anymore and :external+py3.14:func:`~math.gcd` changed it's -signature. +Now there are six and :external+py3.14:func:`~math.factorial` doesn't accept +:class:`float`'s anymore. Rationale From 919f797ce9baeec1492e212fb4d995fe64bfa364 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 24 May 2025 11:20:50 +0300 Subject: [PATCH 06/12] address review: -02-Jun-2019 in metadata --- peps/pep-0791.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index c99a71e07f8..094cef02d09 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -8,7 +8,6 @@ Type: Standards Track Created: 12-May-2025 Python-Version: 3.15 Post-History: `12-Jul-2018 `__, - 02-Jun-2019, `09-May-2025 `__, `19-May-2025 `__, From 656d55ae5be5600428468293bbee21b9ec43a9d8 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 28 May 2025 07:35:06 +0300 Subject: [PATCH 07/12] address review: remove sentences --- peps/pep-0791.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 094cef02d09..f35a0a0cdcd 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -38,9 +38,6 @@ documentation doesn't say so. In the documentation for the proposed ``imath`` m return values are integers." would be accurate. In a similar way we can simplify the description of the accepted arguments for functions in both the new module and in :external+py3.14:mod:`math`. -Which content, as in beginning, will be again related to work with "just -numbers" --- that for most people with basic education means some model of real -numbers). Apparently, the :external+py3.14:mod:`math` module can't serve as a catch-all place for mathematical functions since we also have the :external+py3.14:mod:`cmath` and @@ -157,8 +154,7 @@ Other proposed names include ``ntheory`` (like SymPy's submodule), ``integermath`` and ``imaths``. As a variant, the new module can be added as a submodule of the -:external+py3.14:mod:`math`. The main module itself will preserve a "catch-all" -role for mathematics in the stdlib. +:external+py3.14:mod:`math`. Module scope and possible extensions From dfee009083a46b35a135c56153c372364b6617ad Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 28 May 2025 07:39:06 +0300 Subject: [PATCH 08/12] mention gmpy2 --- peps/pep-0791.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index f35a0a0cdcd..053ffedf029 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -183,6 +183,9 @@ Some possible additions, among those proposed in the initial discussion thread `python/cpython#120950 `_. * ``fibonacci()`` --- `Fibonacci sequence `_. +When proposed function already exists in the :pypi:`gmpy2`, we should prefer a +compatible interface for the stdlib. + Rejected ideas ============== From 0ab65576283f232a4c75f0097c85ee02a628e62a Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 28 May 2025 13:35:40 +0300 Subject: [PATCH 09/12] address review: more submodule/module variants --- peps/pep-0791.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 053ffedf029..32a942570f6 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -151,10 +151,10 @@ 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``. +``integermath``, ``zmath``, ``dmath`` and ``imaths``. As a variant, the new module can be added as a submodule of the -:external+py3.14:mod:`math`. +:external+py3.14:mod:`math` (e.g. ``integer``, ``discrete`` or ``ntheory``). Module scope and possible extensions From a47852e8f81dbdf41a73a9fe7400928db1a31b99 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 29 May 2025 10:46:33 +0300 Subject: [PATCH 10/12] expand Rationale --- peps/pep-0791.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 32a942570f6..6a391c521e5 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -66,7 +66,9 @@ Rationale Why not fix the :external+py3.14:mod:`math` module documentation instead? Sure, we can be much more vague in the module preamble (i.e. roughly say that "the :external+py3.14:mod:`math` module contains some mathematical -functions") and we can accurately describe input/output for each function. +functions"), we can accurately describe input/output for each function +and it's behavior (e.g. whether the :external+py3.14:func:`~math.factorial` +output is exact or not, like e.g. the `scipy.special.factorial `_, per default). But the major issue is that the current module mixes different, almost non-interlaced application domains. Adding more documentation will just highlight this and From 94ccb9f542431a967af58d89826807e114942834 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 29 May 2025 10:58:23 +0300 Subject: [PATCH 11/12] rename module, move "Module name" section --- peps/pep-0791.rst | 48 ++++++++++++++++++++--------------------------- 1 file changed, 20 insertions(+), 28 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 6a391c521e5..f393d6b25a3 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -1,5 +1,5 @@ PEP: 791 -Title: imath --- module for integer-specific mathematics functions +Title: intmath --- module for integer-specific mathematics functions Author: Sergey B Kirpichev Sponsor: Victor Stinner Discussions-To: https://discuss.python.org/t/92548 @@ -34,7 +34,7 @@ when explicitly noted otherwise, all return values are floats." This is no longer true: *None* of the functions listed in the `Number-theoretic functions `_ subsection of the documentation return a float, but the -documentation doesn't say so. In the documentation for the proposed ``imath`` module the sentence "All +documentation doesn't say so. In the documentation for the proposed ``intmath`` module the sentence "All return values are integers." would be accurate. In a similar way we can simplify the description of the accepted arguments for functions in both the new module and in :external+py3.14:mod:`math`. @@ -82,7 +82,7 @@ Specification ============= The PEP proposes moving the following integer-related functions to a new -module, called ``imath``: +module, called ``intmath``: * :external+py3.14:func:`~math.comb` * :external+py3.14:func:`~math.factorial` @@ -134,31 +134,6 @@ Reference Implementation Open Issues =========== -Module name ------------ - -The chosen name seems consistent with one existing domain-specific mathematical module: -:external+py3.14:mod:`cmath` (for complex numbers). - -We note the `Imath -`_ C++ library includes -Python bindings with the same name. There is also an :pypi:`imath` project on -PyPI, but only with two releases, with the most recent one four years ago. Its -repository is no longer accessible. - -`Polling showed `_ ``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``, ``zmath``, ``dmath`` and ``imaths``. - -As a variant, the new module can be added as a submodule of the -:external+py3.14:mod:`math` (e.g. ``integer``, ``discrete`` or ``ntheory``). - - Module scope and possible extensions ------------------------------------ @@ -192,6 +167,23 @@ compatible interface for the stdlib. Rejected ideas ============== +Module name +----------- + +`Polling showed `_ ``intmath`` as most +popular candidate with ``imath`` as a second winner. + +Other proposed names include ``ntheory`` (like SymPy's submodule), +``integermath``, ``zmath``, ``dmath`` and ``imaths``. + +As a variant, the new module can be added as a submodule of the +:external+py3.14:mod:`math`: ``integer`` (most preferred), ``discrete`` +or ``ntheory``. + + +:external+py3.14:func:`~math.isqrt` renaming +--------------------------------------------- + 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`` From ae03c4ba5660b85409408f3c79f29359c0f494b0 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 3 Jun 2025 13:53:12 +0300 Subject: [PATCH 12/12] Disband "Open Issues" --- peps/pep-0791.rst | 69 +++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 36 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index f393d6b25a3..a12efe22d51 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -51,6 +51,7 @@ Currently the :external+py3.14:mod:`math` module code in the CPython is around comparable with the :external+py3.14:mod:`cmath` (1340LOC), which is *not* a simple wrapper to the ``libm``, as most functions in the :external+py3.14:mod:`math` module. + And this situation tends to get worse. When the module split `was first proposed `_, @@ -59,6 +60,23 @@ there were only two integer-related functions: Now there are six and :external+py3.14:func:`~math.factorial` doesn't accept :class:`float`'s anymore. +Some possible additions, among those proposed in the initial discussion thread +and issue +`python/cpython#81313 `_ are: + +* ``ceil_div()`` --- for integer ceiling divide, see + `relevant discussion thread `_. +* ``gcdext()`` --- to solve linear `Diophantine equation `_ in two variables (the + :external+py3.14:class:`int` implementation actually includes an extended + Euclidean algorithm) +* ``isqrt_rem()`` --- to return both an integer square root and a remainder (which is non-zero only if + the integer isn't a perfect square) +* ``ilog()`` --- integer logarithm, :external+py3.14:func:`math.log` + has special handling for integer arguments. It's unique (with respect to other module + functions) and not documented so far, see issue + `python/cpython#120950 `_. +* ``fibonacci()`` --- `Fibonacci sequence `_. + Rationale ========= @@ -98,9 +116,21 @@ Module functions will accept integers and objects that implement the object to an integer number. Suitable functions must be computed exactly, given sufficient time and memory. -Possible extensions for the new module and its scope are discussed in the -`Open Issues `_ section. New functions are not part of this -proposal. + +Possible Extensions +=================== + +New functions (like mentioned in `Motivation `_ section) are not +part of this proposal. + +Though, we should mention that, 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, as +production-quality implementatons will require a decent mathematical background +from contributors and belongs rather to specialized libraries. + +When proposed function already exists in the :pypi:`gmpy2`, we should prefer a +compatible interface for the stdlib. Backwards Compatibility @@ -131,39 +161,6 @@ Reference Implementation `python/cpython#133909 `_ -Open Issues -=========== - -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, as production-quality implementatons will require a -decent mathematical background from contributors and belongs rather to -specialized libraries. - -Some possible additions, among those proposed in the initial discussion thread -(see also issue -`python/cpython#81313 `_): - -* ``ceil_div()`` --- for integer ceiling divide, see - `relevant discussion thread `_. -* ``gcdext()`` --- to solve linear `Diophantine equation `_ in two variables (the - :external+py3.14:class:`int` implementation actually includes an extended - Euclidean algorithm) -* ``isqrt_rem()`` --- to return both an integer square root and a remainder (which is non-zero only if - the integer isn't a perfect square) -* ``ilog()`` --- integer logarithm, :external+py3.14:func:`math.log` - has special handling for integer arguments. It's unique (with respect to other module - functions) and not documented so far, see issue - `python/cpython#120950 `_. -* ``fibonacci()`` --- `Fibonacci sequence `_. - -When proposed function already exists in the :pypi:`gmpy2`, we should prefer a -compatible interface for the stdlib. - - Rejected ideas ==============