GeezerVison is showing github.com — Update function signatures to use `*` and `/` as needed · Issue #131885 · python/cpython
Update function signatures to use * and / as needed #131885DescriptionDocumentation
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:
Linked PRs
Activityadded a commit that references this issue on Mar 30, 2025gh-131885: Document that `dict.setdefault` and `dict.get` take no key… chris-eibl commented on Mar 30, 2025 Regarding range, please see also #125897. skirpichev commented on Apr 1, 2025 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 commented on Apr 11, 2025 ContributorAuthor More actions
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 commented on Apr 11, 2025
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. vstinner commented on Oct 30, 2025 What's the status of this issue? Can it be closed? ekohilas commented on Oct 30, 2025 ContributorAuthor More actions 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: ***@***.***> skirpichev commented on Oct 30, 2025
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. vstinner commented on Oct 31, 2025 Reacted by Sergey B Kirpichev skirpichev commented on Nov 10, 2025
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|