gh-105927: Add PyWeakref_GetRef() function

* Add tests on PyWeakref_NewRef(), PyWeakref_GetObject(),
  PyWeakref_GET_OBJECT() and PyWeakref_GetRef().
* PyWeakref_GetObject() now raises a TypeError if the argument is not
  a weak reference, instead of SystemError.

Author: vstinner

Doc/c-api/weakref.rst

@@ -51,6 +51,16 @@ 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 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

Doc/data/refcounts.dat

@@ -2810,6 +2810,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

@@ -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
 ----------------------

Doc/whatsnew/3.13.rst

@@ -28,6 +28,7 @@ PyAPI_FUNC(PyObject *) PyWeakref_NewRef(PyObject *ob,
 PyAPI_FUNC(PyObject *) PyWeakref_NewProxy(PyObject *ob,
                                           PyObject *callback);
 PyAPI_FUNC(PyObject *) PyWeakref_GetObject(PyObject *ref);
+PyAPI_FUNC(int) PyWeakref_GetRef(PyObject *ref, PyObject **pobj);
 
 
 #ifndef Py_LIMITED_API

Include/weakrefobject.h

@@ -967,6 +967,10 @@ def __del__(self): pass
         del x
         support.gc_collect()
 
+    @support.cpython_only
+    def test_capi(self):
+        import _testcapi
+        _testcapi.check_weakref_capi(C)
 
 class SubclassableWeakrefTestCase(TestBase):
 

Lib/test/test_stable_abi_ctypes.py

@@ -0,0 +1,3 @@
+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. Patch by Victor Stinner.

Lib/test/test_weakref.py

@@ -2430,3 +2430,5 @@
     added = '3.12'
 [function.PyImport_AddModuleRef]
     added = '3.13'
+[function.PyWeakref_GetRef]
+    added = '3.13'

Misc/NEWS.d/next/C API/2023-06-20-08-59-05.gh-issue-105927.DfGeEA.rst

@@ -3372,6 +3372,73 @@ check_pyimport_addmodule(PyObject *self, PyObject *args)
 }
 
 
+static PyObject *
+check_weakref_capi(PyObject *self, PyObject *factory)
+{
+    // obj = factory()
+    PyObject *obj = PyObject_CallNoArgs(factory);
+    if (obj == NULL) {
+        return NULL;
+    }
+    Py_ssize_t refcnt = Py_REFCNT(obj);
+    assert(refcnt == 1);
+
+    // test PyWeakref_GetRef()
+    PyObject *weakref = PyWeakref_NewRef(obj, NULL);
+    if (weakref == NULL) {
+        Py_DECREF(obj);
+        return NULL;
+    }
+    assert(PyWeakref_Check(weakref));
+    assert(PyWeakref_CheckRefExact(weakref));
+    assert(PyWeakref_CheckRefExact(weakref));
+    assert(Py_REFCNT(obj) == refcnt);
+
+    // test PyWeakref_GetRef()
+    PyObject *ref1;
+    assert(PyWeakref_GetRef(weakref, &ref1) == 0);
+    assert(ref1 == obj);
+    assert(Py_REFCNT(obj) == (refcnt + 1));
+    Py_DECREF(ref1);
+
+    // test PyWeakref_GetObject()
+    PyObject *ref2 = PyWeakref_GetObject(weakref);
+    assert(ref2 == obj);
+    assert(Py_REFCNT(obj) == refcnt);
+
+    // test PyWeakref_GET_OBJECT()
+    PyObject *ref3 = PyWeakref_GET_OBJECT(weakref);
+    assert(ref3 == obj);
+    assert(Py_REFCNT(obj) == refcnt);
+
+    // delete the object
+    assert(refcnt == 1);
+    Py_DECREF(obj);
+    assert(PyWeakref_GET_OBJECT(weakref) == Py_None);
+    PyObject *ref4;
+    assert(PyWeakref_GetRef(weakref, &ref4) == 0);
+    assert(ref4 == NULL);
+
+    // None is not a weak reference object
+    PyObject *invalid_weakref = Py_None;
+    assert(!PyWeakref_Check(invalid_weakref));
+    assert(!PyWeakref_CheckRefExact(invalid_weakref));
+    assert(!PyWeakref_CheckRefExact(invalid_weakref));
+
+    assert(!PyErr_Occurred());
+    PyObject *ref5 = factory;  // marker to check that value was set
+    assert(PyWeakref_GetRef(invalid_weakref, &ref5) == -1);
+    assert(PyErr_ExceptionMatches(PyExc_TypeError));
+    PyErr_Clear();
+
+    assert(PyWeakref_GetObject(invalid_weakref) == NULL);
+    assert(PyErr_ExceptionMatches(PyExc_TypeError));
+    PyErr_Clear();
+
+    Py_RETURN_NONE;
+}
+
+
 static PyMethodDef TestMethods[] = {
     {"set_errno",               set_errno,                       METH_VARARGS},
     {"test_config",             test_config,                     METH_NOARGS},
@@ -3516,6 +3583,7 @@ static PyMethodDef TestMethods[] = {
     {"function_set_kw_defaults", function_set_kw_defaults, METH_VARARGS, NULL},
     {"test_atexit", test_atexit, METH_NOARGS},
     {"check_pyimport_addmodule", check_pyimport_addmodule, METH_VARARGS},
+    {"check_weakref_capi", check_weakref_capi, METH_O},
     {NULL, NULL} /* sentinel */
 };
 

Misc/stable_abi.toml

@@ -894,13 +894,35 @@ PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
 }
 
 
+int
+PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
+{
+    if (ref == NULL) {
+        *pobj = NULL;
+        PyErr_BadInternalCall();
+        return -1;
+    }
+    if (!PyWeakref_Check(ref)) {
+        *pobj = NULL;
+        PyErr_SetString(PyExc_TypeError, "expected a weakref");
+        return -1;
+    }
+    *pobj = _PyWeakref_GET_REF(ref);
+    return 0;
+}
+
+
 PyObject *
 PyWeakref_GetObject(PyObject *ref)
 {
-    if (ref == NULL || !PyWeakref_Check(ref)) {
+    if (ref == NULL) {
         PyErr_BadInternalCall();
         return NULL;
     }
+    if (!PyWeakref_Check(ref)) {
+        PyErr_SetString(PyExc_TypeError, "expected a weakref");
+        return NULL;
+    }
     return PyWeakref_GET_OBJECT(ref);
 }