Update

Author: vstinner

peps/pep-0782.rst

@@ -80,8 +80,9 @@ Create, Finish, Discard
 
    Create a :c:type:`PyBytesWriter` to write *size* bytes.
 
-   If *size* is greater than zero, allocate *size* bytes for the
-   returned buffer, and set the writer size to *size*.
+   If *size* is greater than zero, allocate *size* bytes, and set the
+   writer size to *size*. The caller is responsible to write *size*
+   bytes using :c:func:`PyBytesWriter_GetData`.
 
    On error, set an exception and return NULL.
 
@@ -128,8 +129,9 @@ High-level API
 
 .. c:function:: int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)
 
-   Write *size* bytes of *bytes* at the *writer* end,
-   and add *size* to the writer size.
+   Grow the *writer* internal buffer by *size* bytes,
+   write *size* bytes of *bytes* at the *writer* end,
+   and add *size* to the *writer* size.
 
    If *size* is equal to ``-1``, call ``strlen(bytes)`` to get the
    string length.
@@ -140,7 +142,8 @@ High-level API
 .. c:function:: int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)
 
    Similar to ``PyBytes_FromFormat()``, but write the output directly at
-   the writer end. Then add the written size to the writer size.
+   the writer end. Grow the writer internal buffer on demand.
+   Then add the written size to the writer size.
 
    On success, return ``0``.
    On error, set an exception and return ``-1``.
@@ -191,7 +194,8 @@ Low-level API
    pointer.
 
    The *buf* pointer is moved if the internal buffer is moved in memory.
-   The *buf* position inside the internal buffer is left unchanged.
+   The *buf* relative position within the internal buffer is left
+   unchanged.
 
    On error, set an exception and return ``NULL``.
 
@@ -330,7 +334,7 @@ Example of code using the soft deprecated
     if (result == NULL) {
         return NULL;
     }
-    if (safe_memcpy(PyBytes_AS_STRING(result), start, num_bytes) < 0) {
+    if (copy_bytes(PyBytes_AS_STRING(result), start, num_bytes) < 0) {
         Py_CLEAR(result);
     }
     return result;
@@ -341,7 +345,7 @@ It can now be updated to::
     if (writer == NULL) {
         return NULL;
     }
-    if (safe_memcpy(PyBytesWriter_GetData(writer), start, num_bytes) < 0) {
+    if (copy_bytes(PyBytesWriter_GetData(writer), start, num_bytes) < 0) {
         PyBytesWriter_Discard(writer);
         return NULL;
     }