gh-125957: sync argument naming in sphinx docs of the cmath and help()

[skirpichev]

• Issue: Discrepancy in argument naming for Sphinx docs & help in the cmath module #125957

---

📚 Documentation preview 📚: https://cpython-previews--125958.org.readthedocs.build/

[skirpichev]

The second commits allows sin(z=1) syntax. This has some overhead:

In the main: $ ./python -m timeit -r11 -s 'from cmath import sin;z=1j' 'sin(z)' 1000000 loops, best of 11: 312 nsec per loop With patch: $ ./python -m timeit -r11 -s 'from cmath import sin;z=1j' 'sin(z)' 1000000 loops, best of 11: 330 nsec per loop 

Alternative solution: include slashed in the sphinx docs to reflect the actual function signature.

[picnixz]

I'm going offline until Friday so I won't be able to merge it (@vstinner asked me to wait for one other core dev approval before merging so if someone accepts it, they can either merge it or accept the PR and I'll merge it on Friday)

[vstinner]

LGTM.

PR title:

gh-125957: sync argument naming in sphinx docs of the cmath and help() #125958

It might be interesting to add the / marker for positional-only parameters.

Example:

>>> import cmath; help(cmath.phase) phase(z, /) Return argument, also known as the phase angle, of a complex. 

[skirpichev]

It might be interesting to add the / marker for positional-only parameters.

I did this once: #101120

This thread discuss an alternative proposal (allow keyword arguments): https://discuss.python.org/t/81003/ See some benchmarks above: #125958 (comment)

[miss-islington-app]

Thanks @skirpichev for the PR, and @AA-Turner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-131962 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-131963 is a backport of this pull request to the 3.12 branch.