gh-137609: Update signatures of builtins in the documentation#137610
gh-137609: Update signatures of builtins in the documentation#137610serhiy-storchaka merged 18 commits intopython:mainfrom
Conversation
Show signatures that match the actual signatures or future multisignatures for all functions, classes and methods in the "builtins" module.
serhiy-storchaka
added
docs
…uiltins This is to pair with pythonGH-137610.
…uiltins This is to pair with pythonGH-137610.
|
See also #137611. |
terryjreedy
left a comment
terryjreedy
left a comment
There was a problem hiding this comment.
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
Outdated
| .. class:: bytearray() | ||
| bytearray(source) | ||
| bytearray(source, encoding) | ||
| bytearray(source, encoding, errors) |
There was a problem hiding this comment.
I believe only two lines are needed.
| .. 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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I prefer fewer lines, and approve of the changes.
There was a problem hiding this comment.
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.
|
When you're done making the requested changes, leave the comment: |
serhiy-storchaka
left a comment
serhiy-storchaka
left a comment
There was a problem hiding this comment.
I have made the requested changes; please review again.
Doc/library/functions.rst
Outdated
| .. class:: bytearray() | ||
| bytearray(source) | ||
| bytearray(source, encoding) | ||
| bytearray(source, encoding, errors) |
There was a problem hiding this comment.
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.
Co-authored-by: Terry Jan Reedy <[email protected]>
serhiy-storchaka
force-pushed
the
docs-builtins-signatures
branch
from
00556ee to
de15f70
Compare
| .. _func-str: | ||
| .. class:: str(object='') | ||
| str(object=b'', encoding='utf-8', errors='strict') | ||
| .. class:: str(*, encoding='utf-8', errors='strict') |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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')
''|
|
||
| .. _func-frozenset: | ||
| .. class:: frozenset(iterable=set()) | ||
| .. class:: frozenset(iterable=(), /) |
There was a problem hiding this comment.
Either approach could work but I like the way it's in the current PR; it's better to have fewer distinct signatures.
Co-authored-by: Jelle Zijlstra <[email protected]>
|
Reverted changes for signatures with start/end parameters, as this is a separate non-trivial issue (#138134). |
|
Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14. |
…ythonGH-137610) Show signatures that match the actual signatures or future multisignatures for all functions, classes and methods in the "builtins" module. (cherry picked from commit 65fb4d1) Co-authored-by: Serhiy Storchaka <[email protected]>
|
Sorry, @serhiy-storchaka, I could not cleanly backport this to |
|
GH-138137 is a backport of this pull request to the 3.14 branch. |
…ation (pythonGH-137610) Show signatures that match the actual signatures or future multisignatures for all functions, classes and methods in the "builtins" module. (cherry picked from commit 65fb4d1) Co-authored-by: Serhiy Storchaka <[email protected]>
|
GH-138138 is a backport of this pull request to the 3.13 branch. |
…H-137610) (#138137) Co-authored-by: Serhiy Storchaka <[email protected]>
…ation (pythonGH-137610) (python#138137) Co-authored-by: Serhiy Storchaka <[email protected]>
6 participants
Show signatures that match the actual signatures or future multisignatures for all functions, classes and methods in the "builtins" module.
📚 Documentation preview 📚: https://cpython-previews--137610.org.readthedocs.build/