python
Update function signatures to use `*` and `/` as needed
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:
- [x]
dict.get(),dict.setdefault()
- [x]
See also:
- https://discuss.python.org/t/editorial-board-decisions/58580
- https://github.com/python/cpython/pull/129669#issuecomment-2636839784
- https://discuss.python.org/t/81003
- https://devguide.python.org/documentation/style-guide/#function-signatures
- https://discuss.python.org/t/58750
Linked PRs
- gh-131868
- gh-131886
- gh-128208
- gh-131893
- gh-131894
- gh-131990
- gh-131992
- gh-132029
- gh-136085
Regarding range, please see also https://github.com/python/cpython/issues/125897.
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 https://github.com/python/cpython/pull/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 https://github.com/python/cpython/issues/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 https://github.com/python/cpython/pull/117671, merge conflicts fixed in https://github.com/skirpichev/cpython/pull/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.
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.
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.
Thanks for checking in. Will review the current progress and update with the status.(Unless a new issue should be made for any other related changes)On 30 Oct 2025, at 6:41 am, Victor Stinner @.***> wrote:vstinner left a comment (python/cpython#131885) What's the status of this issue? Can it be closed?
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: @.***>
Can it be closed?
There are open pull requests.
And there are many stdlib modules (e.g. math or cmath), for which the issue is still valid and should be solved one way or another.