Update function signatures to use * and / as needed

[ekohilas]

Documentation

Caution

For new contributors, please do not consider this issue as an "easy" one. While the changes may seem mechanical, they are not necessarily trivial as this requires to know what really happens (both at a Python and a C level).

This is tracks cases where changes need to be made to enact the Editorial Board's decision for function signature markup.

• builtins:
  • min()
  • max()
  • range()
  • map()
• methods on builtins:
  • dict.get(), dict.setdefault()

See also:

• https://discuss.python.org/t/editorial-board-decisions/58580
• gh-129667: Update annotation in documentation #129669 (comment)
• https://discuss.python.org/t/81003
• https://devguide.python.org/documentation/style-guide/#function-signatures
• https://discuss.python.org/t/58750

Linked PRs

• gh-131885: Updates docs to make max and min iterable param positional only #131868
• gh-131885: simplify function signatures in the cmath module #131886
• gh-131885: Document that dict.setdefault takes no keyword arguments #128208
• [3.13] gh-131885: Document that dict.setdefault and dict.get take no keyword arguments (GH-128208) #131893
• [3.12] gh-131885: Document that dict.setdefault and dict.get take no keyword arguments (GH-128208) #131894
• gh-131885: Document / for decimal.Context methods #131990
• gh-131885: Document / for codecs functions #131992
• gh-131885: Document * for code.InteractiveConsole #132029

[chris-eibl]

Regarding range, please see also #125897.

[skirpichev]

My 2c on how this can be addressed.

First, probably we shouldn't just mechanically change docs to reflect actual signatures. I trust @rhettinger teaching experience that slash/star-enabled signatures are less readable for newcomers. On another hand, IMO such signatures for C-coded functions usually seems to be artifacts of lacking the AC in past. Now we can use positional-or-keyword arguments in C and leave boilerplate code to the AC. Why not do this? Then e.g. we can use plain-and-simple len(obj) in documentation, instead of len(obj, /). Note that first form preferred also by some Python implementations (e.g. PyPy).

The price is some performance degradation (see #131886), which might be AC bug. Also, argument names will be part of the API.

Second, I think that EB decision covers only sphinx docs, @nedbat ?

If so, we also have docstrings for C-coded functions, where in some cases function signatures are documented by some non-Python syntax, nowhere (i.e. in docs) actually documented. min/max functions are examples. What we should do here?

Proper solution, probably, requires solving #73536. But that seems to be rather an issue for the inspect module. I think that already now we can start fixing such docstrings to use multiple signatures (each being a valid Python function signature!), just as sphinx docs. So, the outcome for e.g. max() will be (as in #117671, merge conflicts fixed in skirpichev#7):

>>> help(max)
Help on built-in function max in module builtins:

max(iterable, /, *, key=None)
max(iterable, /, *, default, key=None)
max(arg1, arg2, /, *args, key=None)
    With a single iterable argument, return its biggest item. The
    default keyword-only argument specifies an object to return if
    the provided iterable is empty.
    With two or more positional arguments, return the largest argument.

Sure, we can invent a more dense syntax for such signatures. But I doubt it worth: 1) new syntax will require an explanation 2) save us line or two in each case, at maximum.

[ekohilas]

I trust @rhettinger teaching experience that slash/star-enabled signatures are less readable for newcomers.

I could understand why that would be the case previously, if you didn't know what / meant!
I would think now with the tooltips present on mouseover for * and /, that would no longer be the case, as newcomers could dig into what that means.
As it stands, the lack of / and * in signatures is worse, because users that have seen or understood different types of argument usage would be confused why a function behaves as if it has a / but isn't documented as such.

artifacts of lacking the AC in past.

Could you clarify what AC means here?

we also have docstrings for C-coded functions, where in some cases function signatures are documented by some non-Python syntax, nowhere (i.e. in docs) actually documented. min/max functions are examples. What we should do here?

max(iterable, /, *, key=None)
max(iterable, /, *, default, key=None)
max(arg1, arg2, /, *args, key=None)
With a single iterable argument, return its biggest item. The
default keyword-only argument specifies an object to return if
the provided iterable is empty.
With two or more positional arguments, return the largest argument.
Sure, we can invent a more dense syntax for such signatures. But I doubt it worth: 1) new syntax will require an explanation 2) save us line or two in each case, at maximum.

Yes this is great!
If docstrings are used as docs, they could be the same as the docs and signatures in the docs themselves?
No need for having to define the undocumented syntax already used, and give newcomers another thing to learn.

[skirpichev]

I would think now with the tooltips present on mouseover for * and /

There is no tooltips in help() output.

Could you clarify what AC means here?

https://devguide.python.org/development-tools/clinic/

If docstrings are used as docs, they could be the same as the docs and signatures in the docs themselves?

In general, sphinx docs and docstrings are different. Later less verbose, miss examples, etc. But wrt functions signatures they could be same and, probably, should.