From 751c2d0cf977e85317f06326c2ec84e410ba0c52 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 15 Oct 2025 13:45:51 +0200 Subject: [PATCH 1/4] gh-129813: Enhance PyBytesWriter documentation Mention if functions overallocate or not. --- Doc/c-api/bytes.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index 9bddfe4dce2f87..4494eec18ceda1 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -258,7 +258,7 @@ Create, Finish, Discard 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`. + bytes using :c:func:`PyBytesWriter_GetData`. Do not overallocate. On error, set an exception and return ``NULL``. @@ -348,7 +348,7 @@ Low-level API .. c:function:: int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size) Resize the writer to *size* bytes. It can be used to enlarge or to - shrink the writer. + shrink the writer. Overallocate the writer. Newly allocated bytes are left uninitialized. @@ -360,6 +360,7 @@ Low-level API .. c:function:: int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow) Resize the writer by adding *grow* bytes to the current writer size. + Overallocate the writer. Newly allocated bytes are left uninitialized. From 1a005289f1abc660cbb481ceb759dd75f30e6431 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 15 Oct 2025 14:26:48 +0200 Subject: [PATCH 2/4] Update Doc/c-api/bytes.rst Co-authored-by: Antoine Pitrou --- Doc/c-api/bytes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index 4494eec18ceda1..a3d903c6edb7b9 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -258,7 +258,7 @@ Create, Finish, Discard 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`. Do not overallocate. + bytes using :c:func:`PyBytesWriter_GetData`. This function does not overallocate. On error, set an exception and return ``NULL``. From e4ee5c8c3d987195c06aaf2c33a49db195f93c28 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 15 Oct 2025 14:26:57 +0200 Subject: [PATCH 3/4] Update Doc/c-api/bytes.rst Co-authored-by: Antoine Pitrou --- Doc/c-api/bytes.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index a3d903c6edb7b9..a2cb2022460cfc 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -348,7 +348,8 @@ Low-level API .. c:function:: int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size) Resize the writer to *size* bytes. It can be used to enlarge or to - shrink the writer. Overallocate the writer. + shrink the writer. This function typically overallocates to achieve + amortized performance when resizing multiple times. Newly allocated bytes are left uninitialized. From 3d397d1a87bb6295ef09d886f9a6312a00b0d865 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 15 Oct 2025 14:29:24 +0200 Subject: [PATCH 4/4] Apply Antoine's suggestion --- Doc/c-api/bytes.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index a2cb2022460cfc..865a9e5d2bf5d5 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -258,7 +258,8 @@ Create, Finish, Discard 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`. This function does not overallocate. + bytes using :c:func:`PyBytesWriter_GetData`. + This function does not overallocate. On error, set an exception and return ``NULL``. @@ -348,8 +349,9 @@ Low-level API .. c:function:: int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size) Resize the writer to *size* bytes. It can be used to enlarge or to - shrink the writer. This function typically overallocates to achieve - amortized performance when resizing multiple times. + shrink the writer. + This function typically overallocates to achieve amortized performance when + resizing multiple times. Newly allocated bytes are left uninitialized. @@ -361,7 +363,8 @@ Low-level API .. c:function:: int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow) Resize the writer by adding *grow* bytes to the current writer size. - Overallocate the writer. + This function typically overallocates to achieve amortized performance when + resizing multiple times. Newly allocated bytes are left uninitialized.