gh-139888: Add PyTupleWriter C API

* Add _PyTuple_NewNoTrack() and _PyTuple_ResizeNoTrack() helper
  functions.
* Modify PySequence_Tuple() to use PyTupleWriter API.
* Soft deprecate _PyTuple_Resize().

Author: vstinner

Doc/c-api/tuple.rst

@@ -142,6 +142,71 @@ Tuple Objects
    ``*p`` is destroyed.  On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and
    raises :exc:`MemoryError` or :exc:`SystemError`.
 
+   .. deprecated:: 3.15
+      The function is :term:`soft deprecated`,
+      use the :ref:`PyTupleWriter API <pytuplewriter>` instead.
+
+
+.. _pytuplewriter:
+
+PyTupleWriter
+-------------
+
+The :c:type:`PyTupleWriter` API can be used to create a Python :class:`tuple`
+object.
+
+.. versionadded:: next
+
+.. c:type:: PyTupleWriter
+
+   A tuple writer instance.
+
+   The API is **not thread safe**: a writer should only be used by a single
+   thread at the same time.
+
+   The instance must be destroyed by :c:func:`PyTupleWriter_Finish` on
+   success, or :c:func:`PyTupleWriter_Discard` on error.
+
+
+.. c:function:: PyTupleWriter* PyTupleWriter_Create(Py_ssize_t size)
+
+   Create a :c:type:`PyTupleWriter` to add *size* items.
+
+   If *size* is greater than zero, preallocate *size* items. The caller is
+   responsible to add *size* items using :c:func:`PyTupleWriter_Add`.
+
+   On error, set an exception and return ``NULL``.
+
+   *size* must be positive or zero.
+
+
+.. c:function:: PyObject* PyTupleWriter_Finish(PyTupleWriter *writer)
+
+   Finish a :c:type:`PyTupleWriter` created by
+   :c:func:`PyTupleWriter_Create`.
+
+   On success, return a Python :class:`tuple` object.
+   On error, set an exception and return ``NULL``.
+
+   The writer instance is invalid after the call in any case.
+   No API can be called on the writer after :c:func:`PyTupleWriter_Finish`.
+
+.. c:function:: void PyTupleWriter_Discard(PyTupleWriter *writer)
+
+   Discard a :c:type:`PyTupleWriter` created by :c:func:`PyTupleWriter_Create`.
+
+   Do nothing if *writer* is ``NULL``.
+
+   The writer instance is invalid after the call.
+   No API can be called on the writer after :c:func:`PyTupleWriter_Discard`.
+
+.. c:function:: int PyTupleWriter_Add(PyTupleWriter *writer, PyObject *item)
+
+   Add an item to *writer*.
+
+   On success, return ``0``.
+   On error, set an exception and return ``-1``.
+
 
 .. _struct-sequence-objects:
 

Doc/whatsnew/3.15.rst

@@ -855,6 +855,15 @@ New features
 * Add :c:func:`PyTuple_FromArray` to create a :class:`tuple` from an array.
   (Contributed by Victor Stinner in :gh:`111489`.)
 
+* Add a :ref:`PyTupleWriter API <pytuplewriter>` to create :class:`tuple`:
+
+  * :c:func:`PyTupleWriter_Create`
+  * :c:func:`PyTupleWriter_Add`
+  * :c:func:`PyTupleWriter_Finish`
+  * :c:func:`PyTupleWriter_Discard`
+
+  (Contributed by Victor Stinner in :gh:`139888`.)
+
 
 Porting to Python 3.15
 ----------------------

Include/cpython/tupleobject.h

@@ -42,3 +42,14 @@ PyTuple_SET_ITEM(PyObject *op, Py_ssize_t index, PyObject *value) {
 PyAPI_FUNC(PyObject*) PyTuple_FromArray(
     PyObject *const *array,
     Py_ssize_t size);
+
+// --- Public PyUnicodeWriter API --------------------------------------------
+
+typedef struct PyTupleWriter PyTupleWriter;
+
+PyAPI_FUNC(PyTupleWriter*) PyTupleWriter_Create(Py_ssize_t size);
+PyAPI_FUNC(int) PyTupleWriter_Add(
+    PyTupleWriter *writer,
+    PyObject *item);
+PyAPI_FUNC(PyObject*) PyTupleWriter_Finish(PyTupleWriter *writer);
+PyAPI_FUNC(void) PyTupleWriter_Discard(PyTupleWriter *writer);

Include/internal/pycore_freelist_state.h

@@ -28,6 +28,7 @@ extern "C" {
 #  define Py_object_stack_chunks_MAXFREELIST 4
 #  define Py_unicode_writers_MAXFREELIST 1
 #  define Py_bytes_writers_MAXFREELIST 1
+#  define Py_tuple_writers_MAXFREELIST 1
 #  define Py_pycfunctionobject_MAXFREELIST 16
 #  define Py_pycmethodobject_MAXFREELIST 16
 #  define Py_pymethodobjects_MAXFREELIST 20
@@ -63,6 +64,7 @@ struct _Py_freelists {
     struct _Py_freelist object_stack_chunks;
     struct _Py_freelist unicode_writers;
     struct _Py_freelist bytes_writers;
+    struct _Py_freelist tuple_writers;
     struct _Py_freelist pycfunctionobject;
     struct _Py_freelist pycmethodobject;
     struct _Py_freelist pymethodobjects;

Lib/test/test_capi/test_tuple.py

@@ -302,5 +302,30 @@ def my_iter():
         self.assertEqual(tuples, [])
 
 
+class TupleWriterTest(unittest.TestCase):
+    def create_writer(self, size):
+        return _testcapi.PyTupleWriter(size)
+
+    def test_create(self):
+        # Test PyTupleWriter_Create()
+        writer = self.create_writer(0)
+        self.assertIs(writer.finish(), ())
+
+        writer = self.create_writer(123)
+        self.assertIs(writer.finish(), ())
+
+    def test_add(self):
+         # Test PyTupleWriter_Add()
+         writer = self.create_writer(3)
+         for ch in 'abc':
+             writer.add(ch)
+         self.assertEqual(writer.finish(), ('a', 'b', 'c'))
+
+         writer = self.create_writer(0)
+         for i in range(1024):
+             writer.add(i)
+         self.assertEqual(writer.finish(), tuple(range(1024)))
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C_API/2025-10-10-09-54-28.gh-issue-139888.Z4Px61.rst

@@ -0,0 +1,8 @@
+Add a :ref:`PyTupleWriter API <pytuplewriter>` to create :class:`tuple`:
+
+* :c:func:`PyTupleWriter_Create`
+* :c:func:`PyTupleWriter_Add`
+* :c:func:`PyTupleWriter_Finish`
+* :c:func:`PyTupleWriter_Discard`
+
+Patch by Victor Stinner.

Misc/NEWS.d/next/C_API/2025-10-10-09-58-57.gh-issue-139888.xCfJ3L.rst

@@ -0,0 +1,2 @@
+The :c:func:`_PyTuple_Resize` function is now :term:`soft deprecated`, use
+the :ref:`PyTupleWriter API <pytuplewriter>` instead.

Modules/_testcapi/tuple.c

@@ -131,6 +131,127 @@ tuple_fromarray(PyObject* Py_UNUSED(module), PyObject *args)
 }
 
 
+// --- PyTupleWriter type ---------------------------------------------------
+
+typedef struct {
+    PyObject_HEAD
+    PyTupleWriter *writer;
+} WriterObject;
+
+
+static PyObject *
+writer_new(PyTypeObject *type, PyObject *args, PyObject *kwargs)
+{
+    WriterObject *self = (WriterObject *)type->tp_alloc(type, 0);
+    if (!self) {
+        return NULL;
+    }
+    self->writer = NULL;
+    return (PyObject*)self;
+}
+
+
+static int
+writer_init(PyObject *self_raw, PyObject *args, PyObject *kwargs)
+{
+    if (kwargs && PyDict_GET_SIZE(kwargs)) {
+        PyErr_Format(PyExc_TypeError,
+                     "PyTupleWriter() takes exactly no keyword arguments");
+        return -1;
+    }
+
+    Py_ssize_t size;
+    if (!PyArg_ParseTuple(args, "n", &size)) {
+        return -1;
+    }
+
+    WriterObject *self = (WriterObject *)self_raw;
+    if (self->writer) {
+        PyTupleWriter_Discard(self->writer);
+    }
+    self->writer = PyTupleWriter_Create(size);
+    if (self->writer == NULL) {
+        return -1;
+    }
+    return 0;
+}
+
+
+static void
+writer_dealloc(PyObject *self_raw)
+{
+    WriterObject *self = (WriterObject *)self_raw;
+    PyTypeObject *tp = Py_TYPE(self);
+    if (self->writer) {
+        PyTupleWriter_Discard(self->writer);
+    }
+    tp->tp_free(self);
+    Py_DECREF(tp);
+}
+
+
+static inline int
+writer_check(WriterObject *self)
+{
+    if (self->writer == NULL) {
+        PyErr_SetString(PyExc_ValueError, "operation on finished writer");
+        return -1;
+    }
+    return 0;
+}
+
+
+static PyObject*
+writer_add(PyObject *self_raw, PyObject *item)
+{
+    WriterObject *self = (WriterObject *)self_raw;
+    if (writer_check(self) < 0) {
+        return NULL;
+    }
+
+    if (PyTupleWriter_Add(self->writer, item) < 0) {
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
+
+
+static PyObject*
+writer_finish(PyObject *self_raw, PyObject *Py_UNUSED(args))
+{
+    WriterObject *self = (WriterObject *)self_raw;
+    if (writer_check(self) < 0) {
+        return NULL;
+    }
+
+    PyObject *tuple = PyTupleWriter_Finish(self->writer);
+    self->writer = NULL;
+    return tuple;
+}
+
+
+static PyMethodDef writer_methods[] = {
+    {"add", _PyCFunction_CAST(writer_add), METH_O},
+    {"finish", _PyCFunction_CAST(writer_finish), METH_NOARGS},
+    {NULL, NULL}  /* sentinel */
+};
+
+static PyType_Slot Writer_Type_slots[] = {
+    {Py_tp_new, writer_new},
+    {Py_tp_init, writer_init},
+    {Py_tp_dealloc, writer_dealloc},
+    {Py_tp_methods, writer_methods},
+    {0, 0},  /* sentinel */
+};
+
+static PyType_Spec Writer_spec = {
+    .name = "_testcapi.PyTupleWriter",
+    .basicsize = sizeof(WriterObject),
+    .flags = Py_TPFLAGS_DEFAULT,
+    .slots = Writer_Type_slots,
+};
+
+
 static PyMethodDef test_methods[] = {
     {"tuple_get_size", tuple_get_size, METH_O},
     {"tuple_get_item", tuple_get_item, METH_VARARGS},
@@ -148,5 +269,15 @@ _PyTestCapi_Init_Tuple(PyObject *m)
         return -1;
     }
 
+    PyTypeObject *writer_type = (PyTypeObject *)PyType_FromSpec(&Writer_spec);
+    if (writer_type == NULL) {
+        return -1;
+    }
+    if (PyModule_AddType(m, writer_type) < 0) {
+        Py_DECREF(writer_type);
+        return -1;
+    }
+    Py_DECREF(writer_type);
+
     return 0;
 }

Objects/abstract.c

@@ -1996,8 +1996,6 @@ PySequence_DelSlice(PyObject *s, Py_ssize_t i1, Py_ssize_t i2)
 PyObject *
 PySequence_Tuple(PyObject *v)
 {
-    PyObject *it;  /* iter(v) */
-
     if (v == NULL) {
         return null_error();
     }
@@ -2010,62 +2008,39 @@ PySequence_Tuple(PyObject *v)
            a copy, so there's no need for exactness below. */
         return Py_NewRef(v);
     }
-    if (PyList_CheckExact(v))
+    if (PyList_CheckExact(v)) {
         return PyList_AsTuple(v);
+    }
 
     /* Get iterator. */
-    it = PyObject_GetIter(v);
-    if (it == NULL)
+    PyObject *it = PyObject_GetIter(v);
+    if (it == NULL) {
         return NULL;
-
-    Py_ssize_t n;
-    PyObject *buffer[8];
-    for (n = 0; n < 8; n++) {
-        PyObject *item = PyIter_Next(it);
-        if (item == NULL) {
-            if (PyErr_Occurred()) {
-                goto fail;
-            }
-            Py_DECREF(it);
-            return _PyTuple_FromArraySteal(buffer, n);
-        }
-        buffer[n] = item;
     }
-    PyListObject *list = (PyListObject *)PyList_New(16);
-    if (list == NULL) {
+
+    PyTupleWriter *writer = PyTupleWriter_Create(0);
+    if (writer == NULL) {
         goto fail;
     }
-    assert(n == 8);
-    Py_SET_SIZE(list, n);
-    for (Py_ssize_t j = 0; j < n; j++) {
-        PyList_SET_ITEM(list, j, buffer[j]);
-    }
+
     for (;;) {
         PyObject *item = PyIter_Next(it);
         if (item == NULL) {
             if (PyErr_Occurred()) {
-                Py_DECREF(list);
-                Py_DECREF(it);
-                return NULL;
+                goto fail;
             }
             break;
         }
-        if (_PyList_AppendTakeRef(list, item) < 0) {
-            Py_DECREF(list);
-            Py_DECREF(it);
-            return NULL;
+        if (PyTupleWriter_Add(writer, item) < 0) {
+            goto fail;
         }
     }
     Py_DECREF(it);
-    PyObject *res = _PyList_AsTupleAndClear(list);
-    Py_DECREF(list);
-    return res;
+    return PyTupleWriter_Finish(writer);
+
 fail:
     Py_DECREF(it);
-    while (n > 0) {
-        n--;
-        Py_DECREF(buffer[n]);
-    }
+    PyTupleWriter_Discard(writer);
     return NULL;
 }
 

Objects/object.c

@@ -946,6 +946,7 @@ _PyObject_ClearFreeLists(struct _Py_freelists *freelists, int is_finalization)
     }
     clear_freelist(&freelists->unicode_writers, is_finalization, PyMem_Free);
     clear_freelist(&freelists->bytes_writers, is_finalization, PyMem_Free);
+    clear_freelist(&freelists->tuple_writers, is_finalization, PyMem_Free);
     clear_freelist(&freelists->ints, is_finalization, free_object);
     clear_freelist(&freelists->pycfunctionobject, is_finalization, PyObject_GC_Del);
     clear_freelist(&freelists->pycmethodobject, is_finalization, PyObject_GC_Del);