From 849338f9d4d5fdbc355c82496aa0f5eaa81ca9c7 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 10 May 2025 08:05:05 +0300 Subject: [PATCH 01/20] PEP 791: imath --- module for number-theoretic functions --- .github/CODEOWNERS | 1 + peps/pep-0791.rst | 165 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+) create mode 100644 peps/pep-0791.rst diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a4254d43e5a..0062df25475 100644 --- a/.github/CODEOWNERS +++ b/.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 # ... diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst new file mode 100644 index 00000000000..eae8606f1a7 --- /dev/null +++ b/peps/pep-0791.rst @@ -0,0 +1,165 @@ +PEP: 791 +Title: imath --- module for number-theoretic functions +Author: Sergey B Kirpichev +Sponsor: Victor Stinner +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 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 `_ 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 `_ C++ library +include Python bindings with same name. + +`Polling shows `_ ``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. From 8e04e48d4030102049b5084ea6553cee9e388f2b Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 12 May 2025 09:58:50 +0300 Subject: [PATCH 02/20] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- peps/pep-0791.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index eae8606f1a7..9865b7e0197 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -5,7 +5,7 @@ Sponsor: Victor Stinner Discussions-To: Pending Status: Draft Type: Standards Track -Created: 10-May-2025 +Created: 12-May-2025 Python-Version: 3.15 Post-History: 02-Jun-2019, `09-May-2025 `__, @@ -64,7 +64,7 @@ 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 +Possible extensions for the new module and its scope are discussed in the `Open Issues `_ section. New functions are not part of the proposal. @@ -72,7 +72,7 @@ proposal. Backwards Compatibility ======================= -As aliases in :external+py3.14:mod:`math` will be kept for indefinite time +As aliases in :external+py3.14:mod:`math` will be kept for an indefinite time (their use would be discouraged), there are no anticipated code breaks. @@ -92,9 +92,9 @@ 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 most recent one four years ago. Its repository is no longer accessible. The `Imath `_ C++ library -include Python bindings with same name. +include Python bindings with the same name. `Polling shows `_ ``intmath`` as another popular name. The argument made was that the normal mathematical spelling of @@ -118,12 +118,12 @@ There are possible additions, 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 + :external+py3.14:class:`int` implementation actually includes an 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 +* ``ilog()`` --- integer logarithm, :external+py3.14:func:`math.log` + has a special handling for integer arguments. It's unique (with respect to other module functions) and not documented so far, see [4]_ * ``fibonacci()``. From 0245fda0c8bd7391264650dfc6990cba443883c9 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 12 May 2025 10:11:23 +0300 Subject: [PATCH 03/20] address review: disband References (inline them) --- peps/pep-0791.rst | 30 +++++++++++------------------- 1 file changed, 11 insertions(+), 19 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 9865b7e0197..89d964a00c5 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -30,8 +30,9 @@ 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 +longer true: *None* of the functions listed in the `Number-theoretic +functions `_ +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 @@ -48,7 +49,7 @@ grouping related functions and IDEs suggesting helpful completions. Specification ============= -The PEP proposes moving the following integer-related functions [1]_ in a new +The PEP proposes moving the following integer-related functions in a new module, called ``imath``: * :external+py3.14:func:`~math.comb` @@ -114,9 +115,11 @@ 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]_): +(see also issue +`python/cpython#81313 `_): -* ``c_div()`` --- for integer ceiling divide, see [2]_, [3]_. +* ``c_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) @@ -124,8 +127,9 @@ There are possible additions, among proposed in the initial discussion thread integer isn't a perfect square) * ``ilog()`` --- integer logarithm, :external+py3.14:func:`math.log` has a special handling for integer arguments. It's unique (with respect to other module - functions) and not documented so far, see [4]_ -* ``fibonacci()``. + functions) and not documented so far, see issue + `python/cpython#120950 `_. + * ``fibonacci()``. Rejected ideas @@ -146,18 +150,6 @@ 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 ========= From 13f82ade512d30ec1b58529cb984ef9de56a09d5 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 12 May 2025 11:27:09 +0300 Subject: [PATCH 04/20] Apply suggestions from code review Co-authored-by: Victor Stinner --- .github/CODEOWNERS | 2 +- peps/pep-0791.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0062df25475..7421c4de20d 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -669,7 +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-0791.rst @skirpichev @vstinner # ... peps/pep-0801.rst @warsaw # ... diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 89d964a00c5..f2f414c7489 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -111,7 +111,7 @@ 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 +like the GMP, the module scope should be limited. For example, no efficient primality testing and factorization. There are possible additions, among proposed in the initial discussion thread @@ -120,7 +120,7 @@ There are possible additions, among proposed in the initial discussion thread * ``c_div()`` --- for integer ceiling divide, see `relevant discussion thread `_. -* ``gcdext()`` --- to solve linear Diophantine equation in two variables (the +* ``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 integer square root and a remainder (if @@ -129,7 +129,7 @@ There are possible additions, among proposed in the initial discussion thread has a 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()`` --- `Fibonacci sequence `_. Rejected ideas From f92dc1b0e84d7fa587312026690e49ffb41583d1 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 12 May 2025 11:27:36 +0300 Subject: [PATCH 05/20] address review: add old discussion link --- peps/pep-0791.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index f2f414c7489..27f5ef606fe 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -7,7 +7,8 @@ Status: Draft Type: Standards Track Created: 12-May-2025 Python-Version: 3.15 -Post-History: 02-Jun-2019, +Post-History: `12-Jul-2018 `__, + 02-Jun-2019, `09-May-2025 `__, From 549ca1a4bfbd93a588887a944e9acc673df1ea52 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 12 May 2025 13:02:07 +0300 Subject: [PATCH 06/20] address review: c_div naming --- peps/pep-0791.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 27f5ef606fe..4812b8f37b3 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -119,7 +119,7 @@ There are possible additions, among proposed in the initial discussion thread (see also issue `python/cpython#81313 `_): -* ``c_div()`` --- for integer ceiling divide, see +* ``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 From b5ff41bd1eaa3ab2bb717e2e7a9c1f9b0a787223 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 12 May 2025 13:27:33 +0300 Subject: [PATCH 07/20] address review: grammar nits --- 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 4812b8f37b3..914ff05eedb 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -24,24 +24,24 @@ 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 +to the mathematical functions defined by the C standard." But, +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 +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 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 +can simplify the description of the accepted arguments for functions in 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 +the :external+py3.14:mod:`statistics`. Let's do the 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. @@ -62,7 +62,7 @@ module, called ``imath``: Their aliases in :external+py3.14:mod:`math` will be :term:`soft deprecated`. -Modules functions will accept integers and objects that implement the +Module 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. From 1013832f1e214fba54df98e660e5bc7219ccf41b Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 12 May 2025 17:48:48 +0300 Subject: [PATCH 08/20] Apply suggestions from code review Co-authored-by: Hood Chatham Co-authored-by: Mikhail Efimov --- peps/pep-0791.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 914ff05eedb..900f52daecc 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -34,23 +34,23 @@ 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 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 +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. -Apparently, the :external+py3.14:mod:`math` can't serve as a catch-all place +Apparently, the :external+py3.14:mod:`math` module 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 do the same for integer-related -functions. It would provide shared context, which reduces verbosity in the +:external+py3.14:mod:`statistics` modules. Let's do the same for integer-related +functions. It provides shared context, which reduces verbosity in the documentation and conceptual load. It also aids discoverability through -grouping related functions and IDEs suggesting helpful completions. +grouping related functions and makes IDE suggestions more helpful. Specification ============= -The PEP proposes moving the following integer-related functions in a new +The PEP proposes moving the following integer-related functions to a new module, called ``imath``: * :external+py3.14:func:`~math.comb` @@ -63,11 +63,11 @@ module, called ``imath``: Their aliases in :external+py3.14:mod:`math` will be :term:`soft deprecated`. Module functions will accept integers and objects that implement the -:external+py3.14:meth:`~object.__index__` method which is used to convert 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 its scope are discussed in the -`Open Issues `_ section. New functions are not part of the +`Open Issues `_ section. New functions are not part of this proposal. @@ -90,7 +90,7 @@ Open Issues Module name ----------- -Chosen name seems consistent with other domain-specific mathematical module: +The chosen name seems consistent with one existing 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 @@ -100,7 +100,7 @@ include Python bindings with the same name. `Polling shows `_ ``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 +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. @@ -115,7 +115,7 @@ Unless we can just provide bindings to some well supported mathematical library like the GMP, the module scope should be limited. For example, no efficient primality testing and factorization. -There are possible additions, among proposed in the initial discussion thread +Some possible additions, among those proposed in the initial discussion thread (see also issue `python/cpython#81313 `_): @@ -124,10 +124,10 @@ There are possible additions, among proposed in the initial 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 integer square root and a remainder (if +* ``isqrt_rem()`` --- to return both integer square root and a remainder (which is non-zero only if integer isn't a perfect square) * ``ilog()`` --- integer logarithm, :external+py3.14:func:`math.log` - has a special handling for integer arguments. It's unique (with respect to other module + 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 `_. @@ -146,8 +146,8 @@ 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 +Thanks to Tim Peters for reviving the idea of splitting the :external+py3.14:mod:`math` +module. Thanks to Neil Girdhar for substantial improvements of the initial draft. From 1b19066f7f5c0b06abe2b3c2fedad5d8d8f31405 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 13 May 2025 08:59:36 +0300 Subject: [PATCH 09/20] address review: re-arrange Imath note --- peps/pep-0791.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 900f52daecc..00e170d24cf 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -93,10 +93,11 @@ Module name The chosen name seems consistent with one existing 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 four years ago. Its repository is no longer accessible. -The `Imath `_ C++ library -include Python bindings with the same name. +We should note, that the `Imath +`_ C++ library include +Python bindings with the same name. There is also an ``imath`` project on +PyPI, but only with two releases, with the most recent one four years ago. Its +repository is no longer accessible. `Polling shows `_ ``intmath`` as another popular name. The argument made was that the normal mathematical spelling of From 5054afb15d77525ba271a2c7d041b4ad98c65bf0 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 13 May 2025 09:18:46 +0300 Subject: [PATCH 10/20] address review: rework note about primality testing, etc --- peps/pep-0791.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 00e170d24cf..5a40f634307 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -113,8 +113,10 @@ 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 efficient primality -testing and factorization. +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 From d7b3aec9b86e1025ef3ba2e33be8029c286d7fcc Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 13 May 2025 10:25:12 +0300 Subject: [PATCH 11/20] address review: add "How to Teach This" --- peps/pep-0791.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 5a40f634307..15ca950b4fd 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -78,6 +78,21 @@ As aliases in :external+py3.14:mod:`math` will be kept for an indefinite time (their use would be discouraged), there are no anticipated code breaks. +How to Teach This +================= + +The new module will be a place to functions, that 1) accept +:external+py3.14:class:`int`-like arguments and return also integers, 2) are +also in the field of arbitrary-precision integer arithmetic, i.e. have no +dependence on the platform floating-point format or behaviour and/or on the +platorm math library (``libm``). + +For users it would be natural first to look on the +:external+py3.14:class:`int`'s methods, which cover most basic use-cases (e.g. +:external+py3.14:meth:`int.bit_length` method), than to some dedicated place in +the stdlib. + + Reference Implementation ======================== From 37e3001b5d7b46f80c42da0e6c1286224f1b9ae7 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 13 May 2025 11:03:09 +0300 Subject: [PATCH 12/20] Apply suggestions from code review Co-authored-by: Mikhail Efimov --- 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 15ca950b4fd..7ff7d65e440 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -84,8 +84,8 @@ How to Teach This The new module will be a place to functions, that 1) accept :external+py3.14:class:`int`-like arguments and return also integers, 2) are also in the field of arbitrary-precision integer arithmetic, i.e. have no -dependence on the platform floating-point format or behaviour and/or on the -platorm math library (``libm``). +dependency on the platform floating-point format or behaviour and/or on the +platform math library (``libm``). For users it would be natural first to look on the :external+py3.14:class:`int`'s methods, which cover most basic use-cases (e.g. From eac5a4a6375874bba9a6ff1f5944a1bfa0b508a0 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 13 May 2025 20:05:04 +0300 Subject: [PATCH 13/20] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@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 7ff7d65e440..64c003b9555 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -33,7 +33,7 @@ For example, the :external+py3.14:mod:`math` module documentation says: "Except 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 returns a float, but the +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 @@ -96,7 +96,7 @@ the stdlib. Reference Implementation ======================== -https://github.com/python/cpython/pull/133909 +`python/cpython#133909 `_ Open Issues @@ -109,12 +109,12 @@ The chosen name seems consistent with one existing domain-specific mathematical :external+py3.14:mod:`cmath` (for complex numbers). We should note, that the `Imath -`_ C++ library include +`_ C++ library includes Python bindings with the same name. There is also an ``imath`` project on PyPI, but only with two releases, with the most recent one four years ago. Its repository is no longer accessible. -`Polling shows `_ ``intmath`` as another +`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 @@ -142,8 +142,8 @@ Some possible additions, among those proposed in the initial 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 integer square root and a remainder (which is non-zero only if - integer isn't a perfect square) +* ``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 From c4857e3ba4e48ded1ef7db14c0583a986981109a Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 13 May 2025 20:33:04 +0300 Subject: [PATCH 14/20] address review: link to imath --- peps/pep-0791.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 64c003b9555..9a28509b6f2 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -110,7 +110,7 @@ The chosen name seems consistent with one existing domain-specific mathematical We should note, that the `Imath `_ C++ library includes -Python bindings with the same name. There is also an ``imath`` project on +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. From 341e1fc42ca5fa49257256aa24156de564804ebf Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 13 May 2025 21:10:16 +0300 Subject: [PATCH 15/20] address review: change title --- peps/pep-0791.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 9a28509b6f2..9b32b93b13f 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -1,5 +1,5 @@ PEP: 791 -Title: imath --- module for number-theoretic functions +Title: imath --- module for integer-specific mathematics functions Author: Sergey B Kirpichev Sponsor: Victor Stinner Discussions-To: Pending From 01017e3fe00b7404f13efdba415b1c3d98e79726 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 14 May 2025 09:01:00 +0300 Subject: [PATCH 16/20] address review by tim-one (and maybe mdickinson) --- 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 9b32b93b13f..9f1f59ffb9f 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -16,9 +16,11 @@ Abstract ======== This PEP proposes a new module for number-theoretical, combinatorial and other -integer-valued functions defined for integer arguments, like +functions defined for integer arguments, like :external+py3.14:func:`math.gcd` or :external+py3.14:func:`math.isqrt`. +Suitable functions must be computed exactly, given sufficient time and memory. + Motivation ========== From 11b5d7fde2c6de91cbbddafee7290b86dbb9aa63 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 14 May 2025 11:01:46 +0300 Subject: [PATCH 17/20] Include argument from the d.p.o thread --- peps/pep-0791.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 9f1f59ffb9f..82e2ca5402c 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -48,6 +48,12 @@ functions. It provides shared context, which reduces verbosity in the documentation and conceptual load. It also aids discoverability through grouping related functions and makes IDE suggestions more helpful. +Currently the :external+py3.14:mod:`math` module code in the CPython is around +4200LOC, from which the new module code is roughly 1/3 (1300LOC). This is +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. + Specification ============= From cc29b813ac18d12f2a98c1f8f64d0c2659106573 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 14 May 2025 17:05:19 +0200 Subject: [PATCH 18/20] Update .github/CODEOWNERS Co-authored-by: Sergey B Kirpichev --- .github/CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7421c4de20d..0062df25475 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -669,7 +669,7 @@ peps/pep-0788.rst @ZeroIntensity @vstinner # ... peps/pep-0789.rst @njsmith peps/pep-0790.rst @hugovk -peps/pep-0791.rst @skirpichev @vstinner +peps/pep-0791.rst @vstinner # ... peps/pep-0801.rst @warsaw # ... From ffe9e8ee6ac6675f5f84ec18224ac346b650ec0e Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 14 May 2025 18:50:54 +0300 Subject: [PATCH 19/20] Apply suggestions from code review Co-authored-by: Neil Girdhar --- peps/pep-0791.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index 82e2ca5402c..58d913ef8ad 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -42,7 +42,7 @@ can simplify the description of the accepted arguments for functions in both the :external+py3.14:mod:`math` and the new module. Apparently, the :external+py3.14:mod:`math` module can't serve as a catch-all place -for mathematical functions: we have also the :external+py3.14:mod:`cmath` and +for mathematical functions since we also have the :external+py3.14:mod:`cmath` and :external+py3.14:mod:`statistics` modules. Let's do the same for integer-related functions. It provides shared context, which reduces verbosity in the documentation and conceptual load. It also aids discoverability through @@ -89,8 +89,8 @@ As aliases in :external+py3.14:mod:`math` will be kept for an indefinite time How to Teach This ================= -The new module will be a place to functions, that 1) accept -:external+py3.14:class:`int`-like arguments and return also integers, 2) are +The new module will be a place for functions, that 1) accept +:external+py3.14:class:`int`-like arguments and also return integers, and 2) are also in the field of arbitrary-precision integer arithmetic, i.e. have no dependency on the platform floating-point format or behaviour and/or on the platform math library (``libm``). @@ -116,7 +116,7 @@ Module name The chosen name seems consistent with one existing domain-specific mathematical module: :external+py3.14:mod:`cmath` (for complex numbers). -We should note, that the `Imath +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 From ad587abbf809f3d2451ccf8272ea9d5e929130d7 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 14 May 2025 19:00:54 +0300 Subject: [PATCH 20/20] address review: move part of Abstract to the Specification --- 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 58d913ef8ad..ce663dba9e5 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -19,8 +19,6 @@ This PEP proposes a new module for number-theoretical, combinatorial and other functions defined for integer arguments, like :external+py3.14:func:`math.gcd` or :external+py3.14:func:`math.isqrt`. -Suitable functions must be computed exactly, given sufficient time and memory. - Motivation ========== @@ -72,7 +70,8 @@ Their aliases in :external+py3.14:mod:`math` will be :term:`soft deprecated`. Module 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. +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