Skip to content

PEP 791: address PEP review comments #4430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
+31 −2
Open

PEP 791: address PEP review comments #4430

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d72681f
PEP 791: address PEP review comments
skirpichev May 21, 2025
5d3c129
add Rationale section
skirpichev May 24, 2025
8cdce7a
expand Motivation
skirpichev May 24, 2025
58a6938
Apply suggestions from code review
skirpichev May 24, 2025
64e2db3
address review: -gcd()
skirpichev May 24, 2025
919f797
address review: -02-Jun-2019 in metadata
skirpichev May 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 31 additions & 2 deletions peps/pep-0791.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ Type: Standards Track
Created: 12-May-2025
Python-Version: 3.15
Post-History: `12-Jul-2018 <https://mail.python.org/archives/list/python-ideas@python.org/thread/YYJ5YJBJNCVXQWK5K3WSVNMPUSV56LOR/>`__,
02-Jun-2019,
`09-May-2025 <https://discuss.python.org/t/91337>`__,
`19-May-2025 <https://discuss.python.org/t/92548>`__,

Expand Down Expand Up @@ -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).
Comment on lines +41 to +43
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels dismissive, can we reword it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any suggestions?

I meant we can't expect advanced math background from average Python users. What they might expect from "just numbers"? They are closed for arithmetic operations (python's int's - aren't), but sometimes not for algebraic (e.g. sqrt(-1)), and they are more than just rational numbers (i.e. sqrt(2)). People also probably aware of decimal floating-point model for real numbers (or at least with fixed-point).


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
Expand All @@ -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
<https://mail.python.org/archives/list/python-ideas@python.org/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
: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
Expand Down Expand Up @@ -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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not convinced by the "catch all" aspect knowing that cmath and statistics will stay outside the math package.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This naming suggests, that new functions (that are not suitable for cmath/statistics/random) will go either to the math module or to some math's submodule.

I think it's an important implication of this naming scheme, i.e. we can't just drop this sentence. But I appreciate any suggestions to reword it.

role for mathematics in the stdlib.


Module scope and possible extensions
------------------------------------
Expand Down