Repository navigation
Update function signatures to use * and / as needed #131885
Description
Activity
- added a commit that references this issue
on Mar 30, 2025 Regarding
range, please see also #125897.Reacted by Evan KohilasMy 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 oflen(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.
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.
- added a commit that references this issue
on Apr 14, 2025 - added a commit that references this issue
on Jun 30, 2025 22 remaining items
What's the status of this issue? Can it be closed?
- marked Clarify documentation of positional-only default values #67926 as a duplicate of this issue
on Oct 30, 2025 - 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.
- marked operator library and inspect.signature clarity: "a" versus "obj"? #141334 as a duplicate of this issue
on Nov 10, 2025 Operator module: #141334
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.
min()max()range()map()dict.get(),dict.setdefault()See also:
Linked PRs
dict.setdefaultanddict.gettake no keyword arguments (GH-128208) #131893dict.setdefaultanddict.gettake no keyword arguments (GH-128208) #131894decimalmodule #131990/forcodecsfunctions #131992*forcode.InteractiveConsole#132029csv.{writer,reader}#136085csv.{writer,reader}(GH-136085) #136120csv.{writer,reader}(GH-136085) #136121max()andmin()(GH-131868) #137656max()andmin()(GH-131868) #137657decimalmodule (GH-131990) #137902decimalmodule (GH-131990) #137904evalandexecin the documentation #139978/#140270zlibdocs #156179zlibdocs (GH-156179) #156267zlibdocs (GH-156179) #156268zlibdocs (GH-156179) #156269