ADR-0018: Provide math and sys as checker tables over runtime functions¶
Status¶
Accepted
Date¶
2026-11-12
Context¶
ADR-0007 decides that each standard library module is a typed Python file
in typy-stdlib, with the operations Python cannot express in a private
module, _typy, and allows a module that needs a later feature to be
"written around it". The builtins already are: print, sorted and
sum are a table in the checker and runtime functions (detailed design
section 6).
math and sys are the first standard library modules (LIB-04, LIB-05).
Their functions cannot be declared in the 0.3 subset:
math.sqrt(4)takes anintor afloat. TyPy refuses anintwhere afloatis declared (TYP-09), andint | floatunions arrive in 0.4.math.floor(x)returns theintitself for anintand rounds afloat, a choice by the argument's type that needs overloads.math.gcd(*integers),math.hypot(*coordinates)andprint(..., file=)take any number of arguments or keywords (EXP-17).- Most of
mathis a call of the C maths library, with CPython's checks around it, andsysreads the command line and the standard streams, all of which would be_typyprimitives with a Python wrapper of one line each.
Options considered¶
- Python files now, typed
float. Follows ADR-0007 to the letter, butmath.sqrt(4)is refused until 0.4, a gap against CPython in the most common uses of the module. - Checker tables over runtime functions, as the builtins. Each name of a module is an entry in a table the checker types; lowering calls a runtime function that holds CPython's algorithm and checks. Arguments take the types CPython accepts.
- Wait for 0.4. Leaves LIB-04 and LIB-05 unmet in the release that plans them.
Decision¶
TyPy uses option 2 for math and sys in 0.3, as the case ADR-0007
allows for a module that needs a later feature.
- A module is a built-in module:
import mathbinds a module object that prints as CPython's does,<module 'math' (built-in)>, and runs no code. Its names are entries of a table intypy-check, each with its shape: the types of its arguments, its result, and the Python version that added it. - A name added after the program's Python floor is E0425 at that floor,
as CPython of that version has no such name (STD-01):
math.fmaneeds 3.13. - A function takes the arguments CPython accepts: a real-number
parameter takes an
int, aboolor afloat, converted as CPython converts it, so aninttoo large for afloatraises CPython'sOverflowError. An argument CPython refuses for every value, such as astr, is E0404 with CPython's message. - The runtime functions port CPython's own code where CPython does not
call the C library directly: the checks of
math_1andmath_2,pow,fmod,remainder,hypot,logof a largeint,ldexp,frexp,modf,isclose,nextafterandulp, and the integer functions. Messages are CPython 3.15's, the newest wording (OI-14). - A module moves to a Python file in
typy-stdlibwhen the features it needs arrive, with the same names and results.
Consequences¶
mathandsyswork in 0.3 with CPython's results, and conformance tests compare them with CPython's modules, as ADR-0007 asks.- The checker carries one table per built-in module, and the runtime the functions behind it; neither grows a program that does not import the module, since an unused runtime function is not linked (NFR-01).
- On the
musltarget the C library's results may differ from glibc's in the last bit for some functions; conformance tests run on glibc. fsum,prod,sumprod,dist,gammaandlgammaare planned for 0.4 (LIB-12): the first four take iterables of numbers, which need generics, and the last two are CPython's own algorithms rather than calls of the C library.
Related requirements¶
LIB-04, LIB-05, LIB-09, LIB-12, TYP-09, EXP-17, STD-01, OI-14, ADR-0003, ADR-0007.