Abstract

This PEP proposes a new module for number-theoretical, combinatorial and other functions defined for integer arguments, like math.gcd() or math.isqrt().

Motivation

The math documentation says: “This module provides access to the mathematical functions defined by the C standard.” But, over time the module was populated with functions that aren’t related to the C standard or floating-point arithmetics. Now it’s much harder to describe module scope, content and interfaces (returned values or accepted arguments).

For example, the math module documentation says: “Except when explicitly noted otherwise, all return values are floats.” This is no longer true: None of the functions listed in the Number-theoretic functions 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 math and the new module.

Apparently, the math module can’t serve as a catch-all place for mathematical functions since we also have the cmath and 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.

Currently the math module code in the CPython is around 4200LOC, from which the new module code is roughly 1/3 (1300LOC). This is comparable with the cmath (1340LOC), which is not a simple wrapper to the libm, as most functions in the math module.

Specification

The PEP proposes moving the following integer-related functions to a new module, called imath:

• comb()
• factorial()
• gcd()
• isqrt()
• lcm()
• perm()

Their aliases in math will be soft deprecated.

Module functions will accept integers and objects that implement the __index__() method, which is used to convert the object to an integer number. Suitable functions must be computed exactly, given sufficient time and memory.

Possible extensions for the new module and its scope are discussed in the Open Issues section. New functions are not part of this proposal.

Backwards Compatibility

As aliases in math will be kept for an indefinite time (their use would be discouraged), there are no anticipated code breaks.

How to Teach This

The new module will be a place for functions, that 1) accept 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 platform math library (libm).

For users it would be natural first to look on the int’s methods, which cover most basic use-cases (e.g. int.bit_length() method), than to some dedicated place in the stdlib.

Reference Implementation

python/cpython#133909

Open Issues

Rejected ideas

There was a brief discussion about exposing math.isqrt() as imath.sqrt in the same way that cmath.sqrt() is the complex version of math.sqrt(). However, isqrt 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).

Acknowledgements

Thanks to Tim Peters for reviving the idea of splitting the math module. Thanks to Neil Girdhar for substantial improvements of the initial draft.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.