https://github.com/python/cpython/commit/2ffa96d4a9e3accdb3ad9c8a1f85254468fe6581 commit: 2ffa96d4a9e3accdb3ad9c8a1f85254468fe6581 branch: 3.15 author: Miss Islington (bot) <[email protected]> committer: vstinner <[email protected]> date: 2026-10-10T19:55:19Z summary:
[3.15] gh-158585: Add 3 examples to PyBytesWriter documentation (GH-159129) (#159142) gh-158585: Add 3 examples to PyBytesWriter documentation (GH-159129) (cherry picked from commit 5eefa589f1339d51f9e536b87b036f4193c0769e) Co-authored-by: Victor Stinner <[email protected]> files: M Doc/c-api/bytes.rst diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index 688d7b6c32d9426..516e8b0bbfa856b 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -458,3 +458,112 @@ Low-level API return NULL; } return (char*)PyBytesWriter_GetData(writer) + pos; + + +Example creating the string ``b'abc'`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Example creating the bytes string ``b"abc"``, with a fixed size of 3 bytes:: + + PyObject* create_abc(void) + { + PyBytesWriter *writer = PyBytesWriter_Create(3); + if (writer == NULL) { + return NULL; + } + + char *str = PyBytesWriter_GetData(writer); + memcpy(str, "abc", 3); + return PyBytesWriter_Finish(writer); + } + +Variant using a pointer to compute the final size:: + + PyObject* create_abc_ptr(void) + { + PyBytesWriter *writer = PyBytesWriter_Create(3); + if (writer == NULL) { + return NULL; + } + + char *str = PyBytesWriter_GetData(writer); + memcpy(str, "abc", 3); + str += 1; + return PyBytesWriter_FinishWithPointer(writer, str); + } + + +Update ``PyBytes_FromStringAndSize()`` code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Example of code using the soft deprecated +``PyBytes_FromStringAndSize(NULL, size)`` API:: + + int copy_bytes(char *dest, const char *src, Py_ssize_t num_bytes) + { + ... + } + + PyObject* create_string(const char *start, Py_ssize_t num_bytes) + { + PyObject *result = PyBytes_FromStringAndSize(NULL, num_bytes); + if (result == NULL) { + return NULL; + } + if (copy_bytes(PyBytes_AS_STRING(result), start, num_bytes) < 0) { + Py_CLEAR(result); + } + return result; + } + +It can now be updated to:: + + PyObject* create_string(const char *start, Py_ssize_t num_bytes) + { + PyBytesWriter *writer = PyBytesWriter_Create(num_bytes); + if (writer == NULL) { + return NULL; + } + if (copy_bytes(PyBytesWriter_GetData(writer), start, num_bytes) < 0) { + PyBytesWriter_Discard(writer); + return NULL; + } + return PyBytesWriter_Finish(writer); + } + + +Update ``_PyBytes_Resize()`` code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Example of code using the soft deprecated ``_PyBytes_Resize()`` API:: + + void create_string(Py_ssize_t size) + { + PyObject *bytes = PyBytes_FromStringAndSize(NULL, size); + if (bytes == NULL) { + return NULL; + } + char *str = PyBytes_AS_STRING(bytes); + + // ... write data into str ... + + if (_PyBytes_Resize(&bytes, (str - PyBytes_AS_STRING(bytes)))) { + return NULL; + } + return bytes; + } + +It can now be updated to:: + + void create_string(Py_ssize_t size) + { + PyBytesWriter *writer = PyBytesWriter_Create(size); + if (writer == NULL) { + return NULL; + } + char *str = PyBytesWriter_GetData(writer); + + // ... write data into str ... + + return PyBytesWriter_FinishWithPointer(writer, str); + } _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
