gh-131885: simplify function signatures in the cmath module

[skirpichev]

Now function docstrings are in sync with the module docs, for example:

>>> import cmath, inspect
>>> help(cmath.sin)
Help on built-in function sin in module cmath:

sin(z)
    Return the sine of z.

>>> inspect.signature(cmath.sin)
<Signature (z)>

As a side effect, this allows sin(z=1.23) calls. The price is slight
performance penalty (maybe this can be fixed on AC side):

Benchmark	ref	patch
sin(1.1)	417 ns	428 ns: 1.03x slower
sin(1j)	414 ns	422 ns: 1.02x slower
log(2.3)	390 ns	409 ns: 1.05x slower
log(1+2j)	449 ns	468 ns: 1.04x slower
log(2.1, 3.2)	601 ns	630 ns: 1.05x slower
Geometric mean	(ref)	1.04x slower

• Issue: Update function signatures to use * and / as needed #131885

---

For reviewers:

• this is on top of gh-125957: sync argument naming in sphinx docs of the cmath and help() #125958
• alternative: adjust sphinx docs instead, like gh-101118: correct function signatures in the math module docs #101120

benchmark code

# bench.py

import pyperf
from cmath import sin, log

runner = pyperf.Runner()
runner.bench_func('sin(1.1)', sin, 1.1)
runner.bench_func('sin(1j)', sin, 1j)
runner.bench_func('log(2.3)', log, 2.3)
runner.bench_func('log(1+2j)', log, 1+2j)
runner.bench_func('log(2.1, 3.2)', log, 2.1, 3.2)

[AA-Turner]

What's the justification for these runtime changes? I don't see any value to being able to use z as a keyword argument, and we shouldn't make things slower just for aesthetics (removing the / in help()).

[skirpichev]

What's the justification for these runtime changes?

It's explained in the pr description and (in depth) issue thread.

With this change we have correct signatures in docs, without cluttering them with syntax, which might be hard for newbies.

we shouldn't make things slower just for aesthetics (removing the / in help()).

No, it's not for aesthetics, but for readability. In pure-Python world you have to add extra syntax to have effect of positional-only arguments. This is something people have to learn and it's not common for being in recipes, tutorials, etc.

IMO, trade speed for readability is good. Though, maybe not for all cases (e.g. len() builtin?). I'm also not sure if this speed penalty can't be mitigated: this looks rather as AC issue for me.

[AA-Turner]

With this change we have correct signatures in docs

The signatures in the documentation are already correct, no? The debate over slash and star is over how precisely we describe runtime semantics. Is there something else I'm missing? The documentation should be driven by the runtime, not vice versa.

A

[skirpichev]

The signatures in the documentation are already correct, no?

No. As for many modules, the cmath sphinx docs are out of sync with module docstrings.

Alternative to this pr will be adding trailing slashes to sphinx docs.

The documentation should be driven by the runtime, not vice versa.

I think that documentation should be 1) readable 2) accurately describe runtime behavior. To achieve 1) and 2) we can adjust either docs or runtime, or both.

[AA-Turner]

To be clear though, the only difference is the slash? I wouldn't describe that as 'wrong', but as 'slightly less precise'.

On the assumption that the above is true, I'll close this PR. Perhaps there is a JavaScript solution we can use to 'simplify' the documentation for beginners.

A

[skirpichev]

I wouldn't describe that as 'wrong', but as 'slightly less precise'.

@AA-Turner, we have EB decision: "If a function accepts positional-only or keyword-only arguments, include the slash and the star in the signature as appropriate: [...] Although the syntax is terse, it is precise about the allowable ways to call the function and is taken from Python itself."

Sorry, I don't see here option for compromises.

Perhaps there is a JavaScript solution we can use to 'simplify' the documentation for beginners.

Currently stars and slashes are highlighted and tooltips appear in the sphinx docs. Though, same syntax appears e.g. in the help() output without any hints for user...

[skirpichev]

BTW, can you change your mind if speed issue will be solved?