Description

skirpichev

opened on Jan 18, 2023

Issue body actions

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

Activity

1. skirpichev

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Jan 18, 2023
2. rhettinger

   closed this as not plannedon Jan 18, 2023
3. skirpichev commented on Jul 19, 2024

   

   skirpichev

   on Jul 19, 2024

   MemberAuthor

   More actions

   @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.
4. skirpichev commented on Jul 21, 2024

   

   skirpichev

   on Jul 21, 2024

   MemberAuthor

   More actions

   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?

Issue actions