From: Peter Bierma <zintensitydev@gmail.com>
Date: Mon, 20 Jan 2025 15:54:29 +0000 (-0500)
Subject: Docs C API: Clarify what happens when null bytes are passed to `PyUnicode_AsUTF8... 
X-Git-Tag: v3.14.0a5~344
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e792f4bc2e712bb6e2143599d2b88dd339de83e6;p=thirdparty%2FPython%2Fcpython.git

Docs C API: Clarify what happens when null bytes are passed to `PyUnicode_AsUTF8` (#127458)

Co-authored-by: Stan U. <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Tomas R. <tomas.roun8@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
---

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index f19b86a8dbfb..94110d48ed7d 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -1054,6 +1054,15 @@ These are the UTF-8 codec APIs:
 
    As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size.
 
+   .. warning::
+
+      This function does not have any special behavior for
+      `null characters <https://en.wikipedia.org/wiki/Null_character>`_ embedded within
+      *unicode*. As a result, strings containing null characters will remain in the returned
+      string, which some C functions might interpret as the end of the string, leading to
+      truncation. If truncation is an issue, it is recommended to use :c:func:`PyUnicode_AsUTF8AndSize`
+      instead.
+
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.7