Repository navigation
Missing "/" in function signatures of the rst docs of stdlib (e.g. the math module) #101118
Closed as not planned
Description
after PEP 570, there is a syntax to specify positional-only parameters in the function definition. Unfortunately, most stdlib modules ignore this (the os module seems to be an exception). The math module is an example. While
>>> inspect.signature(math.ceil)
<Signature (x, /)>the module docs display the function signature as math.ceil(x), that is wrong:
>>> math.ceil(x=3.14)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: math.ceil() takes no keyword arguments
Activity
skirpichev commentedon Jul 19, 2024
@sobolevn, @rhettinger - now Python Documentation Editorial Board decided to specify positional-only arguments, see docs:
"If a function accepts positional-only or keyword-only arguments, include the slash and the star in the signature as appropriate" (c)
Either this issue (and linked pr) should be reopened - or this decision reverted, see d.p.o thread with announce.
skirpichev commentedon Jul 21, 2024
BTW, we can avoid this funny notation (at least for modules with simple interfaces like math or cmath), while preserving "precision and completeness" of reference docs.
Here tests for positional-or-keyword in the cmath:
vs positional-only (in main):
Overhead for arguments processing in (1) is measurable, but it's 2-3% of timings in (2). Maybe it's acceptable?