mirror of
https://github.com/python/cpython
synced 2024-09-05 00:05:39 +00:00
gh-111999: Add signatures and improve docstrings for builtins (GH-112000)
This commit is contained in:
parent
d0058cbd1c
commit
1d75ef6b61
|
@ -4734,12 +4734,13 @@ def test_builtins_have_signatures(self):
|
|||
needs_null = {"anext"}
|
||||
no_signature |= needs_null
|
||||
# These need *args support in Argument Clinic
|
||||
needs_varargs = {"breakpoint", "min", "max", "__build_class__"}
|
||||
needs_varargs = {"min", "max", "__build_class__"}
|
||||
no_signature |= needs_varargs
|
||||
# These builtin types are expected to provide introspection info
|
||||
types_with_signatures = {
|
||||
'complex', 'enumerate', 'float', 'list', 'memoryview', 'object',
|
||||
'property', 'reversed', 'tuple',
|
||||
'bool', 'classmethod', 'complex', 'enumerate', 'filter', 'float',
|
||||
'frozenset', 'list', 'map', 'memoryview', 'object', 'property',
|
||||
'reversed', 'set', 'staticmethod', 'tuple', 'zip'
|
||||
}
|
||||
# Check the signatures we expect to be there
|
||||
ns = vars(builtins)
|
||||
|
@ -4753,6 +4754,10 @@ def test_builtins_have_signatures(self):
|
|||
if (name in no_signature):
|
||||
# Not yet converted
|
||||
continue
|
||||
if name in {'classmethod', 'staticmethod'}:
|
||||
# Bug gh-112006: inspect.unwrap() does not work with types
|
||||
# with the __wrapped__ data descriptor.
|
||||
continue
|
||||
with self.subTest(builtin=name):
|
||||
self.assertIsNotNone(inspect.signature(obj))
|
||||
# Check callables that haven't been converted don't claim a signature
|
||||
|
|
|
@ -110,9 +110,10 @@ bool_xor(PyObject *a, PyObject *b)
|
|||
/* Doc string */
|
||||
|
||||
PyDoc_STRVAR(bool_doc,
|
||||
"bool(x) -> bool\n\
|
||||
"bool(object=False, /)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Returns True when the argument x is true, False otherwise.\n\
|
||||
Returns True when the argument is true, False otherwise.\n\
|
||||
The builtins True and False are the only two instances of the class bool.\n\
|
||||
The class bool is a subclass of the class int, and cannot be subclassed.");
|
||||
|
||||
|
|
|
@ -1541,6 +1541,9 @@ property_deleter(PyObject *self, PyObject *deleter)
|
|||
|
||||
|
||||
PyDoc_STRVAR(set_name_doc,
|
||||
"__set_name__($self, owner, name, /)\n"
|
||||
"--\n"
|
||||
"\n"
|
||||
"Method to set name of a property.");
|
||||
|
||||
static PyObject *
|
||||
|
|
|
@ -1164,7 +1164,8 @@ cm_repr(classmethod *cm)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(classmethod_doc,
|
||||
"classmethod(function) -> method\n\
|
||||
"classmethod(function, /)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Convert a function to be a class method.\n\
|
||||
\n\
|
||||
|
@ -1359,7 +1360,8 @@ sm_repr(staticmethod *sm)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(staticmethod_doc,
|
||||
"staticmethod(function) -> method\n\
|
||||
"staticmethod(function, /)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Convert a function to be a static method.\n\
|
||||
\n\
|
||||
|
|
|
@ -942,7 +942,10 @@ set_update(PySetObject *so, PyObject *args)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(update_doc,
|
||||
"Update a set with the union of itself and others.");
|
||||
"update($self, /, *others)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Update the set, adding elements from all others.");
|
||||
|
||||
/* XXX Todo:
|
||||
If aligned memory allocations become available, make the
|
||||
|
@ -1141,9 +1144,10 @@ set_union(PySetObject *so, PyObject *args)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(union_doc,
|
||||
"Return the union of sets as a new set.\n\
|
||||
"union($self, /, *others)\n\
|
||||
--\n\
|
||||
\n\
|
||||
(i.e. all elements that are in either set.)");
|
||||
Return a new set with elements from the set and all others.");
|
||||
|
||||
static PyObject *
|
||||
set_or(PySetObject *so, PyObject *other)
|
||||
|
@ -1281,9 +1285,10 @@ set_intersection_multi(PySetObject *so, PyObject *args)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(intersection_doc,
|
||||
"Return the intersection of two sets as a new set.\n\
|
||||
"intersection($self, /, *others)\n\
|
||||
--\n\
|
||||
\n\
|
||||
(i.e. all elements that are in both sets.)");
|
||||
Return a new set with elements common to the set and all others.");
|
||||
|
||||
static PyObject *
|
||||
set_intersection_update(PySetObject *so, PyObject *other)
|
||||
|
@ -1312,7 +1317,10 @@ set_intersection_update_multi(PySetObject *so, PyObject *args)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(intersection_update_doc,
|
||||
"Update a set with the intersection of itself and another.");
|
||||
"intersection_update($self, /, *others)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Update the set, keeping only elements found in it and all others.");
|
||||
|
||||
static PyObject *
|
||||
set_and(PySetObject *so, PyObject *other)
|
||||
|
@ -1470,7 +1478,10 @@ set_difference_update(PySetObject *so, PyObject *args)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(difference_update_doc,
|
||||
"Remove all elements of another set from this set.");
|
||||
"difference_update($self, /, *others)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Update the set, removing elements found in others.");
|
||||
|
||||
static PyObject *
|
||||
set_copy_and_difference(PySetObject *so, PyObject *other)
|
||||
|
@ -1587,9 +1598,10 @@ set_difference_multi(PySetObject *so, PyObject *args)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(difference_doc,
|
||||
"Return the difference of two or more sets as a new set.\n\
|
||||
"difference($self, /, *others)\n\
|
||||
--\n\
|
||||
\n\
|
||||
(i.e. all elements that are in this set but not the others.)");
|
||||
Return a new set with elements in the set that are not in the others.");
|
||||
static PyObject *
|
||||
set_sub(PySetObject *so, PyObject *other)
|
||||
{
|
||||
|
@ -1673,7 +1685,10 @@ set_symmetric_difference_update(PySetObject *so, PyObject *other)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(symmetric_difference_update_doc,
|
||||
"Update a set with the symmetric difference of itself and another.");
|
||||
"symmetric_difference_update($self, other, /)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Update the set, keeping only elements found in either set, but not in both.");
|
||||
|
||||
static PyObject *
|
||||
set_symmetric_difference(PySetObject *so, PyObject *other)
|
||||
|
@ -1694,9 +1709,10 @@ set_symmetric_difference(PySetObject *so, PyObject *other)
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(symmetric_difference_doc,
|
||||
"Return the symmetric difference of two sets as a new set.\n\
|
||||
"symmetric_difference($self, other, /)\n\
|
||||
--\n\
|
||||
\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.");
|
||||
|
||||
static PyObject *
|
||||
set_xor(PySetObject *so, PyObject *other)
|
||||
|
@ -2100,8 +2116,8 @@ static PyNumberMethods set_as_number = {
|
|||
};
|
||||
|
||||
PyDoc_STRVAR(set_doc,
|
||||
"set() -> new empty set object\n\
|
||||
set(iterable) -> new set object\n\
|
||||
"set(iterable=(), /)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Build an unordered collection of unique elements.");
|
||||
|
||||
|
@ -2201,8 +2217,8 @@ static PyNumberMethods frozenset_as_number = {
|
|||
};
|
||||
|
||||
PyDoc_STRVAR(frozenset_doc,
|
||||
"frozenset() -> empty frozenset object\n\
|
||||
frozenset(iterable) -> frozenset object\n\
|
||||
"frozenset(iterable=(), /)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Build an immutable unordered collection of unique elements.");
|
||||
|
||||
|
|
|
@ -5254,8 +5254,10 @@ static PyMethodDef type_methods[] = {
|
|||
TYPE___SUBCLASSES___METHODDEF
|
||||
{"__prepare__", _PyCFunction_CAST(type_prepare),
|
||||
METH_FASTCALL | METH_KEYWORDS | METH_CLASS,
|
||||
PyDoc_STR("__prepare__() -> dict\n"
|
||||
"used to create the namespace for the class statement")},
|
||||
PyDoc_STR("__prepare__($cls, name, bases, /, **kwds)\n"
|
||||
"--\n"
|
||||
"\n"
|
||||
"Create the namespace for the class statement")},
|
||||
TYPE___INSTANCECHECK___METHODDEF
|
||||
TYPE___SUBCLASSCHECK___METHODDEF
|
||||
TYPE___DIR___METHODDEF
|
||||
|
|
|
@ -13390,15 +13390,17 @@ _PyUnicodeWriter_Dealloc(_PyUnicodeWriter *writer)
|
|||
#include "stringlib/unicode_format.h"
|
||||
|
||||
PyDoc_STRVAR(format__doc__,
|
||||
"S.format(*args, **kwargs) -> str\n\
|
||||
"format($self, /, *args, **kwargs)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Return a formatted version of S, using substitutions from args and kwargs.\n\
|
||||
Return a formatted version of the string, using substitutions from args and kwargs.\n\
|
||||
The substitutions are identified by braces ('{' and '}').");
|
||||
|
||||
PyDoc_STRVAR(format_map__doc__,
|
||||
"S.format_map(mapping) -> str\n\
|
||||
"format_map($self, /, mapping)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Return a formatted version of S, using substitutions from mapping.\n\
|
||||
Return a formatted version of the string, using substitutions from mapping.\n\
|
||||
The substitutions are identified by braces ('{' and '}').");
|
||||
|
||||
/*[clinic input]
|
||||
|
@ -14696,7 +14698,7 @@ errors is specified, then the object must expose a data buffer\n\
|
|||
that will be decoded using the given encoding and error handler.\n\
|
||||
Otherwise, returns the result of object.__str__() (if defined)\n\
|
||||
or repr(object).\n\
|
||||
encoding defaults to sys.getdefaultencoding().\n\
|
||||
encoding defaults to 'utf-8'.\n\
|
||||
errors defaults to 'strict'.");
|
||||
|
||||
static PyObject *unicode_iter(PyObject *seq);
|
||||
|
|
|
@ -482,6 +482,7 @@ builtin_breakpoint(PyObject *self, PyObject *const *args, Py_ssize_t nargs, PyOb
|
|||
|
||||
PyDoc_STRVAR(breakpoint_doc,
|
||||
"breakpoint(*args, **kws)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Call sys.breakpointhook(*args, **kws). sys.breakpointhook() must accept\n\
|
||||
whatever arguments are passed.\n\
|
||||
|
@ -626,7 +627,8 @@ static PyMethodDef filter_methods[] = {
|
|||
};
|
||||
|
||||
PyDoc_STRVAR(filter_doc,
|
||||
"filter(function or None, iterable) --> filter object\n\
|
||||
"filter(function, iterable, /)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Return an iterator yielding those items of iterable for which function(item)\n\
|
||||
is true. If function is None, return the items that are true.");
|
||||
|
@ -1449,7 +1451,8 @@ static PyMethodDef map_methods[] = {
|
|||
|
||||
|
||||
PyDoc_STRVAR(map_doc,
|
||||
"map(func, *iterables) --> map object\n\
|
||||
"map(function, /, *iterables)\n\
|
||||
--\n\
|
||||
\n\
|
||||
Make an iterator that computes the function using arguments from\n\
|
||||
each of the iterables. Stops when the shortest iterable is exhausted.");
|
||||
|
@ -1888,7 +1891,7 @@ min(arg1, arg2, *args, *[, key=func]) -> value\n\
|
|||
With a single iterable argument, return its smallest item. The\n\
|
||||
default keyword-only argument specifies an object to return if\n\
|
||||
the provided iterable is empty.\n\
|
||||
With two or more arguments, return the smallest argument.");
|
||||
With two or more positional arguments, return the smallest argument.");
|
||||
|
||||
|
||||
/* AC: cannot convert yet, waiting for *args support */
|
||||
|
@ -1905,7 +1908,7 @@ max(arg1, arg2, *args, *[, key=func]) -> value\n\
|
|||
With a single iterable argument, return its biggest item. The\n\
|
||||
default keyword-only argument specifies an object to return if\n\
|
||||
the provided iterable is empty.\n\
|
||||
With two or more arguments, return the largest argument.");
|
||||
With two or more positional arguments, return the largest argument.");
|
||||
|
||||
|
||||
/*[clinic input]
|
||||
|
@ -2958,10 +2961,8 @@ static PyMethodDef zip_methods[] = {
|
|||
};
|
||||
|
||||
PyDoc_STRVAR(zip_doc,
|
||||
"zip(*iterables, strict=False) --> Yield tuples until an input is exhausted.\n\
|
||||
\n\
|
||||
>>> list(zip('abcdefg', range(3), range(4)))\n\
|
||||
[('a', 0, 0), ('b', 1, 1), ('c', 2, 2)]\n\
|
||||
"zip(*iterables, strict=False)\n\
|
||||
--\n\
|
||||
\n\
|
||||
The zip object yields n-length tuples, where n is the number of iterables\n\
|
||||
passed as positional arguments to zip(). The i-th element in every tuple\n\
|
||||
|
@ -2969,7 +2970,10 @@ comes from the i-th iterable argument to zip(). This continues until the\n\
|
|||
shortest argument is exhausted.\n\
|
||||
\n\
|
||||
If strict is true and one of the arguments is exhausted before the others,\n\
|
||||
raise a ValueError.");
|
||||
raise a ValueError.\n\
|
||||
\n\
|
||||
>>> list(zip('abcdefg', range(3), range(4)))\n\
|
||||
[('a', 0, 0), ('b', 1, 1), ('c', 2, 2)]");
|
||||
|
||||
PyTypeObject PyZip_Type = {
|
||||
PyVarObject_HEAD_INIT(&PyType_Type, 0)
|
||||
|
|
Loading…
Reference in a new issue