From 4949f85c2d85bae5d20263b205116ff8d83c6149 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 7 Oct 2025 08:14:48 +0300 Subject: [PATCH 1/5] New namespace avoid name clash with existing math's stuff --- peps/pep-0791.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index e9b1726fe75..900264078e1 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -97,6 +97,13 @@ and issue `python/cpython#81313 * ``fibonacci()`` --- `Fibonacci sequence `_. +Separated namespace eliminates possible name clash with existing +:external+py3.14:mod:`math`'s module functions. For example, possible names +``ceil_div()`` or ``ceildiv()`` for integer ceiling division will interfere +with the :external+py3.14:func:`~math.ceil` (which is for :class:`float`'s and +*sometimes* does right things for integer division, as an accident --- but +`usually not `_). + Rationale ========= From 008ba3a3c20ec4d79e3fec5f6f55edbd6ca02aab Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Tue, 7 Oct 2025 08:17:10 +0300 Subject: [PATCH 2/5] Mention pitfails of c_div() implementation --- 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 900264078e1..87e7bd27d76 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -81,8 +81,8 @@ and issue `python/cpython#81313 * ``c_div()`` and ``n_div()`` --- for integer division with rounding towards positive infinity (ceiling divide) and to the nearest integer, see `relevant discussion thread `_. This is reinvented - several times in the stdlib, e.g. in :mod:`datetime` and - :mod:`fractions`. + several times in the stdlib, e.g. in :mod:`datetime` and :mod:`fractions`. + And it's easy to do this wrongly, as demonstrated by the thread. * ``gcdext()`` --- to solve linear `Diophantine equation `_ in two variables (the :external+py3.14:class:`int` implementation actually includes an extended From 3054b20af79188d85c8260f38e980c1b6730b46d Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 8 Oct 2025 05:41:52 +0300 Subject: [PATCH 3/5] Clarify what IDE means --- 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 87e7bd27d76..7ef706cbeed 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -50,8 +50,8 @@ place 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 grouping related functions and makes IDE suggestions -more helpful. +discoverability through grouping related functions and makes IDE (e.g. new +CPython's REPL) 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 From 48caa4bdfb201aba303b43c51f87c256ab1c531e Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 10 Oct 2025 17:24:50 +0300 Subject: [PATCH 4/5] Rephrase Rationale --- 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 7ef706cbeed..44600f7286c 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -108,12 +108,12 @@ with the :external+py3.14:func:`~math.ceil` (which is for :class:`float`'s and 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"), -we can accurately describe input/output for each function and its behavior -(e.g. whether the :external+py3.14:func:`~math.factorial` output is exact or -not, like the `scipy.special.factorial +Is this all about documentation, why not fix it instead? No, it isn't. 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"), we +can accurately describe input/output for each function and its behavior (e.g. +whether the :external+py3.14:func:`~math.factorial` output is exact or not, +like the `scipy.special.factorial `_, per default). From 7d26e476cdcef6b2aae35c48970b6c7bd8838301 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 10 Oct 2025 17:43:06 +0300 Subject: [PATCH 5/5] intmath -> math.integer --- 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 44600f7286c..573619bfb56 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -1,5 +1,5 @@ PEP: 791 -Title: intmath --- module for integer-specific mathematics functions +Title: math.integer --- submodule for integer-specific mathematics functions Author: Sergey B Kirpichev Sponsor: Victor Stinner Discussions-To: https://discuss.python.org/t/92548 @@ -15,9 +15,9 @@ Post-History: `12-Jul-2018 `_ subsection of the documentation return a float, but the documentation doesn't -say so. In the documentation for the proposed ``intmath`` module the sentence +say so. In the documentation for the proposed ``math.integer`` submodule 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`. +new submodule and in :external+py3.14:mod:`math`. Now it's a lot harder to satisfy people's expectations about the module content. For example, should they expect that ``math.factorial(100)`` will @@ -129,8 +129,7 @@ Specification ============= The PEP proposes moving the following integer-related functions to a new -module, called ``intmath`` (see `Open Issues`_ for alternatives for -it's name): +submodule, called ``math.integer``: * :external+py3.14:func:`~math.comb` * :external+py3.14:func:`~math.factorial` @@ -147,7 +146,8 @@ 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. -The :pypi:`intmath` package will provide new module for older Python versions. +The :pypi:`intmath` package will provide new submodule content for older Python +versions. Possible Extensions @@ -157,7 +157,7 @@ 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 +well supported mathematical library like the GMP, the submodule 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. @@ -176,7 +176,7 @@ 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 for functions, that 1) accept +The new submodule 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 @@ -207,8 +207,8 @@ 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). -Open Issues -=========== +Module name +----------- `Polling showed `_ ``intmath`` as most popular candidate with ``imath`` as a second winner. @@ -216,9 +216,9 @@ 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`` (author preference). +But the SC prefers a submodule rather than a new top-level module. Most +popular variants of the :external+py3.14:mod:`math`'s submodule are: +``integer``, ``discrete`` or ``ntheory`` (author preference). Acknowledgements