https://github.com/python/cpython/commit/2adc8b5f36edbcaae3fdd43fe3369342eee757d5
commit: 2adc8b5f36edbcaae3fdd43fe3369342eee757d5
branch: main
author: Petr Viktorin <[email protected]>
committer: encukou <[email protected]>
date: 2026-10-09T12:03:15+02:00
summary:
gh-157710: Move docs for mutating PyUnicode to new section (GH-159028)
files:
M Doc/c-api/unicode.rst
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 584732b05c811ff..4dbb5945ca6461d 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -154,29 +154,6 @@ access to internal read-only data of Unicode objects:
.. versionadded:: 3.3
-.. c:function:: void PyUnicode_WRITE(int kind, void *data, \
- Py_ssize_t index, Py_UCS4 value)
-
- Write the code point *value* to the given zero-based *index* in a string.
-
- The *kind* value and *data* pointer must have been obtained from a
- string using :c:func:`PyUnicode_KIND` and :c:func:`PyUnicode_DATA`
- respectively. You must hold a reference to that string while calling
- :c:func:`!PyUnicode_WRITE`. All requirements of
- :c:func:`PyUnicode_WriteChar` also apply.
-
- The function performs no checks for any of its requirements,
- and is intended for usage in loops.
-
- While :class:`str` objects are usually immutable in Python, this special C
API allows
- mutating a fresh :class:`str` object if the string has not been "used" yet.
-
- .. versionadded:: 3.3
-
- .. soft-deprecated:: next
- Use the :c:type:`PyUnicodeWriter` API instead.
-
-
.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)
Read a code point from a canonical representation *data* (as obtained with
@@ -385,44 +362,6 @@ Creating and accessing Unicode strings
To create Unicode objects and access their basic sequence properties, use these
APIs:
-.. c:function:: PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
-
- Create a new Unicode object. *maxchar* should be the true maximum code
point
- to be placed in the string. As an approximation, it can be rounded up to
the
- nearest value in the sequence 127, 255, 65535, 1114111.
-
- On error, set an exception and return ``NULL``.
-
- After creation, the string can be filled by :c:func:`PyUnicode_WriteChar`,
- :c:func:`PyUnicode_CopyCharacters`, :c:func:`PyUnicode_Fill`,
- :c:func:`PyUnicode_WRITE` or similar.
- Since strings are supposed to be immutable, take care to not “use” the
- result while it is being modified. In particular, before it's filled
- with its final contents, a string:
-
- - must not be hashed,
- - must not be :c:func:`converted to UTF-8 <PyUnicode_AsUTF8AndSize>`,
- or another non-"canonical" representation,
- - must not have its reference count changed,
- - must not be shared with code that might do one of the above.
-
- This list is not exhaustive. Avoiding these uses is your responsibility;
- Python does not always check these requirements.
-
- To avoid accidentally exposing a partially-written string object, prefer
- using the :c:type:`PyUnicodeWriter` API, or one of the ``PyUnicode_From*``
- functions below.
-
- While :class:`str` objects are usually immutable in Python, this special C
API
- returns a :class:`str` object that can be mutated, except if *size* is
zero, in which
- case it returns the immutable empty string constant.
-
- .. versionadded:: 3.3
-
- .. soft-deprecated:: next
- Use the :c:type:`PyUnicodeWriter` API instead.
-
-
.. c:function:: PyObject* PyUnicode_FromKindAndData(int kind, const void
*buffer, \
Py_ssize_t size)
@@ -755,96 +694,6 @@ APIs:
.. versionadded:: 3.3
-.. c:function:: Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, \
- Py_ssize_t to_start, \
- PyObject *from, \
- Py_ssize_t from_start, \
- Py_ssize_t how_many)
-
- Copy characters from one Unicode object into another. This function
performs
- character conversion when necessary and falls back to :c:func:`!memcpy` if
- possible. Returns ``-1`` and sets an exception on error, otherwise returns
- the number of copied characters.
-
- While :class:`str` objects are usually immutable in Python, this special C
API allows
- mutating a fresh :class:`str` object if the string has not been "used" yet.
-
- See :c:func:`PyUnicode_New` for details.
-
- .. versionadded:: 3.3
-
- .. soft-deprecated:: next
- Use the :c:type:`PyUnicodeWriter` API instead.
-
-
-.. c:function:: int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);
-
- Resize a Unicode object *\*unicode* to the new *length* in code points.
-
- Try to resize the string in place (which is usually faster than allocating
- a new string and copying characters), or create a new string.
-
- *\*unicode* is modified to point to the new (resized) object and ``0`` is
- returned on success. Otherwise, ``-1`` is returned and an exception is set,
- and *\*unicode* is left untouched.
-
- The function doesn't check string content, the result may not be a
- string in canonical representation.
-
- While :class:`str` objects are usually immutable in Python, this special C
API
- can resize a :class:`str` object in-place if the string has not been "used"
yet.
- It returns a :class:`str` object which can be mutated, except if *size* is
zero, in
- which case it returns the immutable empty string constant.
-
- .. soft-deprecated:: next
- Use the :c:type:`PyUnicodeWriter` API instead.
-
-
-.. c:function:: Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start,
\
- Py_ssize_t length, Py_UCS4 fill_char)
-
- Fill a string with a character: write *fill_char* into
- ``unicode[start:start+length]``.
-
- Fail if *fill_char* is bigger than the string maximum character, or if the
- string has more than 1 reference.
-
- Return the number of written characters, or return ``-1`` and raise an
- exception on error.
-
- While :class:`str` objects are usually immutable in Python, this special C
API allows
- mutating a fresh :class:`str` object if the string has not been "used" yet.
-
- See :c:func:`PyUnicode_New` for details.
-
- .. versionadded:: 3.3
-
- .. soft-deprecated:: next
- Use the :c:type:`PyUnicodeWriter` API instead.
-
-
-.. c:function:: int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, \
- Py_UCS4 character)
-
- Write a *character* to the string *unicode* at the zero-based *index*.
- Return ``0`` on success, ``-1`` on error with an exception set.
-
- This function checks that *unicode* is a Unicode object, that the index is
- not out of bounds, and that the object's reference count is one.
- See :c:func:`PyUnicode_WRITE` for a version that skips these checks,
- making them your responsibility.
-
- While :class:`str` objects are usually immutable in Python, this special C
API allows
- mutating a fresh :class:`str` object if the string has not been "used" yet.
-
- See :c:func:`PyUnicode_New` for details.
-
- .. versionadded:: 3.3
-
- .. soft-deprecated:: next
- Use the :c:type:`PyUnicodeWriter` API instead.
-
-
.. c:function:: Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)
Read a character from a string. This function checks that *unicode* is a
@@ -2053,3 +1902,153 @@ The following API is deprecated.
This API does nothing since Python 3.12.
Previously, this could be called to check if
:c:func:`PyUnicode_READY` is necessary.
+
+
+.. _pyunicode-new-mutating:
+
+Mutating string objects
+"""""""""""""""""""""""
+
+The following functions allow creating a blank string object of a given size,
+then filling in its contents.
+They are :term:`soft deprecated`: they break the assumption that
+strings are immutable, making them hard to use correctly.
+
+Prefer using the :c:type:`PyUnicodeWriter` API,
+or one of the ``PyUnicode_From*``
+functions such as :c:func:`PyUnicode_FromStringAndSize`.
+
+If you do use the functions below, take care to not "use" such a string while
+it is being modified.
+In particular, before it's filled with its final contents, a string:
+
+- must not be hashed,
+- must not be :c:func:`converted to UTF-8 <PyUnicode_AsUTF8AndSize>`,
+ or another non-"canonical" representation,
+- must not have its reference count changed,
+- must not be accessed from another thread,
+- must not be shared with code that might do one of the above.
+
+This list is not exhaustive. Avoiding these uses is your responsibility;
+Python does not always check these requirements.
+
+
+.. c:function:: PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
+
+ Create a new Unicode object. *maxchar* should be the true maximum code
point
+ to be placed in the string. As an approximation, it can be rounded up to
the
+ nearest value in the sequence 127, 255, 65535, 1114111.
+
+ On error, set an exception and return ``NULL``.
+
+ See :ref:`pyunicode-new-mutating` for important warnings and caveats.
+
+ .. versionadded:: 3.3
+
+ .. soft-deprecated:: next
+ See :ref:`pyunicode-new-mutating`.
+
+
+.. c:function:: void PyUnicode_WRITE(int kind, void *data, \
+ Py_ssize_t index, Py_UCS4 value)
+
+ Write the code point *value* to the given zero-based *index* in a string.
+
+ The *kind* value and *data* pointer must have been obtained from a
+ string using :c:func:`PyUnicode_KIND` and :c:func:`PyUnicode_DATA`
+ respectively. You must hold a reference to that string while calling
+ :c:func:`!PyUnicode_WRITE`. All requirements of
+ :c:func:`PyUnicode_WriteChar` also apply.
+
+ The function performs no checks for any of its requirements,
+ and is intended for usage in loops.
+
+ The owning string must not be "used" yet.
+ See :ref:`pyunicode-new-mutating` for details.
+
+ .. versionadded:: 3.3
+
+ .. soft-deprecated:: next
+ Use the :c:type:`PyUnicodeWriter` API instead.
+
+
+.. c:function:: Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, \
+ Py_ssize_t to_start, \
+ PyObject *from, \
+ Py_ssize_t from_start, \
+ Py_ssize_t how_many)
+
+ Copy characters from one Unicode object into another. This function
performs
+ character conversion when necessary and falls back to :c:func:`!memcpy` if
+ possible. Returns ``-1`` and sets an exception on error, otherwise returns
+ the number of copied characters.
+
+ The destination string must not be "used" yet.
+ See :ref:`pyunicode-new-mutating` for details.
+
+ .. versionadded:: 3.3
+
+ .. soft-deprecated:: next
+ Use the :c:type:`PyUnicodeWriter` API instead.
+
+
+.. c:function:: int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);
+
+ Resize a Unicode object *\*unicode* to the new *length* in code points.
+
+ Try to resize the string in place (which is usually faster than allocating
+ a new string and copying characters), or create a new string.
+
+ *\*unicode* is modified to point to the new (resized) object and ``0`` is
+ returned on success. Otherwise, ``-1`` is returned and an exception is set,
+ and *\*unicode* is left untouched.
+
+ The function doesn't check string content, the result may not be a
+ string in canonical representation.
+
+ *\*unicode* must not be "used" yet.
+ See :ref:`pyunicode-new-mutating` for details.
+
+ .. soft-deprecated:: next
+ Use the :c:type:`PyUnicodeWriter` API instead.
+
+
+.. c:function:: Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start,
\
+ Py_ssize_t length, Py_UCS4 fill_char)
+
+ Fill a string with a character: write *fill_char* into
+ ``unicode[start:start+length]``.
+
+ Fail if *fill_char* is bigger than the string maximum character, or if the
+ string has more than 1 reference.
+
+ Return the number of written characters, or return ``-1`` and raise an
+ exception on error.
+
+ *unicode* must not be "used" yet.
+ See :ref:`pyunicode-new-mutating` for details.
+
+ .. versionadded:: 3.3
+
+ .. soft-deprecated:: next
+ Use the :c:type:`PyUnicodeWriter` API instead.
+
+
+.. c:function:: int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, \
+ Py_UCS4 character)
+
+ Write a *character* to the string *unicode* at the zero-based *index*.
+ Return ``0`` on success, ``-1`` on error with an exception set.
+
+ This function checks that *unicode* is a Unicode object, that the index is
+ not out of bounds, and that the object's reference count is one.
+ See :c:func:`PyUnicode_WRITE` for a version that skips these checks,
+ making them your responsibility.
+
+ *unicode* must not be "used" yet.
+ See :ref:`pyunicode-new-mutating` for details.
+
+ .. versionadded:: 3.3
+
+ .. soft-deprecated:: next
+ Use the :c:type:`PyUnicodeWriter` API instead.
_______________________________________________
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]
