gh-111999: Add signatures and improve docstrings for builtins #112000
Conversation
serhiy-storchaka
commented
Nov 12, 2023
•
serhiy-storchaka
commented
- Issue: Add signatures for some builtins #111999
serhiy-storchaka
requested review from
markshannon and
rhettinger
as code owners
| @@ -110,9 +110,10 @@ bool_xor(PyObject *a, PyObject *b) | |||
| /* Doc string */ | |||
|
|
|||
| PyDoc_STRVAR(bool_doc, | |||
| "bool(x) -> bool\n\ | |||
| "bool(object=False, /)\n\ | |||
There was a problem hiding this comment.
Sphinx docs shows this as bool(x=False) (give impression that this is a positional-or-keyword argument). Probably, this should be adjusted too?
There was a problem hiding this comment.
Maybe in other issue. The documentation not always uses syntax for positional-only parameters. It is relatively new.
| \n\ | ||
| (i.e. all elements that are in exactly one of the sets.)"); | ||
| Return a new set with elements in either the set or other but not both."); |
There was a problem hiding this comment.
BTW, for other set methods it seems there are signatures. But...
An example:
>>> help(set.add)
Help on method_descriptor:
add(self, object, /)
Add an element to a set.
This has no effect if the element is already present.
c.f. the sphinx docs:
add(elem)
Add element elem to the set.
There was a problem hiding this comment.
Signatures for methods without arguments and with a single positional argument are now autogenerated.
There was a problem hiding this comment.
Anyway, this looks like a bug.
There was a problem hiding this comment.
I was hoping is obvious. Instead of mystic name object, I would expect something like this
>>> inspect.signature(set.add)
<Signature (self, element, /)>
>>> help(set.add)
Help on method_descriptor:
add(self, element, /)
Add an element to a set.
This has no effect if the element is already present.I realize, parameter name here is not a part of API, but I think it should be meaningful, if possible.
There was a problem hiding this comment.
It could be improved, but it is not a bug. You can add explicit signatures for these methods, but for me it has low priority. I worked on support of multi-signatures, and this PR is a side product, the improvements that do not need multi-signatures (with multi-signatures and autogenerated signatures almost 100% of builtin functions and classes will have signatures).
There was a problem hiding this comment.
I think 'object', an instance of the base object class, is as correct as 'element', which is a set-theory specific synonym. We might say that 'a list has items', but item is a synonym for object. Here also, I appreciate the technically correct list.append(self, object, /). I think the consistency of the auto-generated signatures is good.
There was a problem hiding this comment.
One could argue that it should be set.add(self, hashable), as not any object can be added, whereas any object can be appended. The math term 'element' does not imply the restriction any more than 'object'.
