gh-128863: Deprecate the private _PyUnicodeWriter API

Deprecate private C API functions:

* _PyUnicodeWriter_Init()
* _PyUnicodeWriter_Finish()
* _PyUnicodeWriter_Dealloc()
* _PyUnicodeWriter_WriteChar()
* _PyUnicodeWriter_WriteStr()
* _PyUnicodeWriter_WriteSubstring()
* _PyUnicodeWriter_WriteASCIIString()
* _PyUnicodeWriter_WriteLatin1String()

These functions are not deprecated in the internal C API (if the
Py_BUILD_CORE macro is defined).

Author: vstinner

Doc/deprecations/c-api-pending-removal-in-3.18.rst

@@ -10,6 +10,14 @@ Pending removal in Python 3.18
   * :c:func:`!_PyLong_New`: use :c:func:`PyLongWriter_Create`.
   * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
   * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
+  * :c:func:`!_PyUnicodeWriter_Init`: use :c:func:`PyUnicodeWriter_Create`
+  * :c:func:`!_PyUnicodeWriter_Finish`: use :c:func:`PyUnicodeWriter_Finish`
+  * :c:func:`!_PyUnicodeWriter_Dealloc`: use :c:func:`PyUnicodeWriter_Discard`
+  * :c:func:`!_PyUnicodeWriter_WriteChar`: use :c:func:`PyUnicodeWriter_WriteChar`
+  * :c:func:`!_PyUnicodeWriter_WriteStr`: use :c:func:`PyUnicodeWriter_WriteStr`
+  * :c:func:`!_PyUnicodeWriter_WriteSubstring`: use :c:func:`PyUnicodeWriter_WriteSubstring`
+  * :c:func:`!_PyUnicodeWriter_WriteASCIIString`: use :c:func:`PyUnicodeWriter_WriteUTF8`
+  * :c:func:`!_PyUnicodeWriter_WriteLatin1String`: use :c:func:`PyUnicodeWriter_WriteUTF8`
   * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
   * :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.
 

Doc/whatsnew/3.14.rst

@@ -1399,6 +1399,14 @@ Deprecated
   * :c:func:`!_PyLong_New`: use :c:func:`PyLongWriter_Create`.
   * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
   * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
+  * :c:func:`!_PyUnicodeWriter_Init`: use :c:func:`PyUnicodeWriter_Create`
+  * :c:func:`!_PyUnicodeWriter_Finish`: use :c:func:`PyUnicodeWriter_Finish`
+  * :c:func:`!_PyUnicodeWriter_Dealloc`: use :c:func:`PyUnicodeWriter_Discard`
+  * :c:func:`!_PyUnicodeWriter_WriteChar`: use :c:func:`PyUnicodeWriter_WriteChar`
+  * :c:func:`!_PyUnicodeWriter_WriteStr`: use :c:func:`PyUnicodeWriter_WriteStr`
+  * :c:func:`!_PyUnicodeWriter_WriteSubstring`: use :c:func:`PyUnicodeWriter_WriteSubstring`
+  * :c:func:`!_PyUnicodeWriter_WriteASCIIString`: use :c:func:`PyUnicodeWriter_WriteUTF8`
+  * :c:func:`!_PyUnicodeWriter_WriteLatin1String`: use :c:func:`PyUnicodeWriter_WriteUTF8`
   * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
   * :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.
 

Include/cpython/unicodeobject.h

@@ -521,13 +521,19 @@ typedef struct {
     unsigned char readonly;
 } _PyUnicodeWriter;
 
+#ifndef Py_BUILD_CORE
+#  define _Py_PUBLIC_DEPRECATED(version) Py_DEPRECATED(version)
+#else
+#  define _Py_PUBLIC_DEPRECATED(version)
+#endif
+
 // Initialize a Unicode writer.
 //
 // By default, the minimum buffer size is 0 character and overallocation is
 // disabled. Set min_length, min_char and overallocate attributes to control
 // the allocation of the buffer.
-PyAPI_FUNC(void)
-_PyUnicodeWriter_Init(_PyUnicodeWriter *writer);
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(void) _PyUnicodeWriter_Init(
+    _PyUnicodeWriter *writer);
 
 /* Prepare the buffer to write 'length' characters
    with the specified maximum character.
@@ -543,9 +549,10 @@ _PyUnicodeWriter_Init(_PyUnicodeWriter *writer);
 
 /* Don't call this function directly, use the _PyUnicodeWriter_Prepare() macro
    instead. */
-PyAPI_FUNC(int)
-_PyUnicodeWriter_PrepareInternal(_PyUnicodeWriter *writer,
-                                 Py_ssize_t length, Py_UCS4 maxchar);
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(int) _PyUnicodeWriter_PrepareInternal(
+    _PyUnicodeWriter *writer,
+    Py_ssize_t length,
+    Py_UCS4 maxchar);
 
 /* Prepare the buffer to have at least the kind KIND.
    For example, kind=PyUnicode_2BYTE_KIND ensures that the writer will
@@ -559,58 +566,55 @@ _PyUnicodeWriter_PrepareInternal(_PyUnicodeWriter *writer,
 
 /* Don't call this function directly, use the _PyUnicodeWriter_PrepareKind()
    macro instead. */
-PyAPI_FUNC(int)
-_PyUnicodeWriter_PrepareKindInternal(_PyUnicodeWriter *writer,
-                                     int kind);
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(int) _PyUnicodeWriter_PrepareKindInternal(
+    _PyUnicodeWriter *writer,
+    int kind);
 
 /* Append a Unicode character.
    Return 0 on success, raise an exception and return -1 on error. */
-PyAPI_FUNC(int)
-_PyUnicodeWriter_WriteChar(_PyUnicodeWriter *writer,
-    Py_UCS4 ch
-    );
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(int) _PyUnicodeWriter_WriteChar(
+    _PyUnicodeWriter *writer,
+    Py_UCS4 ch);
 
 /* Append a Unicode string.
    Return 0 on success, raise an exception and return -1 on error. */
-PyAPI_FUNC(int)
-_PyUnicodeWriter_WriteStr(_PyUnicodeWriter *writer,
-    PyObject *str               /* Unicode string */
-    );
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(int) _PyUnicodeWriter_WriteStr(
+    _PyUnicodeWriter *writer,
+    PyObject *str);               /* Unicode string */
 
 /* Append a substring of a Unicode string.
    Return 0 on success, raise an exception and return -1 on error. */
-PyAPI_FUNC(int)
-_PyUnicodeWriter_WriteSubstring(_PyUnicodeWriter *writer,
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(int) _PyUnicodeWriter_WriteSubstring(
+    _PyUnicodeWriter *writer,
     PyObject *str,              /* Unicode string */
     Py_ssize_t start,
-    Py_ssize_t end
-    );
+    Py_ssize_t end);
 
 /* Append an ASCII-encoded byte string.
    Return 0 on success, raise an exception and return -1 on error. */
-PyAPI_FUNC(int)
-_PyUnicodeWriter_WriteASCIIString(_PyUnicodeWriter *writer,
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(int) _PyUnicodeWriter_WriteASCIIString(
+    _PyUnicodeWriter *writer,
     const char *str,           /* ASCII-encoded byte string */
-    Py_ssize_t len             /* number of bytes, or -1 if unknown */
-    );
+    Py_ssize_t len);           /* number of bytes, or -1 if unknown */
 
 /* Append a latin1-encoded byte string.
    Return 0 on success, raise an exception and return -1 on error. */
-PyAPI_FUNC(int)
-_PyUnicodeWriter_WriteLatin1String(_PyUnicodeWriter *writer,
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(int) _PyUnicodeWriter_WriteLatin1String(
+    _PyUnicodeWriter *writer,
     const char *str,           /* latin1-encoded byte string */
-    Py_ssize_t len             /* length in bytes */
-    );
+    Py_ssize_t len);           /* length in bytes */
 
 /* Get the value of the writer as a Unicode string. Clear the
    buffer of the writer. Raise an exception and return NULL
    on error. */
-PyAPI_FUNC(PyObject *)
-_PyUnicodeWriter_Finish(_PyUnicodeWriter *writer);
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(PyObject *) _PyUnicodeWriter_Finish(
+    _PyUnicodeWriter *writer);
 
 /* Deallocate memory of a writer (clear its internal buffer). */
-PyAPI_FUNC(void)
-_PyUnicodeWriter_Dealloc(_PyUnicodeWriter *writer);
+_Py_PUBLIC_DEPRECATED(3.14) PyAPI_FUNC(void) _PyUnicodeWriter_Dealloc(
+    _PyUnicodeWriter *writer);
+
+#undef _Py_PUBLIC_DEPRECATED
 
 
 /* --- Manage the default encoding ---------------------------------------- */

Misc/NEWS.d/next/C_API/2025-01-15-11-42-07.gh-issue-128863.C9MkB_.rst

@@ -8,6 +8,14 @@ Python 3.18:
 * :c:func:`!_PyLong_New`: use :c:func:`PyLongWriter_Create`.
 * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
 * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
+* :c:func:`!_PyUnicodeWriter_Init`: use :c:func:`PyUnicodeWriter_Create`
+* :c:func:`!_PyUnicodeWriter_Finish`: use :c:func:`PyUnicodeWriter_Finish`
+* :c:func:`!_PyUnicodeWriter_Dealloc`: use :c:func:`PyUnicodeWriter_Discard`
+* :c:func:`!_PyUnicodeWriter_WriteChar`: use :c:func:`PyUnicodeWriter_WriteChar`
+* :c:func:`!_PyUnicodeWriter_WriteStr`: use :c:func:`PyUnicodeWriter_WriteStr`
+* :c:func:`!_PyUnicodeWriter_WriteSubstring`: use :c:func:`PyUnicodeWriter_WriteSubstring`
+* :c:func:`!_PyUnicodeWriter_WriteASCIIString`: use :c:func:`PyUnicodeWriter_WriteUTF8`
+* :c:func:`!_PyUnicodeWriter_WriteLatin1String`: use :c:func:`PyUnicodeWriter_WriteUTF8`
 * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
 * :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.