gh-137609: Update signatures of builtins in the documentation #137610

serhiy-storchaka · 2025-08-10T13:47:37Z

Show signatures that match the actual signatures or future multisignatures for all functions, classes and methods in the "builtins" module.

Issue: Update signatures of builtins in the documentation #137609

📚 Documentation preview 📚: https://cpython-previews--137610.org.readthedocs.build/

Show signatures that match the actual signatures or future multisignatures for all functions, classes and methods in the "builtins" module.

…uiltins This is to pair with pythonGH-137610.

serhiy-storchaka · 2025-08-10T14:11:46Z

See also #137611.

skirpichev · 2025-08-10T15:02:56Z

Doc/library/functions.rst

+.. class:: range(stop, /)
+           range(start, stop, step=1, /)


See #125945 for range

skirpichev · 2025-08-10T15:03:46Z

Doc/library/functions.rst

+.. function:: min(iterable, /, *, key=None)
+              min(iterable, /, *, default, key=None)
+              min(arg1, arg2, /, *args, key=None)


See #131868 for min/max.

terryjreedy

I approve of the issue, the addition of /s, the renamings, and most of the details. The main question for me is relative positioning of / and *args.

Fewer versus more lines is partly style preference and partly technical accuracy, and the signature needed to have an inspect.signature and to write a python version of the same or similar function, versus ease of understanding how to call the function. Are "future multisignatures" a real possibility?

terryjreedy · 2025-08-10T15:42:12Z

Doc/library/functions.rst

+.. class:: bytearray()
+           bytearray(source)
           bytearray(source, encoding)
           bytearray(source, encoding, errors)


I believe only two lines are needed.

Suggested change

.. class:: bytearray()

bytearray(source)

bytearray(source, encoding)

bytearray(source, encoding, errors)

.. class:: bytearray(source=b'')

bytearray(source, encoding, errors='strict')

See also #137100, which is also about the text that follows.

Some descriptions have separate signature for no argument, others merge it with a signature with one argument. See for example dict which could be written as dict(mapping_or_iterable=(), **kwargs), but is written as three semantically different signatures. I tried to be more consistent and chose the former variant. But I have no such strong preference.

terryjreedy · 2025-08-10T15:42:42Z

Doc/library/functions.rst

+.. class:: bytes()
+           bytes(source)


Same comments as for bytearray.

terryjreedy · 2025-08-10T16:36:58Z

Doc/library/functions.rst

-              max(arg1, arg2, *args, key=None)
+.. function:: max(iterable, /, *, key=None)
+              max(iterable, /, *, default, key=None)
+              max(arg1, arg2, /, *args, key=None)


To me, the /, belongs after *args as the latter only collects the remaining positional args.

This is not valid syntax.

terryjreedy · 2025-08-10T16:38:22Z

Doc/library/functions.rst

+.. function:: max(iterable, /, *, key=None)
+              max(iterable, /, *, default, key=None)


Why the inconsistency of type mode, normal versus italic? Applies to next line also.

I guess this is a flaw of the GitHub highligher.

terryjreedy · 2025-08-10T17:02:14Z

Doc/library/functions.rst

+           str(object, encoding)
+           str(object, encoding, errors)
+           str(object, *, errors)


This is tough. There is a default encoding if errors is given, not if not. str(b'abc')=="b'abc'" (the 6 char repr()) while str(b'abc',errors='strict')=='abc' (3 chars).

bedevere-app · 2025-08-10T17:10:23Z

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

StanFromIreland · 2025-08-10T17:11:27Z

Doc/library/functions.rst

@@ -54,15 +54,15 @@ are always available.  They are listed here in alphabetical order.
 .. |func-bytearray| replace:: ``bytearray()``
 .. |func-bytes| replace:: ``bytes()``

-.. function:: abs(x)
+.. function:: abs(number, /)

   Return the absolute value of a number.  The argument may be an


Suggested change

Return the absolute value of a number. The argument may be an

Return the absolute value of *number*. *number* may be an

I think that there is no need to refer the argument by name if it is the only argument. I think it's easier to understand if you don't get distracted by the name. And if you were to read it out loud, which variant sounds better?

StanFromIreland · 2025-08-10T17:12:58Z

Doc/library/functions.rst


-   Return a reverse :term:`iterator`.  *seq* must be an object which has
+   Return a reverse :term:`iterator`.  The argument must be an object which has


Why not update the previous?

Suggested change

Return a reverse :term:`iterator`. The argument must be an object which has

Return a reverse :term:`iterator`. *sequence* must be an object which has

Actually, sequence is not so good name. The argument can be a dict.

serhiy-storchaka

I have made the requested changes; please review again.

serhiy-storchaka · 2025-08-10T17:50:17Z

Doc/library/functions.rst

@@ -54,15 +54,15 @@ are always available.  They are listed here in alphabetical order.
 .. |func-bytearray| replace:: ``bytearray()``
 .. |func-bytes| replace:: ``bytes()``

-.. function:: abs(x)
+.. function:: abs(number, /)

   Return the absolute value of a number.  The argument may be an


I think that there is no need to refer the argument by name if it is the only argument. I think it's easier to understand if you don't get distracted by the name. And if you were to read it out loud, which variant sounds better?

serhiy-storchaka · 2025-08-10T17:55:50Z

Doc/library/functions.rst

+.. class:: bytearray()
+           bytearray(source)
           bytearray(source, encoding)
           bytearray(source, encoding, errors)


Some descriptions have separate signature for no argument, others merge it with a signature with one argument. See for example dict which could be written as dict(mapping_or_iterable=(), **kwargs), but is written as three semantically different signatures. I tried to be more consistent and chose the former variant. But I have no such strong preference.

serhiy-storchaka · 2025-08-10T18:05:45Z

Doc/library/functions.rst

-              max(arg1, arg2, *args, key=None)
+.. function:: max(iterable, /, *, key=None)
+              max(iterable, /, *, default, key=None)
+              max(arg1, arg2, /, *args, key=None)


This is not valid syntax.

serhiy-storchaka · 2025-08-10T18:06:23Z

Doc/library/functions.rst

+.. function:: max(iterable, /, *, key=None)
+              max(iterable, /, *, default, key=None)


I guess this is a flaw of the GitHub highligher.

serhiy-storchaka · 2025-08-10T18:08:22Z

Doc/library/functions.rst


-   Return a reverse :term:`iterator`.  *seq* must be an object which has
+   Return a reverse :term:`iterator`.  The argument must be an object which has


Actually, sequence is not so good name. The argument can be a dict.

pythongh-137609: Update signatures of builtins in the documentation

5f13e6f

Show signatures that match the actual signatures or future multisignatures for all functions, classes and methods in the "builtins" module.

serhiy-storchaka added docs Documentation in the Doc dir skip news needs backport to 3.13 bugs and security fixes labels Aug 10, 2025

github-project-automation bot added this to Docs PRs Aug 10, 2025

serhiy-storchaka added the needs backport to 3.14 bugs and security fixes label Aug 10, 2025

github-project-automation bot moved this to Todo in Docs PRs Aug 10, 2025

bedevere-app bot added the awaiting core review label Aug 10, 2025

bedevere-app bot mentioned this pull request Aug 10, 2025

Update signatures of builtins in the documentation #137609

Open

serhiy-storchaka added a commit to serhiy-storchaka/cpython that referenced this pull request Aug 10, 2025

pythongh-137609: Change names of some positional-only parameters in b…

aeda212

…uiltins This is to pair with pythonGH-137610.

serhiy-storchaka added a commit to serhiy-storchaka/cpython that referenced this pull request Aug 10, 2025

pythongh-137609: Change names of some positional-only parameters in b…

d7d3981

…uiltins This is to pair with pythonGH-137610.

serhiy-storchaka mentioned this pull request Aug 10, 2025

gh-137609: Change names of some positional-only parameters in builtins #137611

Open

serhiy-storchaka requested a review from AA-Turner August 10, 2025 14:11

skirpichev reviewed Aug 10, 2025

View reviewed changes

terryjreedy requested changes Aug 10, 2025

View reviewed changes

bedevere-app bot removed the awaiting core review label Aug 10, 2025

bedevere-app bot added the awaiting changes label Aug 10, 2025

StanFromIreland reviewed Aug 10, 2025

View reviewed changes

Use less signatures and more default values.

72157aa

serhiy-storchaka commented Aug 10, 2025

View reviewed changes

		.. function:: max(iterable, /, *, key=None)
		max(iterable, /, *, default, key=None)

	Return the absolute value of a number. The argument may be an
	Return the absolute value of number. number may be an


		Return a reverse :term:`iterator`. seq must be an object which has
		Return a reverse :term:`iterator`. The argument must be an object which has

	Return a reverse :term:`iterator`. The argument must be an object which has
	Return a reverse :term:`iterator`. sequence must be an object which has

Uh oh!

gh-137609: Update signatures of builtins in the documentation #137610

Are you sure you want to change the base?

gh-137609: Update signatures of builtins in the documentation #137610

Conversation

serhiy-storchaka commented Aug 10, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

serhiy-storchaka commented Aug 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

terryjreedy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Aug 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

serhiy-storchaka commented Aug 10, 2025 •

edited by github-actions bot

Loading