Add high-level API example

Author: vstinner

Include/cpython/bytesobject.h

@@ -57,7 +57,7 @@ PyAPI_FUNC(PyObject*) PyBytesWriter_FinishWithSize(
     Py_ssize_t size);
 PyAPI_FUNC(PyObject*) PyBytesWriter_FinishWithPointer(
     PyBytesWriter *writer,
-    void *data);
+    void *buf);
 
 PyAPI_FUNC(void*) PyBytesWriter_GetData(
     PyBytesWriter *writer);
@@ -82,4 +82,4 @@ PyAPI_FUNC(int) PyBytesWriter_Grow(
 PyAPI_FUNC(void*) PyBytesWriter_GrowAndUpdatePointer(
     PyBytesWriter *writer,
     Py_ssize_t size,
-    void *data);
+    void *buf);

Lib/test/test_capi/test_bytes.py

@@ -370,6 +370,9 @@ def test_abc(self):
     def test_resize(self):
         self.assertEqual(_testcapi.byteswriter_resize(), b'Hello World')
 
+    def test_highlevel(self):
+        self.assertEqual(_testcapi.byteswriter_highlevel(), b'Hello World!')
+
 
 class ByteArrayWriterTest(BytesWriterTest):
     result_type = bytearray

Modules/_testcapi/bytes.c

@@ -331,11 +331,33 @@ byteswriter_resize(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
 }
 
 
+static PyObject *
+byteswriter_highlevel(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
+{
+    PyBytesWriter *writer = PyBytesWriter_Create(0);
+    if (writer == NULL) {
+        goto error;
+    }
+    if (PyBytesWriter_WriteBytes(writer, "Hello", -1) < 0) {
+        goto error;
+    }
+    if (PyBytesWriter_Format(writer, " %s!", "World") < 0) {
+        goto error;
+    }
+    return PyBytesWriter_Finish(writer);
+
+error:
+    PyBytesWriter_Discard(writer);
+    return NULL;
+}
+
+
 static PyMethodDef test_methods[] = {
     {"bytes_resize", bytes_resize, METH_VARARGS},
     {"bytes_join", bytes_join, METH_VARARGS},
     {"byteswriter_abc", byteswriter_abc, METH_NOARGS},
     {"byteswriter_resize", byteswriter_resize, METH_NOARGS},
+    {"byteswriter_highlevel", byteswriter_highlevel, METH_NOARGS},
     {NULL},
 };
 

Objects/bytesobject.c

@@ -3920,9 +3920,9 @@ PyBytesWriter_Finish(PyBytesWriter *writer)
 
 
 PyObject*
-PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *data)
+PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)
 {
-    Py_ssize_t size = (char*)data - byteswriter_data(writer);
+    Py_ssize_t size = (char*)buf - byteswriter_data(writer);
     if (size < 0 || size > byteswriter_allocated(writer)) {
         PyBytesWriter_Discard(writer);
         PyErr_SetString(PyExc_ValueError, "invalid end pointer");
@@ -4005,9 +4005,9 @@ PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t size)
 
 void*
 PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size,
-                                   void *data)
+                                   void *buf)
 {
-    Py_ssize_t pos = (char*)data - byteswriter_data(writer);
+    Py_ssize_t pos = (char*)buf - byteswriter_data(writer);
     if (PyBytesWriter_Grow(writer, size) < 0) {
         return NULL;
     }