[3.13] gh-141004: Document `PyType_FastSubclass` (GH-141313) (GH-141369)

gh-141004: Document `PyType_FastSubclass` (GH-141313)
(cherry picked from commit ed0a5fd8cacb1964111d03ff37627f6bea5e6026)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 1b69d6d22326f83624ac0ee77984e61e1a5a8195..aa7f2bca98a2f19b152dbba946630a89327bfd98 100644 (file)
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -133,6 +133,18 @@ Type Objects
    Type features are denoted by single bit flags.
 
 
+.. c:function:: int PyType_FastSubclass(PyTypeObject *type, int flag)
+
+   Return non-zero if the type object *type* sets the subclass flag *flag*.
+   Subclass flags are denoted by
+   :c:macro:`Py_TPFLAGS_*_SUBCLASS <Py_TPFLAGS_LONG_SUBCLASS>`.
+   This function is used by many ``_Check`` functions for common types.
+
+   .. seealso::
+       :c:func:`PyObject_TypeCheck`, which is used as a slower alternative in
+       ``_Check`` functions for types that don't come with subclass flags.
+
+
 .. c:function:: int PyType_IS_GC(PyTypeObject *o)
 
    Return true if the type object includes support for the cycle detector; this

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index a692a65218bd21657fa1b6310ed46bf72893d9ae..a191d07e48135a3b24089bb35d38e51b84563035 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1248,8 +1248,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    .. c:macro:: Py_TPFLAGS_BASE_EXC_SUBCLASS
    .. c:macro:: Py_TPFLAGS_TYPE_SUBCLASS
 
-      These flags are used by functions such as
-      :c:func:`PyLong_Check` to quickly determine if a type is a subclass
+      Functions such as :c:func:`PyLong_Check` will call :c:func:`PyType_FastSubclass`
+      with one of these flags to quickly determine if a type is a subclass
       of a built-in type; such specific checks are faster than a generic
       check, like :c:func:`PyObject_IsInstance`. Custom types that inherit
       from built-ins should have their :c:member:`~PyTypeObject.tp_flags`