Add PyListWriter_FromBuffer() function

Add internal _PyMemoryView_ToListWriter() function.

Author: vstinner

Doc/c-api/list.rst

@@ -329,3 +329,12 @@ On Free Threading, it's more efficient than the ``PyList`` C API to create a
 
    On success, return ``0``.
    On error, set an exception, leave the writer unchanged, and return ``-1``.
+
+.. c:function:: int PyListWriter_FromBuffer(PyListWriter *writer, PyBuffer *view)
+
+   Add values from a buffer.
+
+   *buffer* must have 1 dimension.
+
+   On success, return ``0``.
+   On error, set an exception, leave the writer unchanged, and return ``-1``.

Doc/whatsnew/3.16.rst

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

Include/cpython/listobject.h

@@ -81,3 +81,6 @@ PyAPI_FUNC(int) PyListWriter_FromFormat(
     PyListWriter *writer,
     const char *format,
     ...);
+PyAPI_FUNC(int) PyListWriter_FromBuffer(
+    PyListWriter *writer,
+    Py_buffer *buf);

Lib/test/test_capi/test_list.py

@@ -1,3 +1,4 @@
+import array
 import threading
 import unittest
 from collections import UserList
@@ -460,7 +461,7 @@ def test_extend_array_steal(self):
         # Test PyListWriter_ExtendArraySteal()
         self.check_extend('extend_array_steal')
 
-    def test_build_value(self):
+    def test_from_format(self):
         # Test PyListWriter_FromFormat()
 
         # Allocate a small array on the stack (1 item)
@@ -483,6 +484,17 @@ def test_build_value(self):
         writer.append("after")
         self.list_equal(writer.finish(), ["before", "after"])
 
+    def test_from_buffer(self):
+        # Test PyListWriter_FromBuffer()
+        writer = self.create_writer(0)
+        writer.from_buffer(memoryview(b'abc'))
+        self.list_equal(writer.finish(), [97, 98, 99])
+
+        numbers = array.array('d', [1.5, 3.0, 5.0])
+        writer = self.create_writer(0)
+        writer.from_buffer(memoryview(numbers))
+        self.list_equal(writer.finish(), [1.5, 3.0, 5.0])
+
     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

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

Modules/_testcapi/list.c

@@ -365,6 +365,30 @@ writer_from_format_error(PyObject *self_raw, PyObject *Py_UNUSED(args))
 }
 
 
+// Test PyListWriter_FromBuffer() error
+static PyObject*
+writer_from_buffer(PyObject *self_raw, PyObject *obj)
+{
+    WriterObject *self = (WriterObject *)self_raw;
+    if (writer_check(self) < 0) {
+        return NULL;
+    }
+
+    Py_buffer view;
+    int flags = PyBUF_FORMAT | PyBUF_ND | PyBUF_STRIDES;
+    if (PyObject_GetBuffer(obj, &view, flags) < 0) {
+        return NULL;
+    }
+
+    int res = PyListWriter_FromBuffer(self->writer, &view);
+    PyBuffer_Release(&view);
+    if (res < 0) {
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
+
+
 // Test PyListWriter_Finish()
 static PyObject*
 writer_finish(PyObject *self_raw, PyObject *Py_UNUSED(args))
@@ -404,6 +428,7 @@ static PyMethodDef writer_methods[] = {
     {"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},
+    {"from_buffer", _PyCFunction_CAST(writer_from_buffer), METH_O},
     {"finish", _PyCFunction_CAST(writer_finish), METH_NOARGS},
     {"discard", _PyCFunction_CAST(writer_discard), METH_NOARGS},
     {NULL,              NULL}           /* sentinel */

Objects/listobject.c

@@ -4706,3 +4706,25 @@ PyListWriter_FromFormat(PyListWriter *writer, const char *format, ...)
     }
     return res;
 }
+
+
+int
+PyListWriter_FromBuffer(PyListWriter *writer, Py_buffer *buf)
+{
+    extern int _PyMemoryView_ToListWriter(PyObject *self,
+                                          PyListWriter *writer);
+
+    if (buf->ndim != 1) {
+        PyErr_SetString(PyExc_ValueError, "require a buffer of 1 dimension");
+        return -1;
+    }
+
+    PyObject *mview = PyMemoryView_FromBuffer(buf);
+    if (mview == NULL) {
+        return -1;
+    }
+
+    int res = _PyMemoryView_ToListWriter(mview, writer);
+    Py_DECREF(mview);
+    return res;
+}

Objects/memoryobject.c

@@ -2303,6 +2303,24 @@ tolist_base(PyMemoryViewObject *self, const char *ptr, const Py_ssize_t *shape,
     return lst;
 }
 
+static int
+tolistwriter(PyListWriter *writer, PyMemoryViewObject *self, const char *ptr,
+             const Py_ssize_t *shape, const Py_ssize_t *strides,
+             const Py_ssize_t *suboffsets, const char *fmt)
+{
+    for (Py_ssize_t i = 0; i < shape[0]; ptr+=strides[0], i++) {
+        const char *xptr = ADJUST_PTR(ptr, suboffsets, 0);
+        PyObject *item = unpack_single(self, xptr, fmt);
+        if (item == NULL) {
+            return -1;
+        }
+        if (PyListWriter_AppendSteal(writer, item) < 0) {
+            return -1;
+        }
+    }
+    return 0;
+}
+
 /* Unpack a multi-dimensional array into a nested list.
    Assumption: ndim >= 1. */
 static PyObject *
@@ -2374,6 +2392,26 @@ memoryview_tolist_impl(PyMemoryViewObject *self)
     }
 }
 
+
+int
+_PyMemoryView_ToListWriter(PyObject *mview, PyListWriter *writer)
+{
+    assert(PyMemoryView_Check(mview));
+    PyMemoryViewObject *self = (PyMemoryViewObject *)mview;
+    const Py_buffer *view = &self->view;
+    assert(view->ndim == 1);
+
+    const char *fmt = adjust_fmt(view);
+    if (fmt == NULL) {
+        return -1;
+    }
+
+    return tolistwriter(writer, self, view->buf, view->shape,
+                        view->strides, view->suboffsets,
+                        fmt);
+}
+
+
 /*[clinic input]
 memoryview.tobytes