gh-105927: Add PyWeakref_GetRef() function (#105932)

Add tests on PyWeakref_NewRef(), PyWeakref_GetObject(),
PyWeakref_GET_OBJECT() and PyWeakref_GetRef().

Doc/c-api/weakref.rst

@@ -11,20 +11,20 @@ simple reference object, and the second acts as a proxy for the original object
 as much as it can.
 
 
-.. c:function:: int PyWeakref_Check(ob)
+.. c:function:: int PyWeakref_Check(PyObject *ob)
 
-   Return true if *ob* is either a reference or proxy object.  This function
+   Return non-zero if *ob* is either a reference or proxy object.  This function
    always succeeds.
 
 
-.. c:function:: int PyWeakref_CheckRef(ob)
+.. c:function:: int PyWeakref_CheckRef(PyObject *ob)
 
-   Return true if *ob* is a reference object.  This function always succeeds.
+   Return non-zero if *ob* is a reference object.  This function always succeeds.
 
 
-.. c:function:: int PyWeakref_CheckProxy(ob)
+.. c:function:: int PyWeakref_CheckProxy(PyObject *ob)
 
-   Return true if *ob* is a proxy object.  This function always succeeds.
+   Return non-zero if *ob* is a proxy object.  This function always succeeds.
 
 
 .. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
@@ -51,10 +51,21 @@ as much as it can.
    ``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
 
+.. c:function:: int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
+
+   Get a :term:`strong reference` to the referenced object from a weak
+   reference, *ref*, into *\*pobj*.
+   Return 0 on success. Raise an exception and return -1 on error.
+
+   If the referent is no longer live, set *\*pobj* to ``NULL`` and return 0.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)
 
-   Return the referenced object from a weak reference, *ref*.  If the referent is
-   no longer live, returns :const:`Py_None`.
+   Return a :term:`borrowed reference` to the referenced object from a weak
+   reference, *ref*.  If the referent is no longer live, returns ``Py_None``.
 
    .. note::
 

Doc/data/refcounts.dat

@@ -2813,6 +2813,10 @@ PyWeakref_GET_OBJECT:PyObject*:ref:0:
 PyWeakref_GetObject:PyObject*::0:
 PyWeakref_GetObject:PyObject*:ref:0:
 
+PyWeakref_GetRef:int:::
+PyWeakref_GetRef:PyObject*:ref:0:
+PyWeakref_GetRef:PyObject**:pobj:+1:
+
 PyWeakref_NewProxy:PyObject*::+1:
 PyWeakref_NewProxy:PyObject*:ob:0:
 PyWeakref_NewProxy:PyObject*:callback:0:

Doc/data/stable_abi.dat

@@ -781,6 +781,7 @@ function,PyVectorcall_Call,3.12,,
 function,PyVectorcall_NARGS,3.12,,
 type,PyWeakReference,3.2,,opaque
 function,PyWeakref_GetObject,3.2,,
+function,PyWeakref_GetRef,3.13,,
 function,PyWeakref_NewProxy,3.2,,
 function,PyWeakref_NewRef,3.2,,
 var,PyWrapperDescr_Type,3.2,,

Doc/whatsnew/3.13.rst

@@ -431,6 +431,10 @@ New Features
   of a :term:`borrowed reference`.
   (Contributed by Victor Stinner in :gh:`105922`.)
 
+* Add :c:func:`PyWeakref_GetRef` function: similar to
+  :c:func:`PyWeakref_GetObject` but returns a :term:`strong reference`, or
+  ``NULL`` if the referent is no longer live.
+  (Contributed by Victor Stinner in :gh:`105927`.)
 
 Porting to Python 3.13
 ----------------------