[3.13] gh-141004: Document `PyType_SUPPORTS_WEAKREFS` (GH-141408) (GH-141487)

* gh-141004: Document `PyType_SUPPORTS_WEAKREFS` (GH-141408)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
(cherry picked from commit 9cd5427d9619b96db20d0347a136b3d331af71ae)

diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index ae478d8c1391dde32131a04ddc5ec9e103c1cbe9..84a5b0fc3c0c77ea055a5d5ddf748b09f33bae7d 100644 (file)
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -181,11 +181,13 @@ Type Objects
    Python's default memory allocation mechanism to allocate a new instance and
    initialize all its contents to ``NULL``.
 
+
 .. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
 
    Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object.  Create a
    new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot.
 
+
 .. c:function:: int PyType_Ready(PyTypeObject *type)
 
    Finalize a type object.  This should be called on all type objects to finish
@@ -202,6 +204,7 @@ Type Objects
        GC protocol itself by at least implementing the
        :c:member:`~PyTypeObject.tp_traverse` handle.
 
+
 .. c:function:: PyObject* PyType_GetName(PyTypeObject *type)
 
    Return the type's name. Equivalent to getting the type's
@@ -209,6 +212,7 @@ Type Objects
 
    .. versionadded:: 3.11
 
+
 .. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
 
    Return the type's qualified name. Equivalent to getting the
@@ -224,6 +228,7 @@ Type Objects
 
    .. versionadded:: 3.13
 
+
 .. c:function:: PyObject* PyType_GetModuleName(PyTypeObject *type)
 
    Return the type's module name. Equivalent to getting the
@@ -231,6 +236,7 @@ Type Objects
 
    .. versionadded:: 3.13
 
+
 .. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
 
    Return the function pointer stored in the given slot. If the
@@ -247,6 +253,7 @@ Type Objects
       :c:func:`PyType_GetSlot` can now accept all types.
       Previously, it was limited to :ref:`heap types <heap-types>`.
 
+
 .. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
 
    Return the module object associated with the given type when the type was
@@ -266,6 +273,7 @@ Type Objects
 
    .. versionadded:: 3.9
 
+
 .. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
 
    Return the state of the module object associated with the given type.
@@ -280,6 +288,7 @@ Type Objects
 
    .. versionadded:: 3.9
 
+
 .. c:function:: PyObject* PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
 
    Find the first superclass whose module was created from
@@ -299,6 +308,7 @@ Type Objects
 
    .. versionadded:: 3.11
 
+
 .. c:function:: int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
 
    Attempt to assign a version tag to the given type.
@@ -309,6 +319,16 @@ Type Objects
    .. versionadded:: 3.12
 
 
+.. c:function:: int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)
+
+   Return true if instances of *type* support creating weak references, false
+   otherwise. This function always succeeds. *type* must not be ``NULL``.
+
+   .. seealso::
+      * :ref:`weakrefobjects`
+      * :py:mod:`weakref`
+
+
 Creating Heap-Allocated Types
 .............................
 
@@ -361,6 +381,7 @@ The following functions and structs are used to create
 
    .. versionadded:: 3.12
 
+
 .. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
 
    Equivalent to ``PyType_FromMetaclass(NULL, module, spec, bases)``.
@@ -383,6 +404,7 @@ The following functions and structs are used to create
       :c:member:`~PyTypeObject.tp_new` is deprecated and in Python 3.14+ it
       will be no longer allowed.
 
+
 .. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
 
    Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, bases)``.
@@ -400,6 +422,7 @@ The following functions and structs are used to create
       :c:member:`~PyTypeObject.tp_new` is deprecated and in Python 3.14+ it
       will be no longer allowed.
 
+
 .. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
 
    Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``.

diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst
index 6a35304e48f04e4f17e59dd6370993c4fd507fc2..c769e0810136d7f4c509e839c6e8f12d1ce6fd3d 100644 (file)
--- a/Doc/c-api/weakref.rst
+++ b/Doc/c-api/weakref.rst
@@ -45,6 +45,10 @@ as much as it can.
    weakly referenceable object, or if *callback* is not callable, ``None``, or
    ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
+   .. seealso::
+      :c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly
+      referenceable.
+
 
 .. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
 
@@ -57,6 +61,10 @@ as much as it can.
    is not a weakly referenceable object, or if *callback* is not callable,
    ``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
+   .. seealso::
+      :c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly
+      referenceable.
+
 
 .. c:function:: int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)