https://github.com/python/cpython/commit/aebb4eab457ec42268a453a16f9b8b55245ad727
commit: aebb4eab457ec42268a453a16f9b8b55245ad727
branch: 3.13
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: encukou <encu...@gmail.com>
date: 2025-05-29T13:22:33Z
summary:
[3.13] gh-69011: : clarify & deduplicate `ctypes.create_*_buffer` docs
(GH-132858) (GH-134882)
This adds a warning about the possibly-missing NUL terminator, but in a way
that doesn't make it sound like a bug/wart.
(cherry picked from commit b783e1791b2076ef560104f8207156d75859c0a6)
Co-authored-by: Stan Ulbrych <89152624+stanfromirel...@users.noreply.github.com>
files:
M Doc/library/ctypes.rst
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index c06cbc314b40c4..648652b7352761 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1940,35 +1940,55 @@ Utility functions
pointer.
-.. function:: create_string_buffer(init_or_size, size=None)
+.. function:: create_string_buffer(init, size=None)
+ create_string_buffer(size)
This function creates a mutable character buffer. The returned object is a
ctypes array of :class:`c_char`.
- *init_or_size* must be an integer which specifies the size of the array, or
a
- bytes object which will be used to initialize the array items.
+ If *size* is given (and not ``None``), it must be an :class:`int`.
+ It specifies the size of the returned array.
- If a bytes object is specified as first argument, the buffer is made one
item
- larger than its length so that the last element in the array is a NUL
- termination character. An integer can be passed as second argument which
allows
- specifying the size of the array if the length of the bytes should not be
used.
+ If the *init* argument is given, it must be :class:`bytes`. It is used
+ to initialize the array items. Bytes not initialized this way are
+ set to zero (NUL).
+
+ If *size* is not given (or if it is ``None``), the buffer is made one
element
+ larger than *init*, effectively adding a NUL terminator.
+
+ If both arguments are given, *size* must not be less than ``len(init)``.
+
+ .. warning::
+
+ If *size* is equal to ``len(init)``, a NUL terminator is
+ not added. Do not treat such a buffer as a C string.
+
+ For example::
+
+ >>> bytes(create_string_buffer(2))
+ b'\x00\x00'
+ >>> bytes(create_string_buffer(b'ab'))
+ b'ab\x00'
+ >>> bytes(create_string_buffer(b'ab', 2))
+ b'ab'
+ >>> bytes(create_string_buffer(b'ab', 4))
+ b'ab\x00\x00'
+ >>> bytes(create_string_buffer(b'abcdef', 2))
+ Traceback (most recent call last):
+ ...
+ ValueError: byte string too long
.. audit-event:: ctypes.create_string_buffer init,size
ctypes.create_string_buffer
-.. function:: create_unicode_buffer(init_or_size, size=None)
+.. function:: create_unicode_buffer(init, size=None)
+ create_unicode_buffer(size)
This function creates a mutable unicode character buffer. The returned
object is
a ctypes array of :class:`c_wchar`.
- *init_or_size* must be an integer which specifies the size of the array, or
a
- string which will be used to initialize the array items.
-
- If a string is specified as first argument, the buffer is made one item
- larger than the length of the string so that the last element in the array
is a
- NUL termination character. An integer can be passed as second argument which
- allows specifying the size of the array if the length of the string should
not
- be used.
+ The function takes the same arguments as :func:`~create_string_buffer`
except
+ *init* must be a string and *size* counts :class:`c_wchar`.
.. audit-event:: ctypes.create_unicode_buffer init,size
ctypes.create_unicode_buffer
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: arch...@mail-archive.com
