Skip to content

gh-117764: Fix and add signatures for many builtins #117769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 12, 2024
Merged

gh-117764: Fix and add signatures for many builtins #117769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9fdbe57
gh-117764: Fix and add signatures for many builtins
serhiy-storchaka Apr 11, 2024
6ac4fee
Update Objects/descrobject.c
serhiy-storchaka Apr 11, 2024
2dc3d9f
Add a docstring for __del__().
serhiy-storchaka Apr 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion Objects/clinic/descrobject.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 5 additions & 4 deletions Objects/descrobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1165,8 +1165,8 @@ mappingproxy_reversed(PyObject *self, PyObject *Py_UNUSED(ignored))

static PyMethodDef mappingproxy_methods[] = {
{"get", _PyCFunction_CAST(mappingproxy_get), METH_FASTCALL,
PyDoc_STR("D.get(k[,d]) -> D[k] if k in D, else d."
" d defaults to None.")},
PyDoc_STR("get($self, key, default=None, /)\n--\n\n"
"Return the value for key if key is in the mapping, else default.")},
{"keys", mappingproxy_keys, METH_NOARGS,
PyDoc_STR("D.keys() -> a set-like object providing a view on D's keys")},
{"values", mappingproxy_values, METH_NOARGS,
Expand Down Expand Up @@ -1254,11 +1254,12 @@ mappingproxy.__new__ as mappingproxy_new

mapping: object

Read-only proxy of a mapping.
[clinic start generated code]*/

static PyObject *
mappingproxy_new_impl(PyTypeObject *type, PyObject *mapping)
/*[clinic end generated code: output=65f27f02d5b68fa7 input=d2d620d4f598d4f8]*/
/*[clinic end generated code: output=65f27f02d5b68fa7 input=c156df096ef7590c]*/
{
mappingproxyobject *mappingproxy;

Expand Down Expand Up @@ -2024,7 +2025,7 @@ PyTypeObject PyDictProxy_Type = {
0, /* tp_as_buffer */
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC |
Py_TPFLAGS_MAPPING, /* tp_flags */
0, /* tp_doc */
mappingproxy_new__doc__, /* tp_doc */
mappingproxy_traverse, /* tp_traverse */
0, /* tp_clear */
mappingproxy_richcompare, /* tp_richcompare */
Expand Down
2 changes: 2 additions & 0 deletions Objects/genericaliasobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -537,6 +537,8 @@ _Py_subs_parameters(PyObject *self, PyObject *args, PyObject *parameters, PyObje
}

PyDoc_STRVAR(genericalias__doc__,
"GenericAlias(origin, args, /)\n"
"--\n\n"
"Represent a PEP 585 generic type\n"
"\n"
"E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).");
Expand Down
5 changes: 4 additions & 1 deletion Objects/memoryobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3255,6 +3255,9 @@ PyDoc_STRVAR(memory_f_contiguous_doc,
"A bool indicating whether the memory is Fortran contiguous.");
PyDoc_STRVAR(memory_contiguous_doc,
"A bool indicating whether the memory is contiguous.");
PyDoc_STRVAR(memory_exit_doc,
"__exit__($self, /, *exc_info)\n--\n\n"
"Release the underlying buffer exposed by the memoryview object.");
Comment on lines +3258 to +3260
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
PyDoc_STRVAR(memory_exit_doc,
"__exit__($self, /, *exc_info)\n--\n\n"
"Release the underlying buffer exposed by the memoryview object.");
PyDoc_STRVAR(memory_enter_doc,
"__enter__($self)\n--\n\n"
"Check the underlying buffer has not been released.");
PyDoc_STRVAR(memory_exit_doc,
"__exit__($self, /, *exc_info)\n--\n\n"
"Release the underlying buffer exposed by the memoryview object.");

(maybe the signature for enter is not correct, it returns a reference to itself)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is rather the side effect.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left this for future. The __enter__ methods either acquire the resource, in which case it should be explicitly documented, or do not have a side effect, in which case they do not need a docstring. I am not sure what is closer to this case.



static PyGetSetDef memory_getsetlist[] = {
Expand Down Expand Up @@ -3283,7 +3286,7 @@ static PyMethodDef memory_methods[] = {
MEMORYVIEW_TOREADONLY_METHODDEF
MEMORYVIEW__FROM_FLAGS_METHODDEF
{"__enter__", memory_enter, METH_NOARGS, NULL},
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{"__enter__", memory_enter, METH_NOARGS, NULL},
{"__enter__", memory_enter, METH_NOARGS, memory_enter_doc},

{"__exit__", memory_exit, METH_VARARGS, NULL},
{"__exit__", memory_exit, METH_VARARGS, memory_exit_doc},
{NULL, NULL}
};

Expand Down
6 changes: 3 additions & 3 deletions Objects/namespaceobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,9 +225,9 @@ static PyMethodDef namespace_methods[] = {


PyDoc_STRVAR(namespace_doc,
"A simple attribute-based namespace.\n\
\n\
SimpleNamespace(**kwargs)");
"SimpleNamespace(**kwargs)\n\
--\n\n\
A simple attribute-based namespace.");

PyTypeObject _PyNamespace_Type = {
PyVarObject_HEAD_INIT(&PyType_Type, 0)
Expand Down
2 changes: 1 addition & 1 deletion Objects/rangeobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -751,7 +751,7 @@ PyDoc_STRVAR(index_doc,

static PyMethodDef range_methods[] = {
{"__reversed__", range_reverse, METH_NOARGS, reverse_doc},
{"__reduce__", (PyCFunction)range_reduce, METH_VARARGS},
{"__reduce__", (PyCFunction)range_reduce, METH_NOARGS},
{"count", (PyCFunction)range_count, METH_O, count_doc},
{"index", (PyCFunction)range_index, METH_O, index_doc},
{NULL, NULL} /* sentinel */
Expand Down
9 changes: 6 additions & 3 deletions Objects/typeobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6871,7 +6871,7 @@ static PyMethodDef object_methods[] = {
OBJECT___REDUCE_EX___METHODDEF
OBJECT___REDUCE___METHODDEF
OBJECT___GETSTATE___METHODDEF
{"__subclasshook__", object_subclasshook, METH_CLASS | METH_VARARGS,
{"__subclasshook__", object_subclasshook, METH_CLASS | METH_O,
object_subclasshook_doc},
{"__init_subclass__", object_init_subclass, METH_CLASS | METH_NOARGS,
object_init_subclass_doc},
Expand Down Expand Up @@ -9847,7 +9847,8 @@ static pytype_slotdef slotdefs[] = {
TPSLOT(__getattribute__, tp_getattro, _Py_slot_tp_getattr_hook,
wrap_binaryfunc,
"__getattribute__($self, name, /)\n--\n\nReturn getattr(self, name)."),
TPSLOT(__getattr__, tp_getattro, _Py_slot_tp_getattr_hook, NULL, ""),
TPSLOT(__getattr__, tp_getattro, _Py_slot_tp_getattr_hook, NULL,
"__getattr__($self, name, /)\n--\n\nImplement getattr(self, name)."),
TPSLOT(__setattr__, tp_setattro, slot_tp_setattro, wrap_setattr,
"__setattr__($self, name, value, /)\n--\n\nImplement setattr(self, name, value)."),
TPSLOT(__delattr__, tp_setattro, slot_tp_setattro, wrap_delattr,
Expand Down Expand Up @@ -9882,7 +9883,9 @@ static pytype_slotdef slotdefs[] = {
TPSLOT(__new__, tp_new, slot_tp_new, NULL,
"__new__(type, /, *args, **kwargs)\n--\n\n"
"Create and return new object. See help(type) for accurate signature."),
TPSLOT(__del__, tp_finalize, slot_tp_finalize, (wrapperfunc)wrap_del, ""),
TPSLOT(__del__, tp_finalize, slot_tp_finalize, (wrapperfunc)wrap_del,
"__del__($self, /)\n--\n\n"
"Called when the instance is about to be destroyed."),

BUFSLOT(__buffer__, bf_getbuffer, slot_bf_getbuffer, wrap_buffer,
"__buffer__($self, flags, /)\n--\n\n"
Expand Down
10 changes: 5 additions & 5 deletions Python/bltinmodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,7 +475,7 @@ builtin_breakpoint(PyObject *self, PyObject *const *args, Py_ssize_t nargs, PyOb
}

PyDoc_STRVAR(breakpoint_doc,
"breakpoint(*args, **kws)\n\
"breakpoint($module, /, *args, **kws)\n\
--\n\
\n\
Call sys.breakpointhook(*args, **kws). sys.breakpointhook() must accept\n\
Expand Down Expand Up @@ -1703,16 +1703,16 @@ anext as builtin_anext
default: object = NULL
/

async anext(aiterator[, default])
Return the next item from the async iterator.

Return the next item from the async iterator. If default is given and the async
iterator is exhausted, it is returned instead of raising StopAsyncIteration.
If default is given and the async iterator is exhausted,
it is returned instead of raising StopAsyncIteration.
[clinic start generated code]*/

static PyObject *
builtin_anext_impl(PyObject *module, PyObject *aiterator,
PyObject *default_value)
/*[clinic end generated code: output=f02c060c163a81fa input=8f63f4f78590bb4c]*/
/*[clinic end generated code: output=f02c060c163a81fa input=2900e4a370d39550]*/
{
PyTypeObject *t;
PyObject *awaitable;
Expand Down
8 changes: 4 additions & 4 deletions Python/clinic/bltinmodule.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions Python/clinic/traceback.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions Python/traceback.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,9 @@
extern char* _PyTokenizer_FindEncodingFilename(int, PyObject *);

/*[clinic input]
class TracebackType "PyTracebackObject *" "&PyTraceback_Type"
class traceback "PyTracebackObject *" "&PyTraceback_Type"
[clinic start generated code]*/
/*[clinic end generated code: output=da39a3ee5e6b4b0d input=928fa06c10151120]*/
/*[clinic end generated code: output=da39a3ee5e6b4b0d input=cf96294b2bebc811]*/

#include "clinic/traceback.c.h"

Expand All @@ -63,7 +63,7 @@ tb_create_raw(PyTracebackObject *next, PyFrameObject *frame, int lasti,

/*[clinic input]
@classmethod
TracebackType.__new__ as tb_new
traceback.__new__ as tb_new

tb_next: object
tb_frame: object(type='PyFrameObject *', subclass_of='&PyFrame_Type')
Expand All @@ -76,7 +76,7 @@ Create a new traceback object.
static PyObject *
tb_new_impl(PyTypeObject *type, PyObject *tb_next, PyFrameObject *tb_frame,
int tb_lasti, int tb_lineno)
/*[clinic end generated code: output=fa077debd72d861a input=01cbe8ec8783fca7]*/
/*[clinic end generated code: output=fa077debd72d861a input=b88143145454cb59]*/
{
if (tb_next == Py_None) {
tb_next = NULL;
Expand Down