PEP 791: address PEP review comments (part 2)

peps/pep-0791.rst

@@ -39,6 +39,12 @@ 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`.
 
+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
+return an exact answer?  Many languages, Python packages (like :pypi:`scipy`)
+or pocket calculators have functions with same or similar name, that return a
+floating-point value, which is only an approximation in this example.
+
 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
 :external+py3.14:mod:`statistics` modules.  Let's do the same for integer-related
@@ -56,16 +62,26 @@ 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
+:external+py3.14:func:`~math.factorial` (accepting also :class:`float`'s, like other
+functions in the module) and :external+py3.14:func:`~math.gcd` (moved from the
+::external+py3.14:mod:`fractions` module).  Then
+:external+py3.14:func:`~math.isqrt`, :external+py3.14:func:`~math.comb` and
+:external+py3.14:func:`~math.perm` were added, and addition of the new module
+was `proposed second time <https://github.com/python/cpython/issues/81313>`_,
+so all new functions would go directly to it, without littering the
+:external+py3.14:mod:`math` namespace.
+Now there are six functions and :external+py3.14:func:`~math.factorial` doesn't accept
 :class:`float`'s anymore.
 
 Some possible additions, among those proposed in the initial discussion thread
 and issue
 `python/cpython#81313 <https://github.com/python/cpython/issues/81313>`_ are:
 
-* ``ceil_div()`` --- for integer ceiling divide, see
-  `relevant discussion thread <https://discuss.python.org/t/91269>`_.
+* ``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 the :mod:`datetime` and the
+  :mod:`fractions`.
 * ``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
   Euclidean algorithm)
@@ -110,6 +126,7 @@ module, called ``intmath``:
 * :external+py3.14:func:`~math.perm`
 
 Their aliases in :external+py3.14:mod:`math` will be :term:`soft deprecated`.
+This PEP doesn't introduce backward-incompatible changes.
 
 Module functions will accept integers and objects that implement the
 :external+py3.14:meth:`~object.__index__` method, which is used to convert the