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
@@ -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 <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,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