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:
- dict.get(), dict.setdefault()

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: Use positional-only markers for the decimal module #131990
gh-131885: Document / for codecs functions #131992
gh-131885: Document * for code.InteractiveConsole #132029
gh-131885: update documented signatures for csv.{writer,reader} #136085
[3.14] gh-131885: Update documented signatures for csv.{writer,reader} (GH-136085) #136120
[3.13] gh-131885: Update documented signatures for csv.{writer,reader} (GH-136085) #136121
[3.14] gh-131885: Use positional-only markers for max() and min() (GH-131868) #137656
[3.13] gh-131885: Use positional-only markers for max() and min() (GH-131868) #137657
[3.14] gh-131885: Use positional-only markers for the decimal module (GH-131990) #137902
[3.13] gh-131885: Use positional-only markers for the decimal module (GH-131990) #137904
gh-131885: Update location of positional-only parameter indicator for eval and exec in the documentation #139978
gh-131885: Update unicodedata function signatures to use / #140270
gh-142349: Clarify lazy import filters have positional-only parameters #144856
gh-131885: Use real signatures in the zlib docs #156179
[3.13] gh-131885: Use real signatures in the zlib docs (GH-156179) #156267
[3.15] gh-131885: Use real signatures in the zlib docs (GH-156179) #156268
[3.14] gh-131885: Use real signatures in the zlib docs (GH-156179) #156269

pythongh-131885: simplify function signatures in the cmath module

gh-131885: Document that `dict.setdefault` and `dict.get` take no key…

pythongh-131885: Document that `dict.setdefault` and `dict.get` take …

[3.13] gh-131885: Document that `dict.setdefault` and `dict.get` take…

[3.12] gh-131885: Document that `dict.setdefault` and `dict.get` take…

Regarding range, please see also #125897.

@rhettinger

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.

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.

gh-131885: Document `/` for `codecs` functions (#131992)

gh-131885: Update documented signatures for `csv.{writer,reader}` (GH…

gh-131885: Update unicodedata function signatures to use `/` (#140270)

What's the status of this issue? Can it be closed?

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.

gh-131885: Document `*` for `code.InteractiveConsole` (#132029)

I merged #132029 PR.

Operator module: #141334

pythongh-131885: Update unicodedata function signatures to use `/` (p…

pythongh-131885: Document `*` for `code.InteractiveConsole` (python#1…

gh-131885: Use real signatures in the `zlib` docs (#156179)

[3.14] gh-131885: Use real signatures in the `zlib` docs (GH-156179) (#…

[3.13] gh-131885: Use real signatures in the `zlib` docs (GH-156179) (#…

[3.15] gh-131885: Use real signatures in the `zlib` docs (GH-156179) (#…

Navigation Menu

Repository navigation

Update function signatures to use `*` and `/` as needed #131885

Documentation

Linked PRs

22 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

Description

Documentation

Linked PRs

Activity

chris-eibl commented on Mar 30, 2025

skirpichev commented on Apr 1, 2025

ekohilas commented on Apr 11, 2025

skirpichev commented on Apr 11, 2025

22 remaining items

vstinner commented on Oct 30, 2025

ekohilas commented on Oct 30, 2025

skirpichev commented on Oct 30, 2025

vstinner commented on Oct 31, 2025

skirpichev commented on Nov 10, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Update function signatures to use `*` and `/` as needed #131885