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.

26 files changed, 74 insertions, 52 deletions

diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst
index ce8de6e..c197d44 100644
--- a/Doc/c-api/bool.rst
+++ b/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
diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst
index b2f409c..30bcfc7 100644
--- a/Doc/c-api/bytearray.rst
+++ b/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
diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index 0e33ed2..de65701 100644
--- a/Doc/c-api/bytes.rst
+++ b/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)
diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
index 5eb313c..908e926 100644
--- a/Doc/c-api/capsule.rst
+++ b/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)
diff --git a/Doc/c-api/cell.rst b/Doc/c-api/cell.rst
index 8408f7e..ac4ef5a 100644
--- a/Doc/c-api/cell.rst
+++ b/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)
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 6f8c41c..b3a17f1 100644
--- a/Doc/c-api/code.rst
+++ b/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)
 
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index 06dbb25..e2ea766 100644
--- a/Doc/c-api/complex.rst
+++ b/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)
diff --git a/Doc/c-api/coro.rst b/Doc/c-api/coro.rst
index 2260944..caa855a 100644
--- a/Doc/c-api/coro.rst
+++ b/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)
diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst
index 415ce4c..4c4e4bc 100644
--- a/Doc/c-api/datetime.rst
+++ b/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:
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index 8e0d684..d257c9b 100644
--- a/Doc/c-api/dict.rst
+++ b/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()
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index b29937d..c107243 100644
--- a/Doc/c-api/float.rst
+++ b/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)
diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst
index bb416f4..2096882 100644
--- a/Doc/c-api/function.rst
+++ b/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)
diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst
index 7441092..0eb5922 100644
--- a/Doc/c-api/gen.rst
+++ b/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)
diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst
index 68df6f6..74fb557 100644
--- a/Doc/c-api/iter.rst
+++ b/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)
diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst
index 4d91e4a..3fcf099 100644
--- a/Doc/c-api/iterator.rst
+++ b/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)
diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst
index 0bc0785..f338e2a 100644
--- a/Doc/c-api/list.rst
+++ b/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)
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 4d859fb..4201490 100644
--- a/Doc/c-api/long.rst
+++ b/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)
diff --git a/Doc/c-api/memoryview.rst b/Doc/c-api/memoryview.rst
index de429e5..24f8c93 100644
--- a/Doc/c-api/memoryview.rst
+++ b/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)
diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst
index 0a5341c..2385225 100644
--- a/Doc/c-api/method.rst
+++ b/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)
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 41a705d..a2541af 100644
--- a/Doc/c-api/module.rst
+++ b/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)
diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
index 879f394..84f34e7 100644
--- a/Doc/c-api/set.rst
+++ b/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)
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index 48a58c6..8271d9a 100644
--- a/Doc/c-api/slice.rst
+++ b/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)
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index c0c14f4..6919e61 100644
--- a/Doc/c-api/tuple.rst
+++ b/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)
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index a869859..b9bfa55 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -23,12 +23,14 @@ Type Objects
 
    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.
+   This function always succeeds.
 
 
 .. c:function:: int PyType_CheckExact(PyObject *o)
 
-   Return non-zero if the object *o* is a type object, but not a subtype of the
-   standard type object.  Return 0 in all other cases.
+   Return non-zero if the object *o* is a type object, but not a subtype of
+   the standard type object.  Return 0 in all other cases.  This function
+   always succeeds.
 
 
 .. c:function:: unsigned int PyType_ClearCache()
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index b7f99d3..1851c64 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -91,13 +91,13 @@ access internal read-only data of Unicode objects:
 .. c:function:: int PyUnicode_Check(PyObject *o)
 
    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)
 
    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)
diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst
index 9205ca6..98ebe71 100644
--- a/Doc/c-api/weakref.rst
+++ b/Doc/c-api/weakref.rst
@@ -13,17 +13,18 @@ as much as it can.
 
 .. 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)
 
-   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)
 
-   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)