bpo-42528: Improve the docs of most Py*_Check{,Exact} API calls (GH-23602)

I think that none of these API calls can fail, but only few of them are
documented as such. Add the sentence "This function always succeeds" (which is
the same already used e.g. by PyNumber_Check) to all of them.
This commit is contained in:
Antonio Cuni 2021-01-06 12:38:26 +01:00 committed by GitHub
parent 1a9f51ed12
commit 315fc52db1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 74 additions and 52 deletions

View File

@ -13,7 +13,8 @@ are available, however.
.. c:function:: int PyBool_Check(PyObject *o) .. c:function:: int PyBool_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyBool_Type`. Return true if *o* is of type :c:data:`PyBool_Type`. This function always
succeeds.
.. c:var:: PyObject* Py_False .. c:var:: PyObject* Py_False

View File

@ -25,13 +25,13 @@ Type check macros
.. c:function:: int PyByteArray_Check(PyObject *o) .. c:function:: int PyByteArray_Check(PyObject *o)
Return true if the object *o* is a bytearray object or an instance of a Return true if the object *o* is a bytearray object or an instance of a
subtype of the bytearray type. subtype of the bytearray type. This function always succeeds.
.. c:function:: int PyByteArray_CheckExact(PyObject *o) .. c:function:: int PyByteArray_CheckExact(PyObject *o)
Return true if the object *o* is a bytearray object, but not an instance of a Return true if the object *o* is a bytearray object, but not an instance of a
subtype of the bytearray type. subtype of the bytearray type. This function always succeeds.
Direct API functions Direct API functions

View File

@ -25,13 +25,13 @@ called with a non-bytes parameter.
.. c:function:: int PyBytes_Check(PyObject *o) .. c:function:: int PyBytes_Check(PyObject *o)
Return true if the object *o* is a bytes object or an instance of a subtype Return true if the object *o* is a bytes object or an instance of a subtype
of the bytes type. of the bytes type. This function always succeeds.
.. c:function:: int PyBytes_CheckExact(PyObject *o) .. c:function:: int PyBytes_CheckExact(PyObject *o)
Return true if the object *o* is a bytes object, but not an instance of a Return true if the object *o* is a bytes object, but not an instance of a
subtype of the bytes type. subtype of the bytes type. This function always succeeds.
.. c:function:: PyObject* PyBytes_FromString(const char *v) .. c:function:: PyObject* PyBytes_FromString(const char *v)

View File

@ -34,7 +34,8 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: int PyCapsule_CheckExact(PyObject *p) .. c:function:: int PyCapsule_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyCapsule`. Return true if its argument is a :c:type:`PyCapsule`. This function always
succeeds.
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor) .. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

View File

@ -27,7 +27,8 @@ Cell objects are not likely to be useful elsewhere.
.. c:function:: int PyCell_Check(ob) .. c:function:: int PyCell_Check(ob)
Return true if *ob* is a cell object; *ob* must not be ``NULL``. Return true if *ob* is a cell object; *ob* must not be ``NULL``. This
function always succeeds.
.. c:function:: PyObject* PyCell_New(PyObject *ob) .. c:function:: PyObject* PyCell_New(PyObject *ob)

View File

@ -27,7 +27,7 @@ bound into a function.
.. c:function:: int PyCode_Check(PyObject *co) .. c:function:: int PyCode_Check(PyObject *co)
Return true if *co* is a :class:`code` object. Return true if *co* is a :class:`code` object. This function always succeeds.
.. c:function:: int PyCode_GetNumFree(PyCodeObject *co) .. c:function:: int PyCode_GetNumFree(PyCodeObject *co)

View File

@ -94,13 +94,13 @@ Complex Numbers as Python Objects
.. c:function:: int PyComplex_Check(PyObject *p) .. c:function:: int PyComplex_Check(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject` or a subtype of Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
:c:type:`PyComplexObject`. :c:type:`PyComplexObject`. This function always succeeds.
.. c:function:: int PyComplex_CheckExact(PyObject *p) .. c:function:: int PyComplex_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
:c:type:`PyComplexObject`. :c:type:`PyComplexObject`. This function always succeeds.
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v) .. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)

View File

@ -24,6 +24,7 @@ return.
.. c:function:: int PyCoro_CheckExact(PyObject *ob) .. c:function:: int PyCoro_CheckExact(PyObject *ob)
Return true if *ob*'s type is :c:type:`PyCoro_Type`; *ob* must not be ``NULL``. Return true if *ob*'s type is :c:type:`PyCoro_Type`; *ob* must not be ``NULL``.
This function always succeeds.
.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname) .. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)

View File

@ -28,61 +28,66 @@ Type-check macros:
.. c:function:: int PyDate_Check(PyObject *ob) .. c:function:: int PyDate_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
:c:data:`PyDateTime_DateType`. *ob* must not be ``NULL``. :c:data:`PyDateTime_DateType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyDate_CheckExact(PyObject *ob) .. c:function:: int PyDate_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
``NULL``. ``NULL``. This function always succeeds.
.. c:function:: int PyDateTime_Check(PyObject *ob) .. c:function:: int PyDateTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
:c:data:`PyDateTime_DateTimeType`. *ob* must not be ``NULL``. :c:data:`PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyDateTime_CheckExact(PyObject *ob) .. c:function:: int PyDateTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
be ``NULL``. be ``NULL``. This function always succeeds.
.. c:function:: int PyTime_Check(PyObject *ob) .. c:function:: int PyTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
:c:data:`PyDateTime_TimeType`. *ob* must not be ``NULL``. :c:data:`PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyTime_CheckExact(PyObject *ob) .. c:function:: int PyTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
``NULL``. ``NULL``. This function always succeeds.
.. c:function:: int PyDelta_Check(PyObject *ob) .. c:function:: int PyDelta_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
:c:data:`PyDateTime_DeltaType`. *ob* must not be ``NULL``. :c:data:`PyDateTime_DeltaType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyDelta_CheckExact(PyObject *ob) .. c:function:: int PyDelta_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
``NULL``. ``NULL``. This function always succeeds.
.. c:function:: int PyTZInfo_Check(PyObject *ob) .. c:function:: int PyTZInfo_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
:c:data:`PyDateTime_TZInfoType`. *ob* must not be ``NULL``. :c:data:`PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob) .. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
``NULL``. ``NULL``. This function always succeeds.
Macros to create objects: Macros to create objects:

View File

@ -22,13 +22,13 @@ Dictionary Objects
.. c:function:: int PyDict_Check(PyObject *p) .. c:function:: int PyDict_Check(PyObject *p)
Return true if *p* is a dict object or an instance of a subtype of the dict Return true if *p* is a dict object or an instance of a subtype of the dict
type. type. This function always succeeds.
.. c:function:: int PyDict_CheckExact(PyObject *p) .. c:function:: int PyDict_CheckExact(PyObject *p)
Return true if *p* is a dict object, but not an instance of a subtype of Return true if *p* is a dict object, but not an instance of a subtype of
the dict type. the dict type. This function always succeeds.
.. c:function:: PyObject* PyDict_New() .. c:function:: PyObject* PyDict_New()

View File

@ -22,13 +22,13 @@ Floating Point Objects
.. c:function:: int PyFloat_Check(PyObject *p) .. c:function:: int PyFloat_Check(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
:c:type:`PyFloatObject`. :c:type:`PyFloatObject`. This function always succeeds.
.. c:function:: int PyFloat_CheckExact(PyObject *p) .. c:function:: int PyFloat_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
:c:type:`PyFloatObject`. :c:type:`PyFloatObject`. This function always succeeds.
.. c:function:: PyObject* PyFloat_FromString(PyObject *str) .. c:function:: PyObject* PyFloat_FromString(PyObject *str)

View File

@ -26,7 +26,7 @@ There are a few functions specific to Python functions.
.. c:function:: int PyFunction_Check(PyObject *o) .. c:function:: int PyFunction_Check(PyObject *o)
Return true if *o* is a function object (has type :c:data:`PyFunction_Type`). Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
The parameter must not be ``NULL``. The parameter must not be ``NULL``. This function always succeeds.
.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals) .. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)

View File

@ -22,12 +22,14 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
.. c:function:: int PyGen_Check(PyObject *ob) .. c:function:: int PyGen_Check(PyObject *ob)
Return true if *ob* is a generator object; *ob* must not be ``NULL``. Return true if *ob* is a generator object; *ob* must not be ``NULL``. This
function always succeeds.
.. c:function:: int PyGen_CheckExact(PyObject *ob) .. c:function:: int PyGen_CheckExact(PyObject *ob)
Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be ``NULL``. Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be
``NULL``. This function always succeeds.
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame) .. c:function:: PyObject* PyGen_New(PyFrameObject *frame)

View File

@ -9,7 +9,8 @@ There are two functions specifically for working with iterators.
.. c:function:: int PyIter_Check(PyObject *o) .. c:function:: int PyIter_Check(PyObject *o)
Return true if the object *o* supports the iterator protocol. Return true if the object *o* supports the iterator protocol. This
function always succeeds.
.. c:function:: PyObject* PyIter_Next(PyObject *o) .. c:function:: PyObject* PyIter_Next(PyObject *o)

View File

@ -21,7 +21,8 @@ sentinel value is returned.
.. c:function:: int PySeqIter_Check(op) .. c:function:: int PySeqIter_Check(op)
Return true if the type of *op* is :c:data:`PySeqIter_Type`. Return true if the type of *op* is :c:data:`PySeqIter_Type`. This function
always succeeds.
.. c:function:: PyObject* PySeqIter_New(PyObject *seq) .. c:function:: PyObject* PySeqIter_New(PyObject *seq)
@ -39,7 +40,8 @@ sentinel value is returned.
.. c:function:: int PyCallIter_Check(op) .. c:function:: int PyCallIter_Check(op)
Return true if the type of *op* is :c:data:`PyCallIter_Type`. Return true if the type of *op* is :c:data:`PyCallIter_Type`. This
function always succeeds.
.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel) .. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)

View File

@ -22,13 +22,13 @@ List Objects
.. c:function:: int PyList_Check(PyObject *p) .. c:function:: int PyList_Check(PyObject *p)
Return true if *p* is a list object or an instance of a subtype of the list Return true if *p* is a list object or an instance of a subtype of the list
type. type. This function always succeeds.
.. c:function:: int PyList_CheckExact(PyObject *p) .. c:function:: int PyList_CheckExact(PyObject *p)
Return true if *p* is a list object, but not an instance of a subtype of Return true if *p* is a list object, but not an instance of a subtype of
the list type. the list type. This function always succeeds.
.. c:function:: PyObject* PyList_New(Py_ssize_t len) .. c:function:: PyObject* PyList_New(Py_ssize_t len)

View File

@ -27,13 +27,13 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: int PyLong_Check(PyObject *p) .. c:function:: int PyLong_Check(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject` or a subtype of Return true if its argument is a :c:type:`PyLongObject` or a subtype of
:c:type:`PyLongObject`. :c:type:`PyLongObject`. This function always succeeds.
.. c:function:: int PyLong_CheckExact(PyObject *p) .. c:function:: int PyLong_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
:c:type:`PyLongObject`. :c:type:`PyLongObject`. This function always succeeds.
.. c:function:: PyObject* PyLong_FromLong(long v) .. c:function:: PyObject* PyLong_FromLong(long v)

View File

@ -45,7 +45,8 @@ any other object.
.. c:function:: int PyMemoryView_Check(PyObject *obj) .. c:function:: int PyMemoryView_Check(PyObject *obj)
Return true if the object *obj* is a memoryview object. It is not Return true if the object *obj* is a memoryview object. It is not
currently allowed to create subclasses of :class:`memoryview`. currently allowed to create subclasses of :class:`memoryview`. This
function always succeeds.
.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview) .. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)

View File

@ -22,6 +22,7 @@ to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
Return true if *o* is an instance method object (has type Return true if *o* is an instance method object (has type
:c:data:`PyInstanceMethod_Type`). The parameter must not be ``NULL``. :c:data:`PyInstanceMethod_Type`). The parameter must not be ``NULL``.
This function always succeeds.
.. c:function:: PyObject* PyInstanceMethod_New(PyObject *func) .. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
@ -64,7 +65,7 @@ no longer available.
.. c:function:: int PyMethod_Check(PyObject *o) .. c:function:: int PyMethod_Check(PyObject *o)
Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The
parameter must not be ``NULL``. parameter must not be ``NULL``. This function always succeeds.
.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self) .. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self)

View File

@ -19,12 +19,13 @@ Module Objects
.. c:function:: int PyModule_Check(PyObject *p) .. c:function:: int PyModule_Check(PyObject *p)
Return true if *p* is a module object, or a subtype of a module object. Return true if *p* is a module object, or a subtype of a module object.
This function always succeeds.
.. c:function:: int PyModule_CheckExact(PyObject *p) .. c:function:: int PyModule_CheckExact(PyObject *p)
Return true if *p* is a module object, but not a subtype of Return true if *p* is a module object, but not a subtype of
:c:data:`PyModule_Type`. :c:data:`PyModule_Type`. This function always succeeds.
.. c:function:: PyObject* PyModule_NewObject(PyObject *name) .. c:function:: PyObject* PyModule_NewObject(PyObject *name)

View File

@ -53,28 +53,29 @@ the constructor functions work with any iterable Python object.
.. c:function:: int PySet_Check(PyObject *p) .. c:function:: int PySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object or an instance of a subtype. Return true if *p* is a :class:`set` object or an instance of a subtype.
This function always succeeds.
.. c:function:: int PyFrozenSet_Check(PyObject *p) .. c:function:: int PyFrozenSet_Check(PyObject *p)
Return true if *p* is a :class:`frozenset` object or an instance of a Return true if *p* is a :class:`frozenset` object or an instance of a
subtype. subtype. This function always succeeds.
.. c:function:: int PyAnySet_Check(PyObject *p) .. c:function:: int PyAnySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
instance of a subtype. instance of a subtype. This function always succeeds.
.. c:function:: int PyAnySet_CheckExact(PyObject *p) .. c:function:: int PyAnySet_CheckExact(PyObject *p)
Return true if *p* is a :class:`set` object or a :class:`frozenset` object but Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
not an instance of a subtype. not an instance of a subtype. This function always succeeds.
.. c:function:: int PyFrozenSet_CheckExact(PyObject *p) .. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
Return true if *p* is a :class:`frozenset` object but not an instance of a Return true if *p* is a :class:`frozenset` object but not an instance of a
subtype. subtype. This function always succeeds.
.. c:function:: PyObject* PySet_New(PyObject *iterable) .. c:function:: PyObject* PySet_New(PyObject *iterable)

View File

@ -14,7 +14,8 @@ Slice Objects
.. c:function:: int PySlice_Check(PyObject *ob) .. c:function:: int PySlice_Check(PyObject *ob)
Return true if *ob* is a slice object; *ob* must not be ``NULL``. Return true if *ob* is a slice object; *ob* must not be ``NULL``. This
function always succeeds.
.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step) .. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)

View File

@ -21,14 +21,14 @@ Tuple Objects
.. c:function:: int PyTuple_Check(PyObject *p) .. c:function:: int PyTuple_Check(PyObject *p)
Return true if *p* is a tuple object or an instance of a subtype of the tuple Return true if *p* is a tuple object or an instance of a subtype of the
type. tuple type. This function always succeeds.
.. c:function:: int PyTuple_CheckExact(PyObject *p) .. c:function:: int PyTuple_CheckExact(PyObject *p)
Return true if *p* is a tuple object, but not an instance of a subtype of the Return true if *p* is a tuple object, but not an instance of a subtype of the
tuple type. tuple type. This function always succeeds.
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len) .. c:function:: PyObject* PyTuple_New(Py_ssize_t len)

View File

@ -23,12 +23,14 @@ Type Objects
Return non-zero if the object *o* is a type object, including instances of Return non-zero if the object *o* is a type object, including instances of
types derived from the standard type object. Return 0 in all other cases. types derived from the standard type object. Return 0 in all other cases.
This function always succeeds.
.. c:function:: int PyType_CheckExact(PyObject *o) .. c:function:: int PyType_CheckExact(PyObject *o)
Return non-zero if the object *o* is a type object, but not a subtype of the Return non-zero if the object *o* is a type object, but not a subtype of
standard type object. Return 0 in all other cases. the standard type object. Return 0 in all other cases. This function
always succeeds.
.. c:function:: unsigned int PyType_ClearCache() .. c:function:: unsigned int PyType_ClearCache()

View File

@ -91,13 +91,13 @@ access internal read-only data of Unicode objects:
.. c:function:: int PyUnicode_Check(PyObject *o) .. c:function:: int PyUnicode_Check(PyObject *o)
Return true if the object *o* is a Unicode object or an instance of a Unicode Return true if the object *o* is a Unicode object or an instance of a Unicode
subtype. subtype. This function always succeeds.
.. c:function:: int PyUnicode_CheckExact(PyObject *o) .. c:function:: int PyUnicode_CheckExact(PyObject *o)
Return true if the object *o* is a Unicode object, but not an instance of a Return true if the object *o* is a Unicode object, but not an instance of a
subtype. subtype. This function always succeeds.
.. c:function:: int PyUnicode_READY(PyObject *o) .. c:function:: int PyUnicode_READY(PyObject *o)

View File

@ -13,17 +13,18 @@ as much as it can.
.. c:function:: int PyWeakref_Check(ob) .. c:function:: int PyWeakref_Check(ob)
Return true if *ob* is either a reference or proxy object. Return true if *ob* is either a reference or proxy object. This function
always succeeds.
.. c:function:: int PyWeakref_CheckRef(ob) .. c:function:: int PyWeakref_CheckRef(ob)
Return true if *ob* is a reference object. Return true if *ob* is a reference object. This function always succeeds.
.. c:function:: int PyWeakref_CheckProxy(ob) .. c:function:: int PyWeakref_CheckProxy(ob)
Return true if *ob* is a proxy object. Return true if *ob* is a proxy object. This function always succeeds.
.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback) .. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)