gh-148498: Promote PyUnstable_Object_GC_NewWithExtraData() to the stable API

Rename ``PyUnstable_Object_GC_NewWithExtraData`` to
``PyObject_GC_NewWithExtraData`` and add it to the limited API.

Author: wjakob

Doc/c-api/gcsupport.rst

@@ -100,7 +100,7 @@ rules:
       * :c:member:`~PyTypeObject.tp_alloc`
 
 
-.. c:function:: PyObject* PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
+.. c:function:: PyObject* PyObject_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
 
    Analogous to :c:macro:`PyObject_GC_New` but allocates *extra_size*
    bytes at the end of the object (at offset
@@ -115,15 +115,18 @@ rules:
    :c:func:`PyObject_GC_Del` (usually called via the object's
    :c:member:`~PyTypeObject.tp_free` slot).
 
-   .. warning::
-      The function is marked as unstable because the final mechanism
-      for reserving extra data after an instance is not yet decided.
-      For allocating a variable number of fields, prefer using
-      :c:type:`PyVarObject` and :c:member:`~PyTypeObject.tp_itemsize`
-      instead.
+   For allocating a variable number of fields, prefer using
+   :c:type:`PyVarObject` and :c:member:`~PyTypeObject.tp_itemsize`
+   instead.
 
    .. versionadded:: 3.12
 
+   .. versionchanged:: 3.15
+      The function is now part of the :ref:`limited API <limited-c-api>`.
+
+      Previously, the function was named
+      ``PyUnstable_Object_GC_NewWithExtraData``.
+
 
 .. c:macro:: PyObject_GC_Resize(TYPE, op, newsize)
 

Doc/c-api/typeobj.rst

@@ -599,7 +599,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    :c:member:`!tp_itemsize` field.  For a type with fixed-length instances, all
    instances have the same size, given in :c:member:`!tp_basicsize`.
    (Exceptions to this rule can be made using
-   :c:func:`PyUnstable_Object_GC_NewWithExtraData`.)
+   :c:func:`PyObject_GC_NewWithExtraData`.)
 
    For a type with variable-length instances, the instances must have an
    :c:member:`~PyVarObject.ob_size` field, and the instance size is

Doc/data/stable_abi.dat

@@ -83,8 +83,7 @@ PyAPI_FUNC(int) PyType_SUPPORTS_WEAKREFS(PyTypeObject *type);
 
 PyAPI_FUNC(PyObject **) PyObject_GET_WEAKREFS_LISTPTR(PyObject *op);
 
-PyAPI_FUNC(PyObject *) PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *,
-                                                             size_t);
+
 
 
 /* Visit all live GC-capable objects, similar to gc.get_objects(None). The

Include/cpython/objimpl.h

@@ -182,6 +182,8 @@ PyAPI_FUNC(void) PyObject_GC_Del(void *);
 #define PyObject_GC_NewVar(type, typeobj, n) \
     _Py_CAST(type*, _PyObject_GC_NewVar((typeobj), (n)))
 
+PyAPI_FUNC(PyObject *) PyObject_GC_NewWithExtraData(PyTypeObject *, size_t);
+
 PyAPI_FUNC(int) PyObject_GC_IsTracked(PyObject *);
 PyAPI_FUNC(int) PyObject_GC_IsFinalized(PyObject *);
 

Include/objimpl.h

@@ -0,0 +1,3 @@
+Rename :c:func:`!PyUnstable_Object_GC_NewWithExtraData` to
+:c:func:`PyObject_GC_NewWithExtraData` and add it to the
+:ref:`limited API <limited-c-api>`.

Lib/test/test_stable_abi_ctypes.py

@@ -2706,3 +2706,5 @@
     # Note: The `_reserved` member of this struct is for interal use only.
     # (The definition of 'full-abi' was clarified when this entry was added.)
     struct_abi_kind = 'full-abi'
+[function.PyObject_GC_NewWithExtraData]
+    added = '3.15'

Misc/NEWS.d/next/C_API/2026-04-13-00-00-00.gh-issue-148498.GCNewExtra.rst

@@ -228,7 +228,7 @@ static PyObject *
 obj_extra_data_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 {
     size_t extra_size = sizeof(PyObject *);
-    PyObject *obj = PyUnstable_Object_GC_NewWithExtraData(type, extra_size);
+    PyObject *obj = PyObject_GC_NewWithExtraData(type, extra_size);
     if (obj == NULL) {
         return PyErr_NoMemory();
     }