Missing "/" in function signatures of the rst docs of stdlib (e.g. the math module)

[skirpichev]

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

Linked PRs

• gh-101118: correct function signatures in the math module docs #101120

[skirpichev]

@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]

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:

$ python -m pyperf timeit -s 'from cmath import acos;z=2' -q 'acos(z)' # (1)
Mean +- std dev: 497 ns +- 10 ns
$ python -m pyperf timeit -s 'from cmath import acos;z=2' -q 'acos(z=z)'
Mean +- std dev: 625 ns +- 31 ns

vs positional-only (in main):

$ python -m pyperf timeit -s 'from cmath import acos;z=2' -q 'acos(z)' # (2)
Mean +- std dev: 485 ns +- 6 ns

Overhead for arguments processing in (1) is measurable, but it's 2-3% of timings in (2). Maybe it's acceptable?