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?

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.

I prefer fewer lines, and approve of the changes.

I'm not sure I agree here, source=b'' makes it less clear to me that source also accepts e.g. iterables of integers, buffer-protocol, etc. I would suggest:

.. class:: bytearray() bytearray(source, /) bytearray(source, /, encoding, errors='strict')

Note I have suggested to annotate 'source' as positional-only -- I think this makes more sense to users than writing e.g. bytearray(source=my_numpy_array). My IDE & type-checkers also indicates that source=... is an error, as it is annotated as positional-only in typeshed.

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

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.

Doc/library/functions.rst

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

Typo fixed.

Doc/library/functions.rst

AA-Turner · 2025-08-11T23:42:00Z

Doc/library/functions.rst

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


I'm not sure I agree here, source=b'' makes it less clear to me that source also accepts e.g. iterables of integers, buffer-protocol, etc. I would suggest:

.. class:: bytearray() bytearray(source, /) bytearray(source, /, encoding, errors='strict')

Note I have suggested to annotate 'source' as positional-only -- I think this makes more sense to users than writing e.g. bytearray(source=my_numpy_array). My IDE & type-checkers also indicates that source=... is an error, as it is annotated as positional-only in typeshed.

Doc/library/functions.rst

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.

@terryjreedy what do you think? I would be -1 on combining here, I think it goes too far (even though it is technically accurate).

We currently have two lines for these container initialisers in the documentation, so it's not adding more bloat.

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?

Sorry, happy to explain. It currently says:

The chars argument is a binary sequence specifying the set of byte values to be removed - the name refers to the fact this method is usually used with ASCII characters.

This PR changes *chars* to *bytes*, which means the second half of the sentence doesn't make sense / no longer applies. It should be removed or changed.

Ah, good catch. Then I'll restore chars. This is not the best name, but this should be a separate issue.

On other hand, bytes is already used in the signature for long time. So this is in the scope of this PR.

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?

Doc/library/functions.rst

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.

Doc/library/stdtypes.rst

Doc/library/functions.rst

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.

This reverts commit b159ccd.

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

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

serhiy-storchaka added 6 commits August 13, 2025 12:25

Merge branch 'main' into docs-builtins-signatures

68706c2

Rename "bytes" back to "chars".

b159ccd

Revert "Rename "bytes" back to "chars"."

c2068d2

This reverts commit b159ccd.

Remove outdated explanation of the "chars" name.

c06089f

Add missed '/'s.

8b5e802

Add a signature for weird str() case.

de15f70

serhiy-storchaka force-pushed the docs-builtins-signatures branch from 00556ee to de15f70 Compare August 13, 2025 10:39

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

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


		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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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