From: Victor Stinner <vstinner@python.org>
Date: Thu, 5 Dec 2024 09:37:14 +0000 (+0100)
Subject: gh-119182: Complete PyUnicodeWriter documentation (#127607)
X-Git-Tag: v3.14.0a3~116
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1ef6e8ca3faf2c2b008fb170c7c44c38b86e874a;p=thirdparty%2FPython%2Fcpython.git

gh-119182: Complete PyUnicodeWriter documentation (#127607)
---

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 59bd7661965d..dcbc8804cd6b 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -1588,6 +1588,11 @@ object.
 
    Create a Unicode writer instance.
 
+   *length* must be greater than or equal to ``0``.
+
+   If *length* is greater than ``0``, preallocate an internal buffer of
+   *length* characters.
+
    Set an exception and return ``NULL`` on error.
 
 .. c:function:: PyObject* PyUnicodeWriter_Finish(PyUnicodeWriter *writer)
@@ -1596,12 +1601,16 @@ object.
 
    Set an exception and return ``NULL`` on error.
 
+   The writer instance is invalid after this call.
+
 .. c:function:: void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)
 
    Discard the internal Unicode buffer and destroy the writer instance.
 
    If *writer* is ``NULL``, no operation is performed.
 
+   The writer instance is invalid after this call.
+
 .. c:function:: int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)
 
    Write the single Unicode character *ch* into *writer*.