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.

Doc/library/functions.rst

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?

Doc/library/functions.rst

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.

Doc/library/functions.rst

serhiy-storchaka

I have made the requested changes; please review again.

Doc/library/functions.rst

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

Typo fixed.

AA-Turner · 2025-08-11T23:35:35Z

Doc/library/functions.rst


   As :func:`repr`, return a string containing a printable representation of an
   object, but escape the non-ASCII characters in the string returned by
   :func:`repr` using ``\x``, ``\u``, or ``\U`` escapes.  This generates a string
   similar to that returned by :func:`repr` in Python 2.


-.. function:: bin(x)
+.. function:: bin(integer, /)


'integer' could be too close to int for confusion

Suggested change

.. function:: bin(integer, /)

.. function:: bin(num, /)

I initially used number (it is used in the builtin signature), but changed it to integer, since only int and objects implementing __index__ are supported. In many other parts of the documentation "integer" means "int or objects implementing __index__".

Doc/library/functions.rst

AA-Turner · 2025-08-11T23:43:52Z

Doc/library/functions.rst

@@ -244,7 +242,7 @@ are always available.  They are listed here in alphabetical order.
      in Python 3.2.


-.. function:: chr(i)
+.. function:: chr(i, /)


Suggested change

.. function:: chr(i, /)

.. function:: chr(codepoint, /)

I thought on changing this name, but then we need to change also the following text and the docstring "Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff."

AA-Turner · 2025-08-11T23:49:19Z

Doc/library/functions.rst

@@ -846,7 +844,7 @@ are always available.  They are listed here in alphabetical order.


 .. _func-frozenset:
-.. class:: frozenset(iterable=set())
+.. class:: frozenset(iterable=(), /)


The empty frozenset is (notionally) a singleton, similar to the empty tuple, so I think it's clearer to distinguish them here:

Suggested change

.. class:: frozenset(iterable=(), /)

.. class:: frozenset()

frozenset(iterable, /)

AA-Turner · 2025-08-11T23:52:13Z

Doc/library/functions.rst

@@ -1144,8 +1142,7 @@ are always available.  They are listed here in alphabetical order.


 .. _func-list:
-.. class:: list()
-           list(iterable)
+.. class:: list(iterable=(), /)


As with frozenset I think clearer to keep two lines here:

Suggested change

.. class:: list(iterable=(), /)

.. class:: list()

list(iterable, /)

Your suggestions are opposite to @terryjreedy's. I just changed the code in opposite direction.

Doc/library/stdtypes.rst

AA-Turner · 2025-08-12T00:11:59Z

Doc/library/stdtypes.rst

   be removed - the name refers to the fact this method is usually used with
-   ASCII characters.  If omitted or ``None``, the *chars* argument defaults to
-   removing ASCII whitespace.  The *chars* argument is not a suffix; rather,
+   ASCII characters.  If omitted or ``None``, the *bytes* argument defaults to


this sentence no longer makes sense after changing the argument name

AA-Turner · 2025-08-12T00:12:33Z

Doc/library/stdtypes.rst

   be removed - the name refers to the fact this method is usually used with
-   ASCII characters.  If omitted or ``None``, the *chars* argument defaults
-   to removing ASCII whitespace.  The *chars* argument is not a prefix;
+   ASCII characters.  If omitted or ``None``, the *bytes* argument defaults


this sentence no longer makes sense after changing the argument name

AA-Turner · 2025-08-12T00:12:46Z

Doc/library/stdtypes.rst

   byte values to be removed - the name refers to the fact this method is
-   usually used with ASCII characters.  If omitted or ``None``, the *chars*
-   argument defaults to removing ASCII whitespace. The *chars* argument is
+   usually used with ASCII characters.  If omitted or ``None``, the *bytes*


this sentence no longer makes sense after changing the argument name

Could you please explain?

serhiy-storchaka

Thank you for your review @AA-Turner, especially for your catch of stop/end misnaming.

You suggestions about constructors with no argument are opposite to @terryjreedy's. I have no strong preference for now. I will agree to any consensus.

Could you please explain what is wrong with bytes.strip() etc?

serhiy-storchaka · 2025-08-12T05:46:36Z

Doc/library/functions.rst


   As :func:`repr`, return a string containing a printable representation of an
   object, but escape the non-ASCII characters in the string returned by
   :func:`repr` using ``\x``, ``\u``, or ``\U`` escapes.  This generates a string
   similar to that returned by :func:`repr` in Python 2.


-.. function:: bin(x)
+.. function:: bin(integer, /)


I initially used number (it is used in the builtin signature), but changed it to integer, since only int and objects implementing __index__ are supported. In many other parts of the documentation "integer" means "int or objects implementing __index__".

serhiy-storchaka · 2025-08-12T05:49:34Z

Doc/library/functions.rst

@@ -244,7 +242,7 @@ are always available.  They are listed here in alphabetical order.
      in Python 3.2.


-.. function:: chr(i)
+.. function:: chr(i, /)


I thought on changing this name, but then we need to change also the following text and the docstring "Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff."

serhiy-storchaka · 2025-08-12T05:54:02Z

Doc/library/functions.rst

@@ -1562,7 +1559,7 @@ are always available.  They are listed here in alphabetical order.
   .. versionchanged:: 3.11
      The ``'U'`` mode has been removed.

-.. function:: ord(c)
+.. function:: ord(c, /)


Hmm, the following text and the docstring are incorrect, they should be changed in any case.

Doc/library/stdtypes.rst

serhiy-storchaka · 2025-08-12T05:58:26Z

Doc/library/functions.rst

@@ -1144,8 +1142,7 @@ are always available.  They are listed here in alphabetical order.


 .. _func-list:
-.. class:: list()
-           list(iterable)
+.. class:: list(iterable=(), /)


Your suggestions are opposite to @terryjreedy's. I just changed the code in opposite direction.

serhiy-storchaka · 2025-08-12T06:00:02Z

Doc/library/stdtypes.rst

+   .. method:: hex(*, bytes_per_sep=1)
+               hex(sep, bytes_per_sep=1)


This is why I did not use this.

We can change the code (it would be not trivial) to support sep='', but this is a different issue.

serhiy-storchaka · 2025-08-12T10:35:51Z

Doc/library/functions.rst

-.. class:: type(object)
-           type(name, bases, dict, **kwds)
+.. class:: type(object, /)
+           type(name, bases, dict, /, **kwds)


I think that historically kwds was used first, but now kwargs is used 4-5 times more. kwds is still used 93 times in the documentation and 519 in the Python code. It is not error, but we can change the name here.

serhiy-storchaka · 2025-08-12T10:46:57Z

Doc/library/stdtypes.rst

   byte values to be removed - the name refers to the fact this method is
-   usually used with ASCII characters.  If omitted or ``None``, the *chars*
-   argument defaults to removing ASCII whitespace. The *chars* argument is
+   usually used with ASCII characters.  If omitted or ``None``, the *bytes*


Could you please explain?

serhiy-storchaka · 2025-08-12T12:03:09Z

Doc/library/functions.rst


-   Given a string representing one Unicode character, return an integer
+   The argument must be a one-character string or a :class:`bytes` or


I created a separate issue for this: #137668.

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

Doc/library/functions.rst Outdated Show resolved Hide resolved

Doc/library/functions.rst Outdated Show resolved Hide resolved

terryjreedy previously 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

Doc/library/functions.rst Show resolved Hide resolved

Doc/library/functions.rst Show resolved Hide resolved

Use less signatures and more default values.

72157aa

serhiy-storchaka commented Aug 10, 2025

View reviewed changes

Doc/library/functions.rst Show resolved Hide resolved

Doc/library/functions.rst Outdated Show resolved Hide resolved

Doc/library/functions.rst Outdated Show resolved Hide resolved

Doc/library/functions.rst Outdated Show resolved Hide resolved

Doc/library/functions.rst Show resolved Hide resolved

terryjreedy reviewed Aug 11, 2025

View reviewed changes

Doc/library/functions.rst Outdated Show resolved Hide resolved

This was referenced Aug 11, 2025

gh-125897: Use positional-only parameter indicators for range() #125945

Merged

gh-131885: Updates docs to make max and min iterable param positional only #131868

Merged

AA-Turner and others added 2 commits August 12, 2025 00:30

Merge branch 'main' into docs-builtins-signatures

d08e13f

Update Doc/library/functions.rst

94cc645

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

bedevere-app bot added awaiting review and removed awaiting changes labels Aug 12, 2025

terryjreedy approved these changes Aug 12, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels Aug 12, 2025

AA-Turner reviewed Aug 12, 2025

View reviewed changes

serhiy-storchaka added 2 commits August 12, 2025 13:48

Fix error with stop/end, update chr() and ord(), change kwdto kwargs.

899cc86

Merge branch 'main' into docs-builtins-signatures

e82b3e8

serhiy-storchaka commented Aug 12, 2025

View reviewed changes

ord() only supports bytes and bytearray.

a0f5a73

serhiy-storchaka commented Aug 12, 2025

View reviewed changes

	.. class:: frozenset(iterable=(), /)
	.. class:: frozenset()
	frozenset(iterable, /)

	.. class:: list(iterable=(), /)
	.. class:: list()
	list(iterable, /)

		.. method:: hex(*, bytes_per_sep=1)
		hex(sep, bytes_per_sep=1)


		Given a string representing one Unicode character, return an integer
		The argument must be a one-character string or a :class:`bytes` or

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!

Uh oh!

Uh oh!

terryjreedy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-app bot commented Aug 10, 2025

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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!

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