diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index e9b1726fe75..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 @@ -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 `_. 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 @@ -97,16 +97,23 @@ 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 ========= -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). @@ -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 `_ 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,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. @@ -209,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