https://github.com/python/cpython/commit/b783e1791b2076ef560104f8207156d75859c0a6
commit: b783e1791b2076ef560104f8207156d75859c0a6
branch: main
author: Stan Ulbrych <[email protected]>
committer: encukou <[email protected]>
date: 2025-05-29T15:16:20+02:00
summary:
gh-69011: : clarify & deduplicate `ctypes.create_*_buffer` docs (GH-132858)
This adds a warning about the possibly-missing NUL terminator, but in a way
that doesn't make it sound like a bug/wart.
files:
M Doc/library/ctypes.rst
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 5b733d5321e907..8e74c6c9dee744 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -2031,35 +2031,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 -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
