diff --git a/peps/pep-0791.rst b/peps/pep-0791.rst index aea9a6669d3..094cef02d09 100644 --- a/peps/pep-0791.rst +++ b/peps/pep-0791.rst @@ -8,7 +8,6 @@ Type: Standards Track Created: 12-May-2025 Python-Version: 3.15 Post-History: `12-Jul-2018 `__, - 02-Jun-2019, `09-May-2025 `__, `19-May-2025 `__, @@ -38,7 +37,10 @@ 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 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`. +Which content, as in beginning, will be again related to work with "just +numbers" --- that for most people with basic education means some model of real +numbers). 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,6 +54,29 @@ 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 +`_, +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") and we can accurately describe input/output for each function. + +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 @@ -131,6 +156,10 @@ interval math or numerical integration. Other proposed names include ``ntheory`` (like SymPy's submodule), ``integermath`` and ``imaths``. +As a variant, the new module can be added as a submodule of the +:external+py3.14:mod:`math`. The main module itself will preserve a "catch-all" +role for mathematics in the stdlib. + Module scope and possible extensions ------------------------------------