Add PyListWriter_FromFormat()

Author: vstinner

Doc/c-api/list.rst

@@ -320,3 +320,12 @@ On Free Threading, it's more efficient than the ``PyList`` C API to create a
    instead of copying references.
 
    On error, all *items* references are also cleared.
+
+.. c:function:: int PyListWriter_FromFormat(PyListWriter *writer, const char *format, ...)
+
+   Add values using :ref:`building values format <arg-parsing>`.
+
+   Example adding 3 integers: ``PyListWriter_FromFormat(writer, "iii", 1, 2, 3)``.
+
+   On success, return ``0``.
+   On error, set an exception, leave the writer unchanged, and return ``-1``.

Doc/whatsnew/3.16.rst

@@ -1323,6 +1323,7 @@ New features
   * :c:func:`PyListWriter_Extend`
   * :c:func:`PyListWriter_ExtendArray`
   * :c:func:`PyListWriter_ExtendArraySteal`
+  * :c:func:`PyListWriter_FromFormat`
 
   (Contributed by Victor Stinner in :gh:`158660`.)
 

Include/cpython/listobject.h

@@ -77,3 +77,7 @@ PyAPI_FUNC(int) PyListWriter_ExtendArraySteal(
     PyListWriter *writer,
     PyObject *const *items,
     Py_ssize_t nitem);
+PyAPI_FUNC(int) PyListWriter_FromFormat(
+    PyListWriter *writer,
+    const char *format,
+    ...);

Include/internal/pycore_modsupport.h

@@ -32,12 +32,13 @@ PyAPI_FUNC(int) _PyArg_CheckPositional(const char *, Py_ssize_t,
     (((min) <= (nargs) && (nargs) <= (max)) \
      || _PyArg_CheckPositional((funcname), (nargs), (min), (max)))
 
-extern PyObject ** _Py_VaBuildStack(
+extern int _Py_VaBuildArray(
+    PyObject ***array,
+    Py_ssize_t *size,
     PyObject **small_stack,
     Py_ssize_t small_stack_len,
     const char *format,
-    va_list va,
-    Py_ssize_t *p_nargs);
+    va_list va);
 
 extern PyObject* _PyModule_CreateInitialized(PyModuleDef*, int apiver);
 

Lib/test/test_capi/test_list.py

@@ -460,6 +460,29 @@ def test_extend_array_steal(self):
         # Test PyListWriter_ExtendArraySteal()
         self.check_extend('extend_array_steal')
 
+    def test_build_value(self):
+        # Test PyListWriter_FromFormat()
+
+        # Allocate a small array on the stack (1 item)
+        writer = self.create_writer(0)
+        writer.from_format_i(123)
+        self.list_equal(writer.finish(), [123])
+
+        # Allocate an array on the heap (16 items)
+        items = tuple(range(100, 100+16))
+        writer = self.create_writer(0)
+        writer.from_format_i16(items)
+        self.list_equal(writer.finish(), items)
+
+        # Test error: call PyListWriter_FromFormat(writer, "iiO", 1, 2, NULL).
+        # First items before the error must not be added.
+        writer = self.create_writer(0)
+        writer.append("before")
+        with self.assertRaises(SystemError):
+            writer.from_format_error()
+        writer.append("after")
+        self.list_equal(writer.finish(), ["before", "after"])
+
     def test_empty(self):
         list_get_allocated = _testcapi._list_get_allocated
         empty_tuple = ()

Misc/NEWS.d/next/C_API/2026-10-21-16-35-42.gh-issue-158660.KvixNp.rst

@@ -11,5 +11,6 @@ created list. Add functions:
 * :c:func:`PyListWriter_Extend`
 * :c:func:`PyListWriter_ExtendArray`
 * :c:func:`PyListWriter_ExtendArraySteal`
+* :c:func:`PyListWriter_FromFormat`
 
 Patch by Victor Stinner.

Modules/_testcapi/list.c

@@ -288,6 +288,83 @@ writer_extend_array_steal(PyObject *self_raw, PyObject *tuple)
 }
 
 
+// Test PyListWriter_FromFormat("i")
+static PyObject*
+writer_from_format_i(PyObject *self_raw, PyObject *arg)
+{
+    WriterObject *self = (WriterObject *)self_raw;
+    if (writer_check(self) < 0) {
+        return NULL;
+    }
+
+    int value;
+    if (!PyArg_Parse(arg, "i", &value)) {
+        return NULL;
+    }
+
+    if (PyListWriter_FromFormat(self->writer, "i", value) < 0) {
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
+
+
+// Test PyListWriter_FromFormat("i")
+static PyObject*
+writer_from_format_i16(PyObject *self_raw, PyObject *tuple)
+{
+    WriterObject *self = (WriterObject *)self_raw;
+    if (writer_check(self) < 0) {
+        return NULL;
+    }
+
+    // Test size larger than small_array size in PyListWriter_FromFormat()
+    int values[16];
+    Py_ssize_t len = Py_ARRAY_LENGTH(values);
+    if (!PyTuple_Check(tuple) || PyTuple_GET_SIZE(tuple) != len) {
+        PyErr_Format(PyExc_ValueError,
+                     "expect a tuple of %zd integers", len);
+        return NULL;
+    }
+    for (Py_ssize_t i = 0; i < len; i++) {
+        int value = PyLong_AsInt(PyTuple_GET_ITEM(tuple, i));
+        if (value == -1 && PyErr_Occurred()) {
+            return NULL;
+        }
+        values[i] = value;
+    }
+
+    int res = PyListWriter_FromFormat(self->writer,
+        "iiiiiiiiiiiiiiii",
+        values[0], values[1], values[2], values[3],
+        values[4], values[5], values[6], values[7],
+        values[8], values[9], values[10], values[11],
+        values[12], values[13], values[14], values[15]
+    );
+    if (res < 0) {
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
+
+
+// Test PyListWriter_FromFormat() error
+static PyObject*
+writer_from_format_error(PyObject *self_raw, PyObject *Py_UNUSED(args))
+{
+    WriterObject *self = (WriterObject *)self_raw;
+    if (writer_check(self) < 0) {
+        return NULL;
+    }
+
+    int res = PyListWriter_FromFormat(self->writer, "iiO", 1, 2, NULL);
+    if (res < 0) {
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
+
+
 // Test PyListWriter_Finish()
 static PyObject*
 writer_finish(PyObject *self_raw, PyObject *Py_UNUSED(args))
@@ -324,6 +401,9 @@ static PyMethodDef writer_methods[] = {
     {"extend", _PyCFunction_CAST(writer_extend), METH_O},
     {"extend_array", _PyCFunction_CAST(writer_extend_array), METH_O},
     {"extend_array_steal", _PyCFunction_CAST(writer_extend_array_steal), METH_O},
+    {"from_format_i", _PyCFunction_CAST(writer_from_format_i), METH_O},
+    {"from_format_i16", _PyCFunction_CAST(writer_from_format_i16), METH_O},
+    {"from_format_error", _PyCFunction_CAST(writer_from_format_error), METH_NOARGS},
     {"finish", _PyCFunction_CAST(writer_finish), METH_NOARGS},
     {"discard", _PyCFunction_CAST(writer_discard), METH_NOARGS},
     {NULL,              NULL}           /* sentinel */

Objects/call.c

@@ -517,12 +517,6 @@ static PyObject *
 _PyObject_CallFunctionVa(PyThreadState *tstate, PyObject *callable,
                          const char *format, va_list va)
 {
-    PyObject* small_stack[_PY_FASTCALL_SMALL_STACK];
-    const Py_ssize_t small_stack_len = Py_ARRAY_LENGTH(small_stack);
-    PyObject **stack;
-    Py_ssize_t nargs, i;
-    PyObject *result;
-
     if (callable == NULL) {
         return null_error(tstate);
     }
@@ -531,12 +525,17 @@ _PyObject_CallFunctionVa(PyThreadState *tstate, PyObject *callable,
         return _PyObject_CallNoArgsTstate(tstate, callable);
     }
 
-    stack = _Py_VaBuildStack(small_stack, small_stack_len,
-                             format, va, &nargs);
-    if (stack == NULL) {
+    PyObject* small_stack[_PY_FASTCALL_SMALL_STACK];
+    PyObject **stack;
+    Py_ssize_t nargs;
+    if (_Py_VaBuildArray(&stack, &nargs,
+                         small_stack, Py_ARRAY_LENGTH(small_stack),
+                         format, va) < 0) {
         return NULL;
     }
     EVAL_CALL_STAT_INC_IF_FUNCTION(EVAL_CALL_API, callable);
+
+    PyObject *result;
     if (nargs == 1 && PyTuple_Check(stack[0])) {
         /* Special cases for backward compatibility:
            - PyObject_CallFunction(func, "O", tuple) calls func(*tuple)
@@ -553,7 +552,7 @@ _PyObject_CallFunctionVa(PyThreadState *tstate, PyObject *callable,
                                             stack, nargs, NULL);
     }
 
-    for (i = 0; i < nargs; ++i) {
+    for (Py_ssize_t i = 0; i < nargs; ++i) {
         Py_DECREF(stack[i]);
     }
     if (stack != small_stack) {
@@ -640,15 +639,19 @@ callmethod(PyThreadState *tstate, PyObject *obj, PyObject *name,
 
     /* Build the positional arguments from the format string. */
     PyObject *small_stack[_PY_FASTCALL_SMALL_STACK];
-    Py_ssize_t nargs = 0;
-    PyObject **built = NULL;
+    PyObject **built;
+    Py_ssize_t nargs;
     if (format != NULL && *format != '\0') {
-        built = _Py_VaBuildStack(small_stack, _PY_FASTCALL_SMALL_STACK,
-                                 format, va, &nargs);
-        if (built == NULL) {
+        if (_Py_VaBuildArray(&built, &nargs,
+                             small_stack, _PY_FASTCALL_SMALL_STACK,
+                             format, va) < 0) {
             goto exit;
         }
     }
+    else {
+        built = NULL;
+        nargs = 0;
+    }
 
     /* Backward compat: a single tuple from "O" is unpacked. */
     PyObject *const *args = built;

Objects/listobject.c

@@ -4674,3 +4674,29 @@ PyListWriter_ExtendArraySteal(PyListWriter *writer,
 {
     return listwriter_extend_array(writer, items, nitem, 1);
 }
+
+
+int
+PyListWriter_FromFormat(PyListWriter *writer, const char *format, ...)
+{
+    PyObject* small_array[8];
+    Py_ssize_t size;
+    PyObject **array;
+
+    va_list vargs;
+    va_start(vargs, format);
+    int res = _Py_VaBuildArray(
+        &array, &size,
+        small_array, Py_ARRAY_LENGTH(small_array),
+        format, vargs);
+    va_end(vargs);
+    if (res < 0) {
+        return -1;
+    }
+
+    res = PyListWriter_ExtendArraySteal(writer, array, size);
+    if (array != small_array) {
+        PyMem_Free(array);
+    }
+    return res;
+}

Python/modsupport.c

@@ -549,52 +549,55 @@ va_build_value(const char *format, va_list va)
     return retval;
 }
 
-PyObject **
-_Py_VaBuildStack(PyObject **small_stack, Py_ssize_t small_stack_len,
-                const char *format, va_list va, Py_ssize_t *p_nargs)
+int
+_Py_VaBuildArray(PyObject ***array, Py_ssize_t *array_size,
+                 PyObject **small_array, Py_ssize_t small_array_len,
+                 const char *format, va_list va)
 {
-    const char *f;
-    Py_ssize_t n;
-    va_list lva;
-    PyObject **stack;
-    int res;
-
-    n = countformat(format, '\0');
+    Py_ssize_t n = countformat(format, '\0');
     if (n < 0) {
-        *p_nargs = 0;
-        return NULL;
+        goto error;
     }
 
     if (n == 0) {
-        *p_nargs = 0;
-        return small_stack;
+        *array = small_array;
+        *array_size = 0;
+        return 0;
     }
 
-    if (n <= small_stack_len) {
-        stack = small_stack;
+    PyObject **stack;
+    if (n <= small_array_len) {
+        stack = small_array;
     }
     else {
         stack = PyMem_Malloc(n * sizeof(stack[0]));
         if (stack == NULL) {
             PyErr_NoMemory();
-            return NULL;
+            goto error;
         }
     }
 
+    va_list lva;
     va_copy(lva, va);
-    f = format;
-    res = do_mkstack(stack, &f, &lva, '\0', n);
+    const char *f = format;
+    int res = do_mkstack(stack, &f, &lva, '\0', n);
     va_end(lva);
 
     if (res < 0) {
-        if (stack != small_stack) {
+        if (stack != small_array) {
             PyMem_Free(stack);
         }
-        return NULL;
+        goto error;
     }
 
-    *p_nargs = n;
-    return stack;
+    *array = stack;
+    *array_size = n;
+    return 0;
+
+error:
+    *array = NULL;
+    *array_size = -1;
+    return -1;
 }