PEP 791: address PEP review comments

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 <[email protected]>
 Sponsor: Victor Stinner <[email protected]>
 Discussions-To: https://discuss.python.org/t/92548
@@ -8,7 +8,6 @@ Type: Standards Track
 Created: 12-May-2025
 Python-Version: 3.15
 Post-History: `12-Jul-2018 <https://mail.python.org/archives/list/[email protected]/thread/YYJ5YJBJNCVXQWK5K3WSVNMPUSV56LOR/>`__,
-              02-Jun-2019,
               `09-May-2025 <https://discuss.python.org/t/91337>`__,
               `19-May-2025 <https://discuss.python.org/t/92548>`__,
 
@@ -35,10 +34,10 @@ when explicitly noted otherwise, all return values are floats."  This is no
 longer true:  *None* of the functions listed in the `Number-theoretic
 functions <https://docs.python.org/3.14/library/math.html#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
-:external+py3.14:mod:`math` and the new module.
+new module and in :external+py3.14:mod:`math`.
 
 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,13 +51,38 @@ 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
+<https://mail.python.org/archives/list/[email protected]/thread/YYJ5YJBJNCVXQWK5K3WSVNMPUSV56LOR/>`_,
+there were only two integer-related functions:
+:external+py3.14:func:`~math.factorial` and :external+py3.14:func:`~math.gcd`.
+Now there are six and :external+py3.14:func:`~math.factorial` doesn't accept
+:class:`float`'s anymore.
+
+
+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 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 <https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.factorial.html#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
+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.
 
 
 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`
@@ -110,28 +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
-<https://github.com/AcademySoftwareFoundation/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 <https://discuss.python.org/t/91337/35>`_ ``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
 ------------------------------------
 
@@ -158,10 +160,30 @@ Some possible additions, among those proposed in the initial discussion thread
   `python/cpython#120950 <https://github.com/python/cpython/issues/120950>`_.
 * ``fibonacci()`` --- `Fibonacci sequence <https://en.wikipedia.org/wiki/Fibonacci_sequence>`_.
 
+When proposed function already exists in the :pypi:`gmpy2`, we should prefer a
+compatible interface for the stdlib.
+
 
 Rejected ideas
 ==============
 
+Module name
+-----------
+
+`Polling showed <https://discuss.python.org/t/92548/67>`_ ``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``