From d72681fc4595b7b58e087655bc46b43122eb17c8 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 21 May 2025 07:22:39 +0300 Subject: [PATCH 1/6] 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 2/6] 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 3/6] 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 4/6] 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 5/6] 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 6/6] 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 `__,