Issue #13617: Document that the result of the conversion of a Unicode object to

wchar*, Py_UNICODE* and bytes may contain embedded null characters/bytes.

Patch written by Arnaud Calmettes.

diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index 81f7c466e08bec117a8a3ba6b7c96d75b1aa3e7e..70063c08fb551e10c87b60548eedd590a3b1367e 100644 (file)
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -33,6 +33,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Keith Briggs
    * Ian Bruntlett
    * Lee Busby
+   * Arnaud Calmettes
    * Lorenzo M. Catucci
    * Carl Cerecke
    * Mauro Cicognini

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index f48eb73bfd1bdc4f351098cd61daf6fa6bed46e9..35006547c6469020a91e42118a85daa7f62a22ff 100644 (file)
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -338,16 +338,21 @@ APIs:
 
 .. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
 
-   Return a read-only pointer to the Unicode object's internal :c:type:`Py_UNICODE`
-   buffer, *NULL* if *unicode* is not a Unicode object.
+   Return a read-only pointer to the Unicode object's internal
+   :c:type:`Py_UNICODE` buffer, *NULL* if *unicode* is not a Unicode object.
+   Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded
+   null characters, which would cause the string to be truncated when used in
+   most C functions.
 
 
 .. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
 
    Create a copy of a Unicode string ending with a nul character. Return *NULL*
    and raise a :exc:`MemoryError` exception on memory allocation failure,
-   otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free the
-   buffer).
+   otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free
+   the buffer). Note that the resulting :c:type:`Py_UNICODE*` string may contain
+   embedded null characters, which would cause the string to be truncated when
+   used in most C functions.
 
    .. versionadded:: 3.2
 
@@ -447,7 +452,8 @@ used, passing :c:func:`PyUnicode_FSDecoder` as the conversion function:
 
    Encode a Unicode object to :c:data:`Py_FileSystemDefaultEncoding` with the
    ``'surrogateescape'`` error handler, or ``'strict'`` on Windows, and return
-   :class:`bytes`.
+   :class:`bytes`. Note that the resulting :class:`bytes` object may contain
+   null bytes.
 
    If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
    locale encoding.
@@ -476,7 +482,9 @@ wchar_t Support
    copied or -1 in case of an error.  Note that the resulting :c:type:`wchar_t`
    string may or may not be 0-terminated.  It is the responsibility of the caller
    to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is
-   required by the application.
+   required by the application. Also, note that the :c:type:`wchar_t*` string
+   might contain null characters, which would cause the string to be truncated
+   when used with most C functions.
 
 
 .. c:function:: wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)
@@ -486,9 +494,11 @@ wchar_t Support
    of wide characters (excluding the trailing 0-termination character) into
    *\*size*.
 
-   Returns a buffer allocated by :c:func:`PyMem_Alloc` (use :c:func:`PyMem_Free`
-   to free it) on success. On error, returns *NULL*, *\*size* is undefined and
-   raises a :exc:`MemoryError`.
+   Returns a buffer allocated by :c:func:`PyMem_Alloc` (use
+   :c:func:`PyMem_Free` to free it) on success. On error, returns *NULL*,
+   *\*size* is undefined and raises a :exc:`MemoryError`. Note that the
+   resulting :c:type:`wchar_t*` string might contain null characters, which
+   would cause the string to be truncated when used with most C functions.
 
    .. versionadded:: 3.2