https://github.com/python/cpython/commit/5eefa589f1339d51f9e536b87b036f4193c0769e
commit: 5eefa589f1339d51f9e536b87b036f4193c0769e
branch: main
author: Victor Stinner <[email protected]>
committer: vstinner <[email protected]>
date: 2026-10-10T21:46:56+02:00
summary:
gh-158585: Add 3 examples to PyBytesWriter documentation (#159129)
files:
M Doc/c-api/bytes.rst
diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index fbdad0f346550de..1fcdf2ba5d983f3 100644
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -464,3 +464,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]
