gh-137609: Update signatures of builtins in the documentation

[serhiy-storchaka]

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/

[serhiy-storchaka]

See also #137611.

[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]

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.

[serhiy-storchaka]

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]

I prefer fewer lines, and approve of the changes.

[AA-Turner]

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.

[bedevere-app]

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

[serhiy-storchaka]

I have made the requested changes; please review again.

[serhiy-storchaka]

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.

Typo fixed.

[JelleZijlstra]

Thanks for doing this!

[JelleZijlstra]

It's technically true that you can pass just the encoding or errors kwargs (like str(encoding='ebcdic')), but it's not practically useful, since you just get an empty string whatever encoding you pass, and I fear it's confusing to users to put this here.

The old docs here feel clearer even if they're not as precise.

[serhiy-storchaka]

We should be technically correct.

Several years ago I proposed to deprecate this case, but my proposition was rejected. If it is worth to continue supporting this in code, it is worth to document it. Note that values of encoding and errors are ignored:

>>> str(encoding='spam', errors='ham') ''

[JelleZijlstra]

Either approach could work but I like the way it's in the current PR; it's better to have fewer distinct signatures.

[serhiy-storchaka]

Reverted changes for signatures with start/end parameters, as this is a separate non-trivial issue (#138134).

[miss-islington-app]

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 65fb4d11a0f3f3e4aea373bd84918e4445cbfe67 3.13 

[bedevere-app]

GH-138137 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-138138 is a backport of this pull request to the 3.13 branch.