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

Doc/c-api/bool.rst

@@ -13,7 +13,8 @@ are available, however.
 
 .. 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

Doc/c-api/bytearray.rst

@@ -25,13 +25,13 @@ Type check macros
 .. c:function:: int PyByteArray_Check(PyObject *o)
 
    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)
 
    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

Doc/c-api/bytes.rst

@@ -25,13 +25,13 @@ called with a non-bytes parameter.
 .. c:function:: int PyBytes_Check(PyObject *o)
 
    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)
 
    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)

Doc/c-api/capsule.rst

@@ -34,7 +34,8 @@ Refer to :ref:`using-capsules` for more information on using these objects.
 
 .. 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)

Doc/c-api/cell.rst

@@ -27,7 +27,8 @@ Cell objects are not likely to be useful elsewhere.
 
 .. 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)

Doc/c-api/code.rst

@@ -27,7 +27,7 @@ bound into a function.
 
 .. 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)
 

Doc/c-api/complex.rst

@@ -94,13 +94,13 @@ Complex Numbers as Python Objects
 .. c:function:: int PyComplex_Check(PyObject *p)
 
    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)
 
    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)

Doc/c-api/coro.rst

@@ -24,6 +24,7 @@ return.
 .. c:function:: int PyCoro_CheckExact(PyObject *ob)
 
    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)

Doc/c-api/datetime.rst

@@ -28,61 +28,66 @@ Type-check macros:
 .. c:function:: int PyDate_Check(PyObject *ob)
 
    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)
 
    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)
 
    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)
 
    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)
 
    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)
 
    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)
 
    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)
 
    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)
 
    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)
 
    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:

Doc/c-api/dict.rst

@@ -22,13 +22,13 @@ Dictionary Objects
 .. c:function:: int PyDict_Check(PyObject *p)
 
    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)
 
    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()

Doc/c-api/float.rst

@@ -22,13 +22,13 @@ Floating Point Objects
 .. c:function:: int PyFloat_Check(PyObject *p)
 
    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)
 
    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)

Doc/c-api/function.rst

@@ -26,7 +26,7 @@ There are a few functions specific to Python functions.
 .. c:function:: int PyFunction_Check(PyObject *o)
 
    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)

Doc/c-api/gen.rst

@@ -22,12 +22,14 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
 
 .. 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)
 
-   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)

Doc/c-api/iter.rst

@@ -9,7 +9,8 @@ There are two functions specifically for working with iterators.
 
 .. 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)

Doc/c-api/iterator.rst

@@ -21,7 +21,8 @@ sentinel value is returned.
 
 .. 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)
@@ -39,7 +40,8 @@ sentinel value is returned.
 
 .. 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)

Doc/c-api/list.rst

@@ -22,13 +22,13 @@ List Objects
 .. c:function:: int PyList_Check(PyObject *p)
 
    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)
 
    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)

Doc/c-api/long.rst

@@ -27,13 +27,13 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 .. c:function:: int PyLong_Check(PyObject *p)
 
    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)
 
    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)

Doc/c-api/memoryview.rst

@@ -45,7 +45,8 @@ any other object.
 .. c:function:: int PyMemoryView_Check(PyObject *obj)
 
    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)

Doc/c-api/method.rst

@@ -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
    :c:data:`PyInstanceMethod_Type`).  The parameter must not be ``NULL``.
+   This function always succeeds.
 
 
 .. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
@@ -64,7 +65,7 @@ no longer available.
 .. c:function:: int PyMethod_Check(PyObject *o)
 
    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)

Doc/c-api/module.rst

@@ -19,12 +19,13 @@ Module Objects
 .. c:function:: int PyModule_Check(PyObject *p)
 
    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)
 
    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)

Doc/c-api/set.rst

@@ -53,28 +53,29 @@ the constructor functions work with any iterable Python object.
 .. c:function:: int PySet_Check(PyObject *p)
 
    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)
 
    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)
 
    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)
 
    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)
 
    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)

Doc/c-api/slice.rst

@@ -14,7 +14,8 @@ Slice Objects
 
 .. 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)

Doc/c-api/tuple.rst

@@ -21,14 +21,14 @@ Tuple Objects
 
 .. c:function:: int PyTuple_Check(PyObject *p)
 
-   Return true if *p* is a tuple object or an instance of a subtype of the tuple
-   type.
+   Return true if *p* is a tuple object or an instance of a subtype of the
+   tuple type.  This function always succeeds.
 
 
 .. c:function:: int PyTuple_CheckExact(PyObject *p)
 
    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)