PEP 791: edits (address SC feedback) (#4639)

* New namespace avoid name clash with existing math's stuff
* Mention pitfails of c_div() implementation
* Clarify what IDE means
* Rephrase Rationale
* intmath -> math.integer

Author: skirpichev

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 <skirpichev@gmail.com>
 Sponsor: Victor Stinner <vstinner@python.org>
 Discussions-To: https://discuss.python.org/t/92548
@@ -15,9 +15,9 @@ Post-History: `12-Jul-2018 <https://mail.python.org/archives/list/python-ideas@p
 Abstract
 ========
 
-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`.
+This PEP proposes a new submodule 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`.
 
 
 Motivation
@@ -34,10 +34,10 @@ 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 ``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
@@ -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
@@ -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 <https://discuss.python.org/t/91269>`_.  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
   <https://en.wikipedia.org/wiki/Diophantine_equation>`_ in two variables (the
   :external+py3.14:class:`int` implementation actually includes an extended
@@ -97,16 +97,23 @@ and issue `python/cpython#81313
 * ``fibonacci()`` --- `Fibonacci sequence
   <https://en.wikipedia.org/wiki/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 <https://discuss.python.org/t/91269/6>`_).
+
 
 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
 <https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.factorial.html#scipy.special.factorial>`_,
 per default).
 
@@ -122,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`
@@ -140,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
@@ -150,7 +157,7 @@ New functions (like mentioned in `Motivation <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.
@@ -169,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
@@ -200,18 +207,18 @@ 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 <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`` (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