gh-117518: Add PyTuple_GetItemRef() function

Replace Py_NewRef(PyTuple_GET_ITEM(tuple, pos)) with
PyTuple_GetItemRef(tuple, pos).

Author: vstinner

Doc/c-api/tuple.rst

@@ -54,10 +54,21 @@ Tuple Objects
    no error checking is performed.
 
 
+.. c:function:: PyObject* PyTuple_GetItemRef(PyObject *p, Py_ssize_t pos)
+
+   Return a :term:`strong reference` to the object at position *pos* in the
+   tuple pointed to by *p*.
+
+   If *pos* is negative or out of bounds, return ``NULL`` and set an
+   :exc:`IndexError` exception.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
 
-   Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
-   negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
+   Similar to :c:func:`PyTuple_GetItemRef`, but return a :term:`borrowed
+   reference`.
 
 
 .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

Doc/data/stable_abi.dat

@@ -1773,6 +1773,11 @@ New Features
 * Add :c:func:`PyType_GetModuleByDef` to the limited C API
   (Contributed by Victor Stinner in :gh:`116936`.)
 
+* Add :c:func:`PyTuple_GetItemRef` function, similar to
+  :c:func:`PyTuple_GetItem` but return a :term:`strong reference` instead of a
+  :term:`borrowed reference`.
+  (Contributed by Victor Stinner in :gh:`117518`.)
+
 
 Porting to Python 3.13
 ----------------------

Doc/whatsnew/3.13.rst

@@ -30,6 +30,9 @@ PyAPI_DATA(PyTypeObject) PyTupleIter_Type;
 PyAPI_FUNC(PyObject *) PyTuple_New(Py_ssize_t size);
 PyAPI_FUNC(Py_ssize_t) PyTuple_Size(PyObject *);
 PyAPI_FUNC(PyObject *) PyTuple_GetItem(PyObject *, Py_ssize_t);
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
+PyAPI_FUNC(PyObject *) PyTuple_GetItemRef(PyObject *, Py_ssize_t);
+#endif
 PyAPI_FUNC(int) PyTuple_SetItem(PyObject *, Py_ssize_t, PyObject *);
 PyAPI_FUNC(PyObject *) PyTuple_GetSlice(PyObject *, Py_ssize_t, Py_ssize_t);
 PyAPI_FUNC(PyObject *) PyTuple_Pack(Py_ssize_t, ...);

Include/internal/pycore_opcode_metadata.h

@@ -0,0 +1,3 @@
+Add :c:func:`PyTuple_GetItemRef` function, similar to
+:c:func:`PyTuple_GetItem` but return a :term:`strong reference` instead of a
+:term:`borrowed reference`. Patch by Victor Stinner.

Include/internal/pycore_uop_metadata.h

@@ -2506,3 +2506,5 @@
     added = '3.13'
 [function.PyType_GetModuleByDef]
     added = '3.13'
+[function.PyTuple_GetItemRef]
+    added = '3.13'

Include/tupleobject.h

@@ -213,7 +213,7 @@ divide_nearest(PyObject *m, PyObject *n)
     temp = _PyLong_DivmodNear(m, n);
     if (temp == NULL)
         return NULL;
-    result = Py_NewRef(PyTuple_GET_ITEM(temp, 0));
+    result = PyTuple_GetItemRef(temp, 0);
     Py_DECREF(temp);
 
     return result;
@@ -1978,7 +1978,7 @@ microseconds_to_delta_ex(PyObject *pyus, PyTypeObject *type)
         goto BadDivmod;
     }
 
-    num = Py_NewRef(PyTuple_GET_ITEM(tuple, 0));        /* leftover seconds */
+    num = PyTuple_GetItemRef(tuple, 0);         /* leftover seconds */
     Py_DECREF(tuple);
 
     tuple = checked_divmod(num, st->seconds_per_day);
@@ -1996,7 +1996,7 @@ microseconds_to_delta_ex(PyObject *pyus, PyTypeObject *type)
         goto BadDivmod;
     }
 
-    num = Py_NewRef(PyTuple_GET_ITEM(tuple, 0));           /* leftover days */
+    num = PyTuple_GetItemRef(tuple, 0);         /* leftover days */
     d = PyLong_AsInt(num);
     if (d == -1 && PyErr_Occurred()) {
         goto Done;

Lib/test/test_stable_abi_ctypes.py

@@ -164,7 +164,7 @@ test_from_spec_invalid_metatype_inheritance(PyObject *self, PyObject *Py_UNUSED(
                     "TypeError args are not a one-tuple");
             goto finally;
         }
-        message = Py_NewRef(PyTuple_GET_ITEM(args, 0));
+        message = PyTuple_GetItemRef(args, 0);
         meta_error_string = PyUnicode_FromString("metaclass conflict:");
         if (meta_error_string == NULL) {
             goto finally;
@@ -1028,7 +1028,7 @@ HeapCCollection_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
     }
 
     for (Py_ssize_t i = 0; i < size; i++) {
-        data[i] = Py_NewRef(PyTuple_GET_ITEM(args, i));
+        data[i] = PyTuple_GetItemRef(args, i);
     }
 
     result = self;

Misc/NEWS.d/next/C API/2024-04-03-21-37-08.gh-issue-117518.F17sQ6.rst

@@ -641,7 +641,7 @@ SystemExit_init(PySystemExitObject *self, PyObject *args, PyObject *kwds)
     if (size == 0)
         return 0;
     if (size == 1) {
-        Py_XSETREF(self->code, Py_NewRef(PyTuple_GET_ITEM(args, 0)));
+        Py_XSETREF(self->code, PyTuple_GetItemRef(args, 0));
     }
     else { /* size > 1 */
         Py_XSETREF(self->code, Py_NewRef(args));
@@ -1546,7 +1546,7 @@ ImportError_init(PyImportErrorObject *self, PyObject *args, PyObject *kwds)
     Py_XSETREF(self->name_from, Py_XNewRef(name_from));
 
     if (PyTuple_GET_SIZE(args) == 1) {
-        msg = Py_NewRef(PyTuple_GET_ITEM(args, 0));
+        msg = PyTuple_GetItemRef(args, 0);
     }
     Py_XSETREF(self->msg, msg);
 
@@ -2034,8 +2034,8 @@ OSError_reduce(PyOSErrorObject *self, PyObject *Py_UNUSED(ignored))
         if (!args)
             return NULL;
 
-        PyTuple_SET_ITEM(args, 0, Py_NewRef(PyTuple_GET_ITEM(self->args, 0)));
-        PyTuple_SET_ITEM(args, 1, Py_NewRef(PyTuple_GET_ITEM(self->args, 1)));
+        PyTuple_SET_ITEM(args, 0, PyTuple_GetItemRef(self->args, 0));
+        PyTuple_SET_ITEM(args, 1, PyTuple_GetItemRef(self->args, 1));
         PyTuple_SET_ITEM(args, 2, Py_NewRef(self->filename));
 
         if (self->filename2) {
@@ -2389,7 +2389,7 @@ SyntaxError_init(PySyntaxErrorObject *self, PyObject *args, PyObject *kwds)
         return -1;
 
     if (lenargs >= 1) {
-        Py_XSETREF(self->msg, Py_NewRef(PyTuple_GET_ITEM(args, 0)));
+        Py_XSETREF(self->msg, PyTuple_GetItemRef(args, 0));
     }
     if (lenargs == 2) {
         info = PyTuple_GET_ITEM(args, 1);

Misc/stable_abi.toml

@@ -2121,7 +2121,7 @@ struct_unpack_single(const char *ptr, struct unpacker *x)
         return NULL;
 
     if (PyTuple_GET_SIZE(v) == 1) {
-        PyObject *res = Py_NewRef(PyTuple_GET_ITEM(v, 0));
+        PyObject *res = PyTuple_GetItemRef(v, 0);
         Py_DECREF(v);
         return res;
     }

Modules/_datetimemodule.c

@@ -109,6 +109,15 @@ PyTuple_GetItem(PyObject *op, Py_ssize_t i)
     return ((PyTupleObject *)op) -> ob_item[i];
 }
 
+
+PyObject *
+PyTuple_GetItemRef(PyObject *op, Py_ssize_t index)
+{
+    PyObject *item = PyTuple_GetItem(op, index);
+    return Py_XNewRef(item);
+}
+
+
 int
 PyTuple_SetItem(PyObject *op, Py_ssize_t i, PyObject *newitem)
 {

Modules/_testcapi/heaptype.c

@@ -6453,8 +6453,8 @@ _PyObject_GetNewArguments(PyObject *obj, PyObject **args, PyObject **kwargs)
             Py_DECREF(newargs);
             return -1;
         }
-        *args = Py_NewRef(PyTuple_GET_ITEM(newargs, 0));
-        *kwargs = Py_NewRef(PyTuple_GET_ITEM(newargs, 1));
+        *args = PyTuple_GetItemRef(newargs, 0);
+        *kwargs = PyTuple_GetItemRef(newargs, 1);
         Py_DECREF(newargs);
 
         /* XXX We should perhaps allow None to be passed here. */

Objects/exceptions.c

@@ -293,7 +293,7 @@ union_getitem(PyObject *self, PyObject *item)
         res = make_union(newargs);
     }
     else {
-        res = Py_NewRef(PyTuple_GET_ITEM(newargs, 0));
+        res = PyTuple_GetItemRef(newargs, 0);
         for (Py_ssize_t iarg = 1; iarg < nargs; iarg++) {
             PyObject *arg = PyTuple_GET_ITEM(newargs, iarg);
             Py_SETREF(res, PyNumber_Or(res, arg));

Objects/memoryobject.c

@@ -1237,8 +1237,8 @@ dummy_func(
             DEOPT_IF(!PyTuple_CheckExact(seq));
             DEOPT_IF(PyTuple_GET_SIZE(seq) != 2);
             STAT_INC(UNPACK_SEQUENCE, hit);
-            val0 = Py_NewRef(PyTuple_GET_ITEM(seq, 0));
-            val1 = Py_NewRef(PyTuple_GET_ITEM(seq, 1));
+            val0 = PyTuple_GetItemRef(seq, 0);
+            val1 = PyTuple_GetItemRef(seq, 1);
             DECREF_INPUTS();
         }
 
@@ -2702,7 +2702,7 @@ dummy_func(
             PyTupleObject *seq = it->it_seq;
             assert(seq);
             assert(it->it_index < PyTuple_GET_SIZE(seq));
-            next = Py_NewRef(PyTuple_GET_ITEM(seq, it->it_index++));
+            next = PyTuple_GetItemRef((PyObject*)seq, it->it_index++);
         }
 
         macro(FOR_ITER_TUPLE) =

Objects/tupleobject.c

@@ -2031,8 +2031,8 @@ _PyEval_ExceptionGroupMatch(PyObject* exc_value, PyObject *match_type,
         }
         assert(PyTuple_CheckExact(pair));
         assert(PyTuple_GET_SIZE(pair) == 2);
-        *match = Py_NewRef(PyTuple_GET_ITEM(pair, 0));
-        *rest = Py_NewRef(PyTuple_GET_ITEM(pair, 1));
+        *match = PyTuple_GetItemRef(pair, 0);
+        *rest = PyTuple_GetItemRef(pair, 1);
         Py_DECREF(pair);
         return 0;
     }

Objects/typeobject.c

@@ -411,7 +411,7 @@ _PyCodec_EncodeInternal(PyObject *object,
                         "encoder must return a tuple (object, integer)");
         goto onError;
     }
-    v = Py_NewRef(PyTuple_GET_ITEM(result,0));
+    v = PyTuple_GetItemRef(result, 0);
     /* We don't check or use the second (integer) entry. */
 
     Py_DECREF(args);
@@ -455,7 +455,7 @@ _PyCodec_DecodeInternal(PyObject *object,
                         "decoder must return a tuple (object,integer)");
         goto onError;
     }
-    v = Py_NewRef(PyTuple_GET_ITEM(result,0));
+    v = PyTuple_GetItemRef(result, 0);
     /* We don't check or use the second (integer) entry. */
 
     Py_DECREF(args);
@@ -550,7 +550,7 @@ PyObject *codec_getitem_checked(const char *encoding,
     if (codec == NULL)
         return NULL;
 
-    v = Py_NewRef(PyTuple_GET_ITEM(codec, index));
+    v = PyTuple_GetItemRef(codec, index);
     Py_DECREF(codec);
     return v;
 }

Objects/unionobject.c

@@ -1064,7 +1064,7 @@ merge_consts_recursive(PyObject *const_cache, PyObject *o)
             }
             PyObject *u;
             if (PyTuple_CheckExact(k)) {
-                u = Py_NewRef(PyTuple_GET_ITEM(k, 1));
+                u = PyTuple_GetItemRef(k, 1);
                 Py_DECREF(k);
             }
             else {

PC/python3dll.c

@@ -1625,7 +1625,7 @@ vgetargskeywords(PyObject *args, PyObject *kwargs, const char *format,
         if (!skip) {
             PyObject *current_arg;
             if (i < nargs) {
-                current_arg = Py_NewRef(PyTuple_GET_ITEM(args, i));
+                current_arg = PyTuple_GetItemRef(args, i);
             }
             else if (nkwargs && i >= pos) {
                 if (PyDict_GetItemStringRef(kwargs, kwlist[i], &current_arg) < 0) {