Repository navigation
PEP-791: Add a module for integer related math functions #81313
Description
| BPO | 37132 |
|---|---|
| Nosy | @tim-one, @rhettinger, @mdickinson, @serhiy-storchaka |
| PRs |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2019-06-03.07:13:59.683>
created_at = <Date 2019-06-02.10:54:57.404>
labels = ['3.8', 'type-feature', 'library']
title = 'Add a module for integer related math functions'
updated_at = <Date 2020-05-07.16:27:37.033>
user = 'https://github.com/serhiy-storchaka'bugs.python.org fields:
activity = <Date 2020-05-07.16:27:37.033>
actor = 'mark.dickinson'
assignee = 'none'
closed = True
closed_date = <Date 2019-06-03.07:13:59.683>
closer = 'serhiy.storchaka'
components = ['Library (Lib)']
creation = <Date 2019-06-02.10:54:57.404>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 37132
keywords = ['patch']
message_count = 12.0
messages = ['344269', '344274', '344277', '344279', '344280', '344281', '344283', '344296', '344297', '344381', '344387', '368354']
nosy_count = 5.0
nosy_names = ['tim.peters', 'rhettinger', 'mark.dickinson', 'stutzbach', 'serhiy.storchaka']
pr_nums = ['13741']
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue37132'
versions = ['Python 3.8']See PEP-791
Activity
serhiy-storchaka commented on Jun 2, 2019
The math module contains as function for floating-point numbers, as wells as functions for integer only numbers: factorial(), gcd(). Yet few integer specific functions was added in 3.8: isqrt(), perm(), comb().
The proposed PR adds the new imath module, adds into it old functions factorial() and gcd() and moves new functions. It also adds two additional functions: as_integer_ratio() and ilog2().
There are plans for adding more integer functions: divide_and_round(), is_prime(), primes(), but the work in progress.
mdickinson commented on Jun 2, 2019
Some questions:
What's the plan for the existing functions math.gcd and math.factorial? Do they eventually get deprecated, or do we keep gcd and factorial in both math and imath?
Does PEP-399 apply here? If so, we'll need a pure Python version as well as a C version
Should imath.isqrt be renamed to imath.sqrt?
What's the actual benefit of this separation?
This feels like a really big change to be making a day before feature freeze; I'm not convinced that we don't need a PEP for this. How bad would it be if we have to defer until 3.9?
mdickinson commented on Jun 2, 2019
On futher reflection, I don't think it should. It's a different function, so it's not like comparing math.sqrt and cmath.sqrt.
One more: I suggest renaming the new function ilog to ilog2, for consistency with math.log versus math.log2.
serhiy-storchaka commented on Jun 2, 2019
I think they should eventually get deprecated, but with long term of deprecation. Deprecation warning should be added only when imath versions are already available in older Python versions.
But they can be also kept as pure aliases for very long time.
There were no Python implementations when these functions was in the math module. But there are Python implementations for all these functions (used in tests or as predecessors), so it is not hard to add them in the stdlib. Easier that to implement math.sin() on Python from scratch.
I considered this idea and do not have answer.
Currently math becomes a mix of very different functions. Separation will help to keep it simpler (from user and implementation sides). It also adds a place for landing new integer specific functions which are too specific to add them into the math module or into the int class.
mdickinson commented on Jun 2, 2019
I think the new as_integer_ratio also needs discussion: it was agreed at some point in the past to add as_integer_ratio methods on all numeric built-in types, and there's a PR for that. Adding as_integer_ratio as a new function too seems like two ways to do it.
Please can we defer to 3.9? There just isn't time for the design discussions that are needed, and I'd personally rather see the first version of the imath module be somewhat complete, with is_prime and primes already.
I do realise that from the perspective of adding an imath module, the accumulation of integer-based functions in the math module is something of a wart that we're making worse in 3.8, but I don't think rushing in this change is the solution.
Radical suggestion: should we consider delaying the inclusions of comb, perm and isqrt in the math module so that we can do this properly for 3.9?
serhiy-storchaka commented on Jun 2, 2019
Actually it was ilog2. There was just an error in the documentation.
Currently we have two ways to represent the number as an integer ratio. The official way is two properties numerator and denominator, every number should have them. And some concrete numeric types have the as_integer_ratio() method which returns both values. Rather of adding as_integer_ratio() to all other numeric types I propose to add a helper function which uses either the as_integer_ratio() method if available, or the numerator and denominator properties. Currently any code that uses the as_integer_ratio() method should implement a fallback to numerator and denominator. With imath.as_integer_ratio() it can just use this function.
I like it. I suggest to delay also adding the int.as_integer_ratio() method. Currently it does not help because there are other numeric methods without the as_integer_ratio() method.
mdickinson commented on Jun 2, 2019
I'm pretty much out of core-dev cycles for this weekend; I'm happy to review #57950, but won't have time to do so before next weekend.
I'm overall -0 on this change; there's a minor benefit in the separation, but for me it's outweighted by the duplication of gcd and factorial (or in the case of gcd, triplication, since it's also in the fractions module).
I'm out of time, so I'll be brief, but if this does go into 3.8, here are my thoughts:
Raymond, Tim: thoughts?
rhettinger commented on Jun 2, 2019
-1 I prefer these functions get left in the regular math module and just organize the docs to separate out integer functions. Additional namespacing creates cognitive load and creates a findability problem.
Also, I really don't want gcd() to be moved yet again.
rhettinger commented on Jun 2, 2019
After the beta feature freeze, I'll write up an edit the math module docs that makes in easier to find functions (by splitting out a section of the docs for these functions and by creating a summary link table at the top like we do for builtins). I really don't want a separate module for this and think that would work against the needs of usres.
tim-one commented on Jun 3, 2019
Ya, I'm mostly with Raymond. math was originally a very thin wrapper around C's libm, but we've been moving away from that more and more for decades, and it's no longer the case anyway that the vast bulk of new Python programmers are intimately familiar with C.
If I were coming new to Python now, I'd expect math functions to ... be in math ;-) Whether integer or float. I expect this will work fine if the docs are - as Raymond suggests - reworked to make it clear.
serhiy-storchaka commented on Jun 3, 2019
Well, then closing this.
5 remaining items
serhiy-storchaka commented on May 11, 2025
Closed #13741 has been revived as #133909. Unfortunately, I lost the Python implementation.
Since then, lcm() was added, gcd() supports more than 2 arguments, factorial() rejects floats, factorial(), perm(), and comb() has been significantly optimized.
serhiy-storchaka commented on May 12, 2025
Earlier discussion on the Python-ideas mailing list:
https://mail.python.org/archives/list/python-ideas@python.org/thread/YYJ5YJBJNCVXQWK5K3WSVNMPUSV56LOR/
gh-81313: Add the math.integer module (PEP-791) (GH-133909)
rhettinger commented on Nov 1, 2025
Didn't Guido come out squarely against this?
h-vetinari commented on Nov 1, 2025
Perhaps; the SC was pronounced it as accepted though.
tim-one commented on Nov 1, 2025
@rhettinger, I don't recall. But it's moot now anyway: the Steering Council accepted PEP 791.
https://peps.python.org/pep-0791
On d.p.o.:
https://discuss.python.org/t/pep-791-imath-module-for-integer-specific-mathematics-functions/92548/154
skirpichev commented on Nov 1, 2025
Yes, here are relevant links for your convenience:
In meanwhile people tried to address his objections. I hope, at least "it will just make things backwards incompatible" argument was crushed.
pythongh-81313: Add the math.integer module (PEP-791) (pythonGH-133909)