pythongh-114329: Add PyList_GetItemRef function

The new `PyList_GetItemRef` is similar to `PyList_GetItem`, but returns
a strong reference instead of a borrowed reference. Additionally, if the
passed "list" object is not a list, the function sets a `TypeError`
instead of calling `PyErr_BadInternalCall()`.

Author: colesbury

Doc/c-api/list.rst

@@ -64,6 +64,21 @@ List Objects
    return ``NULL`` and set an :exc:`IndexError` exception.
 
 
+.. c:function:: PyObject* PyList_GetItemRef(PyObject *list, Py_ssize_t index)
+
+   Return a :term:`strong reference` to the object at position *index* in the
+   list pointed to by *list*.  The position must be non-negative; indexing from
+   the end of the list is not supported.  If *index* is out of bounds
+   (<0 or >=len(list)), return ``NULL`` and set an :exc:`IndexError` exception.
+   If *list* is not a :class:`list` object, return ``NULL`` and set a
+   :exc:`TypeError` exception.
+
+   This behaves like :c:func:`PyList_GetItem`, but returns a
+   :term:`strong reference` instead of a :term:`borrowed reference`.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
 
    Similar to :c:func:`PyList_GetItem`, but without error checking.

Doc/data/stable_abi.dat

@@ -1305,6 +1305,10 @@ New Features
   UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`.
   (Contributed by Victor Stinner in :gh:`108314`.)
 
+* Added :c:func:`PyList_GetItemRef` function: similar to
+  :c:func:`PyList_GetItem` but returns a :term:`strong reference` instead of
+  a :term:`borrowed reference`.
+
 * Add :c:func:`Py_IsFinalizing` function: check if the main Python interpreter is
   :term:`shutting down <interpreter shutdown>`.
   (Contributed by Victor Stinner in :gh:`108014`.)

Doc/whatsnew/3.13.rst

@@ -29,6 +29,7 @@ PyAPI_FUNC(PyObject *) PyList_New(Py_ssize_t size);
 PyAPI_FUNC(Py_ssize_t) PyList_Size(PyObject *);
 
 PyAPI_FUNC(PyObject *) PyList_GetItem(PyObject *, Py_ssize_t);
+PyAPI_FUNC(PyObject *) PyList_GetItemRef(PyObject *, Py_ssize_t);
 PyAPI_FUNC(int) PyList_SetItem(PyObject *, Py_ssize_t, PyObject *);
 PyAPI_FUNC(int) PyList_Insert(PyObject *, Py_ssize_t, PyObject *);
 PyAPI_FUNC(int) PyList_Append(PyObject *, PyObject *);

Include/listobject.h

@@ -112,6 +112,15 @@ def test_list_get_item(self):
         # CRASHES get_item(21, 2)
         # CRASHES get_item(NULL, 1)
 
+    def test_list_get_item_ref(self):
+        # Test PyList_GetItemRef()
+        get_item_ref = _testcapi.list_get_item_ref
+        lst = [1, 2, [1, 2, 3]]
+        self.assertEqual(get_item_ref(lst, 0), 1)
+        self.assertEqual(get_item_ref(lst, 2), [1, 2, 3])
+        self.assertRaises(IndexError, get_item_ref, lst, 3)
+        self.assertRaises(IndexError, get_item_ref, lst, -1)
+        self.assertRaises(TypeError, get_item_ref, "not a list", 0)
 
     def test_list_setitem(self):
         # Test PyList_SetItem()

Lib/test/test_capi/test_list.py

@@ -0,0 +1,3 @@
+Add :c:func:`PyList_GetItemRef`, which is similar to
+:c:func:`PyList_GetItem` but returns a :term:`strong reference` instead of a
+:term:`borrowed reference`.

Misc/NEWS.d/next/C API/2024-01-23-21-45-02.gh-issue-114329.YRaBoe.rst

@@ -905,6 +905,8 @@
     added = '3.2'
 [function.PyList_GetItem]
     added = '3.2'
+[function.PyList_GetItemRef]
+    added = '3.13'
 [function.PyList_GetSlice]
     added = '3.2'
 [function.PyList_Insert]

Misc/stable_abi.toml

@@ -59,6 +59,18 @@ list_get_item(PyObject *Py_UNUSED(module), PyObject *args)
     return Py_XNewRef(PyList_GET_ITEM(obj, i));
 }
 
+static PyObject *
+list_get_item_ref(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    PyObject *obj;
+    Py_ssize_t i;
+    if (!PyArg_ParseTuple(args, "On", &obj, &i)) {
+        return NULL;
+    }
+    NULLABLE(obj);
+    return PyList_GetItemRef(obj, i);
+}
+
 static PyObject *
 list_setitem(PyObject *Py_UNUSED(module), PyObject *args)
 {
@@ -191,6 +203,7 @@ static PyMethodDef test_methods[] = {
     {"list_get_size", list_get_size, METH_O},
     {"list_getitem", list_getitem, METH_VARARGS},
     {"list_get_item", list_get_item, METH_VARARGS},
+    {"list_get_item_ref", list_get_item_ref, METH_VARARGS},
     {"list_setitem", list_setitem, METH_VARARGS},
     {"list_set_item", list_set_item, METH_VARARGS},
     {"list_insert", list_insert, METH_VARARGS},

Modules/_testcapi/list.c

@@ -253,6 +253,21 @@ PyList_GetItem(PyObject *op, Py_ssize_t i)
     return ((PyListObject *)op) -> ob_item[i];
 }
 
+PyObject *
+PyList_GetItemRef(PyObject *op, Py_ssize_t i)
+{
+    if (!PyList_Check(op)) {
+        PyErr_SetString(PyExc_TypeError, "expected a list");
+        return NULL;
+    }
+    if (!valid_index(i, Py_SIZE(op))) {
+        _Py_DECLARE_STR(list_err, "list index out of range");
+        PyErr_SetObject(PyExc_IndexError, &_Py_STR(list_err));
+        return NULL;
+    }
+    return Py_NewRef(PyList_GET_ITEM(op, i));
+}
+
 int
 PyList_SetItem(PyObject *op, Py_ssize_t i,
                PyObject *newitem)