pythongh-111489: Add PyList_FromArrayMoveRef() function

Add new functions to create tuple and list from arrays:

* PyTuple_FromArray().
* PyTuple_FromArrayMoveRef().
* PyList_FromArrayMoveRef().

Add tests on new functions.

Doc/c-api/list.rst

@@ -43,6 +43,19 @@ List Objects
       setting all items to a real object with :c:func:`PyList_SetItem`.
 
 
+.. c:function:: PyObject* PyList_FromArrayMoveRef(PyObject **array, Py_ssize_t size)
+
+   Create a list of *size* items and move *array* :term:`strong references
+   <strong reference>` to the new list.
+
+   * Return a new reference on success. *array* references become
+     :term:`borrowed references <borrowed reference>`.
+   * Set an exception and return ``NULL`` on error. *array* is left unchanged,
+     the caller should clear *array* strong references.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: Py_ssize_t PyList_Size(PyObject *list)
 
    .. index:: pair: built-in function; len

Doc/c-api/tuple.rst

@@ -36,6 +36,30 @@ Tuple Objects
    Return a new tuple object of size *len*, or ``NULL`` on failure.
 
 
+.. c:function:: PyObject* PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)
+
+   Create a tuple of *size* items and copy references from *array* to the new
+   tuple.
+
+   * Return a new reference on success.
+   * Set an exception and return NULL on error.
+
+   .. versionadded:: 3.13
+
+
+.. c:function:: PyObject* PyTuple_FromArrayMoveRef(PyObject **array, Py_ssize_t size)
+
+   Create a tuple of *size* items and move *array* :term:`strong references
+   <strong reference>` to the new tuple.
+
+   * Return a new reference on success. *array* references become :term:`borrowed
+     references <borrowed reference>`.
+   * Set an exception and return ``NULL`` on error. *array* is left unchanged,
+     the caller should clear *array* strong references.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
 
    Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values

Doc/whatsnew/3.13.rst

@@ -1269,6 +1269,14 @@ New Features
 * Add :c:func:`Py_HashPointer` function to hash a pointer.
   (Contributed by Victor Stinner in :gh:`111545`.)
 
+* Add new functions to create :class:`tuple` and :class:`list` from arrays:
+
+  * :c:func:`PyTuple_FromArray`.
+  * :c:func:`PyTuple_FromArrayMoveRef`.
+  * :c:func:`PyList_FromArrayMoveRef`.
+
+  (Contributed by Victor Stinner in :gh:`111489`.)
+
 
 Porting to Python 3.13
 ----------------------

Include/cpython/listobject.h

@@ -47,3 +47,6 @@ PyList_SET_ITEM(PyObject *op, Py_ssize_t index, PyObject *value) {
 
 PyAPI_FUNC(int) PyList_Extend(PyObject *self, PyObject *iterable);
 PyAPI_FUNC(int) PyList_Clear(PyObject *self);
+PyAPI_FUNC(PyObject*) PyList_FromArrayMoveRef(
+    PyObject *const *array,
+    Py_ssize_t size);

Include/cpython/tupleobject.h

@@ -36,3 +36,10 @@ PyTuple_SET_ITEM(PyObject *op, Py_ssize_t index, PyObject *value) {
 }
 #define PyTuple_SET_ITEM(op, index, value) \
     PyTuple_SET_ITEM(_PyObject_CAST(op), (index), _PyObject_CAST(value))
+
+PyAPI_FUNC(PyObject*) PyTuple_FromArray(
+    PyObject *const *array,
+    Py_ssize_t size);
+PyAPI_FUNC(PyObject*) PyTuple_FromArrayMoveRef(
+    PyObject *const *array,
+    Py_ssize_t size);

Include/internal/pycore_list.h

@@ -77,7 +77,9 @@ typedef struct {
     PyListObject *it_seq; /* Set to NULL when iterator is exhausted */
 } _PyListIterObject;
 
-extern PyObject *_PyList_FromArraySteal(PyObject *const *src, Py_ssize_t n);
+extern PyObject *_PyList_FromArraySteal(
+    PyObject *const *array,
+    Py_ssize_t size);
 
 #ifdef __cplusplus
 }

Include/internal/pycore_tuple.h

@@ -63,8 +63,11 @@ struct _Py_tuple_state {
 
 #define _PyTuple_ITEMS(op) _Py_RVALUE(_PyTuple_CAST(op)->ob_item)
 
-extern PyObject *_PyTuple_FromArray(PyObject *const *, Py_ssize_t);
-extern PyObject *_PyTuple_FromArraySteal(PyObject *const *, Py_ssize_t);
+// Alias for backward compatibility
+#define _PyTuple_FromArray PyTuple_FromArray
+extern PyObject *_PyTuple_FromArraySteal(
+    PyObject *const *array,
+    Py_ssize_t size);
 
 
 typedef struct {

Lib/test/test_capi/test_list.py

@@ -342,3 +342,11 @@ def test_list_extend(self):
 
         # CRASHES list_extend(NULL, [])
         # CRASHES list_extend([], NULL)
+
+    def test_list_fromarraymoveref(self):
+        # Test PyList_FromArrayMoveRef()
+        list_fromarraymoveref = _testcapi.list_fromarraymoveref
+
+        lst = [object() for _ in range(5)]
+        copy = list_fromarraymoveref(lst)
+        self.assertEqual(copy, lst)

Lib/test/test_capi/test_tuple.py

@@ -0,0 +1,21 @@
+import unittest
+from test.support import import_helper
+_testcapi = import_helper.import_module('_testcapi')
+
+
+class CAPITest(unittest.TestCase):
+    def test_tuple_fromarray(self):
+        # Test PyTuple_FromArray()
+        tuple_fromarray = _testcapi.tuple_fromarraymoveref
+
+        tup = tuple(object() for _ in range(5))
+        copy = tuple_fromarray(tup)
+        self.assertEqual(copy, tup)
+
+    def test_tuple_fromarraymoveref(self):
+        # Test PyTuple_FromArrayMoveRef()
+        tuple_fromarraymoveref = _testcapi.tuple_fromarraymoveref
+
+        tup = tuple(object() for _ in range(5))
+        copy = tuple_fromarraymoveref(tup)
+        self.assertEqual(copy, tup)

Misc/NEWS.d/next/C API/2023-12-11-18-30-51.gh-issue-111489.S78zth.rst

@@ -0,0 +1,7 @@
+Add new functions to create :class:`tuple` and :class:`list` from arrays:
+
+* :c:func:`PyTuple_FromArray`.
+* :c:func:`PyTuple_FromArrayMoveRef`.
+* :c:func:`PyList_FromArrayMoveRef`.
+
+Patch by Victor Stinner.

Modules/_testcapi/list.c

@@ -183,6 +183,45 @@ list_extend(PyObject* Py_UNUSED(module), PyObject *args)
 }
 
 
+static PyObject *
+list_fromarraymoveref(PyObject* Py_UNUSED(module), PyObject *args)
+{
+    PyObject *src;
+    if (!PyArg_ParseTuple(args, "O!", &PyList_Type, &src)) {
+        return NULL;
+    }
+
+    Py_ssize_t size = PyList_GET_SIZE(src);
+    PyObject **array = PyMem_Malloc(size * sizeof(PyObject**));
+    if (array == NULL) {
+        PyErr_NoMemory();
+        return NULL;
+    }
+    for (Py_ssize_t i = 0; i < size; i++) {
+        array[i] = Py_NewRef(PyList_GET_ITEM(src, i));
+    }
+
+    PyObject *list = PyList_FromArrayMoveRef(array, size);
+
+    for (Py_ssize_t i = 0; i < size; i++) {
+        // check that the array is not modified
+        assert(array[i] == PyList_GET_ITEM(src, i));
+
+        // check that the array was copied properly
+        assert(PyList_GET_ITEM(list, i) == array[i]);
+    }
+
+    if (list == NULL) {
+        for (Py_ssize_t i = 0; i < size; i++) {
+            Py_DECREF(array[i]);
+        }
+    }
+    PyMem_Free(array);
+
+    return list;
+}
+
+
 static PyMethodDef test_methods[] = {
     {"list_check", list_check, METH_O},
     {"list_check_exact", list_check_exact, METH_O},
@@ -202,6 +241,7 @@ static PyMethodDef test_methods[] = {
     {"list_astuple", list_astuple, METH_O},
     {"list_clear", list_clear, METH_O},
     {"list_extend", list_extend, METH_VARARGS},
+    {"list_fromarraymoveref", list_fromarraymoveref, METH_VARARGS},
     {NULL},
 };
 

Modules/_testcapi/tuple.c

@@ -2,7 +2,68 @@
 #include "util.h"
 
 
+static PyObject *
+tuple_fromarray_impl(PyObject *args, int move_ref)
+{
+    PyObject *src;
+    if (!PyArg_ParseTuple(args, "O!", &PyTuple_Type, &src)) {
+        return NULL;
+    }
+
+    Py_ssize_t size = PyTuple_GET_SIZE(src);
+    PyObject **array = PyMem_Malloc(size * sizeof(PyObject**));
+    if (array == NULL) {
+        PyErr_NoMemory();
+        return NULL;
+    }
+    for (Py_ssize_t i = 0; i < size; i++) {
+        array[i] = Py_NewRef(PyTuple_GET_ITEM(src, i));
+    }
+
+    PyObject *tuple;
+    if (move_ref) {
+        tuple = PyTuple_FromArrayMoveRef(array, size);
+    }
+    else {
+        tuple = PyTuple_FromArray(array, size);
+    }
+
+    for (Py_ssize_t i = 0; i < size; i++) {
+        // check that the array is not modified
+        assert(array[i] == PyTuple_GET_ITEM(src, i));
+
+        // check that the array was copied properly
+        assert(PyTuple_GET_ITEM(tuple, i) == array[i]);
+    }
+
+    if (!move_ref || tuple == NULL) {
+        for (Py_ssize_t i = 0; i < size; i++) {
+            Py_DECREF(array[i]);
+        }
+    }
+    PyMem_Free(array);
+
+    return tuple;
+}
+
+
+static PyObject *
+tuple_fromarray(PyObject* Py_UNUSED(module), PyObject *args)
+{
+    return tuple_fromarray_impl(args, 0);
+}
+
+
+static PyObject *
+tuple_fromarraymoveref(PyObject* Py_UNUSED(module), PyObject *args)
+{
+    return tuple_fromarray_impl(args, 1);
+}
+
+
 static PyMethodDef test_methods[] = {
+    {"tuple_fromarray", tuple_fromarray, METH_VARARGS},
+    {"tuple_fromarraymoveref", tuple_fromarraymoveref, METH_VARARGS},
     {NULL},
 };
 

Objects/listobject.c

@@ -2622,25 +2622,36 @@ PyList_AsTuple(PyObject *v)
     return _PyTuple_FromArray(((PyListObject *)v)->ob_item, Py_SIZE(v));
 }
 
-PyObject *
-_PyList_FromArraySteal(PyObject *const *src, Py_ssize_t n)
+PyObject*
+PyList_FromArrayMoveRef(PyObject *const *array, Py_ssize_t size)
 {
-    if (n == 0) {
+    if (size == 0) {
         return PyList_New(0);
     }
 
-    PyListObject *list = (PyListObject *)PyList_New(n);
-    if (list == NULL) {
-        for (Py_ssize_t i = 0; i < n; i++) {
-            Py_DECREF(src[i]);
-        }
+    PyObject *op = PyList_New(size);
+    if (op == NULL) {
         return NULL;
     }
+    PyListObject *list = (PyListObject *)op;
 
-    PyObject **dst = list->ob_item;
-    memcpy(dst, src, n * sizeof(PyObject *));
+    PyObject **items = list->ob_item;
+    // PyList_New(size) returns NULL is size*sizeof(PyObject*) is greater than
+    // PY_SSIZE_T_MAX. No need to check for integer overflow again.
+    memcpy(items, array, size * sizeof(PyObject *));
+    return op;
+}
 
-    return (PyObject *)list;
+PyObject *
+_PyList_FromArraySteal(PyObject *const *array, Py_ssize_t size)
+{
+    PyObject *list = PyList_FromArrayMoveRef(array, size);
+    if (list == NULL) {
+        for (Py_ssize_t i = 0; i < size; i++) {
+            Py_DECREF(array[i]);
+        }
+    }
+    return list;
 }
 
 /*[clinic input]