Add PyUnstable_Object_IsUniquelyReferenced (#149)

Author: ngoldbaum

docs/api.rst

@@ -208,6 +208,9 @@ Python 3.14
 
    See `PyConfig_GetInt() documentation <https://docs.python.org/dev/c-api/init_config.html#c.PyConfig_GetInt>`__.
 
+.. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)
+
+   See `PyUnstable_Object_IsUniquelyReferenced() documentation <https://docs.python.org/dev/c-api/object.html#c.PyUnstable_Object_IsUniquelyReferenced>`__.
 
 Not supported:
 

docs/changelog.rst

@@ -1,6 +1,7 @@
 Changelog
 =========
 
+* 2025-09-01: Add ``PyUnstable_Object_IsUniquelyReferenced()`` function.
 * 2025-06-09: Add ``PyUnicodeWriter_WriteASCII()`` function.
 * 2025-06-03: Add functions:
 

pythoncapi_compat.h

@@ -2211,6 +2211,24 @@ PyConfig_GetInt(const char *name, int *value)
 }
 #endif  // PY_VERSION_HEX > 0x03090000 && !defined(PYPY_VERSION)
 
+// gh-133144 added PyUnstable_Object_IsUniquelyReferenced() to Python 3.14.0b1.
+// Adapted from  _PyObject_IsUniquelyReferenced() implementation.
+#if PY_VERSION_HEX < 0x030E00B0
+static inline int PyUnstable_Object_IsUniquelyReferenced(PyObject *obj)
+{
+#if !defined(Py_GIL_DISABLED)
+    return Py_REFCNT(obj) == 1;
+#else
+    // NOTE: the entire ob_ref_shared field must be zero, including flags, to
+    // ensure that other threads cannot concurrently create new references to
+    // this object.
+    return (_Py_IsOwnedByCurrentThread(obj) &&
+            _Py_atomic_load_uint32_relaxed(&obj->ob_ref_local) == 1 &&
+            _Py_atomic_load_ssize_relaxed(&obj->ob_ref_shared) == 0);
+#endif
+}
+#endif
+
 
 #if PY_VERSION_HEX < 0x030F0000
 static inline PyObject*

tests/test_pythoncapi_compat_cext.c

@@ -1972,6 +1972,25 @@ test_unicodewriter_format(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
 }
 #endif
 
+static PyObject *
+test_uniquely_referenced(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
+{
+    PyObject *obj = Py_BuildValue("(s, s)", "hello", "world");
+    if (obj == NULL) {
+        return NULL;
+    }
+
+    assert(PyUnstable_Object_IsUniquelyReferenced(obj));
+
+    Py_INCREF(obj);
+
+    assert(!PyUnstable_Object_IsUniquelyReferenced(obj));
+
+    Py_DECREF(obj);
+    Py_DECREF(obj);
+
+    Py_RETURN_NONE;
+}
 
 static PyObject *
 test_bytes(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
@@ -2328,6 +2347,7 @@ static struct PyMethodDef methods[] = {
     {"test_config", test_config, METH_NOARGS, _Py_NULL},
 #endif
     {"test_sys", test_sys, METH_NOARGS, _Py_NULL},
+    {"test_uniquely_referenced", test_uniquely_referenced, METH_NOARGS, _Py_NULL},
     {_Py_NULL, _Py_NULL, 0, _Py_NULL}
 };