gh-132798: Schedule removal of `PyUnicode_AsDecoded/Encoded` functions for 3.15 (#132799)

Co-authored-by: Victor Stinner <vstinner@python.org>

5 files changed, 29 insertions, 16 deletions

diff --git a/Doc/deprecations/c-api-pending-removal-in-3.15.rst b/Doc/deprecations/c-api-pending-removal-in-3.15.rst
index 666a1622dd0..a5cc8f1d5b3 100644
--- a/Doc/deprecations/c-api-pending-removal-in-3.15.rst
+++ b/Doc/deprecations/c-api-pending-removal-in-3.15.rst
@@ -10,6 +10,16 @@ Pending removal in Python 3.15
   :c:func:`PyWeakref_GetRef` on Python 3.12 and older.
 * :c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro:
   Use :c:type:`wchar_t` instead.
+* :c:func:`!PyUnicode_AsDecodedObject`:
+  Use :c:func:`PyCodec_Decode` instead.
+* :c:func:`!PyUnicode_AsDecodedUnicode`:
+  Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64")
+  may return a type other than :class:`str`, such as :class:`bytes`.
+* :c:func:`!PyUnicode_AsEncodedObject`:
+  Use :c:func:`PyCodec_Encode` instead.
+* :c:func:`!PyUnicode_AsEncodedUnicode`:
+  Use :c:func:`PyCodec_Encode` instead; Note that some codecs (for example, "base64")
+  may return a type other than :class:`bytes`, such as :class:`str`.
 * Python initialization functions, deprecated in Python 3.13:
 
   * :c:func:`Py_GetPath`:
diff --git a/Doc/deprecations/c-api-pending-removal-in-future.rst b/Doc/deprecations/c-api-pending-removal-in-future.rst
index 1003047344a..841d1b455b6 100644
--- a/Doc/deprecations/c-api-pending-removal-in-future.rst
+++ b/Doc/deprecations/c-api-pending-removal-in-future.rst
@@ -18,14 +18,6 @@ although there is currently no date scheduled for their removal.
   Use :c:func:`PyOS_AfterFork_Child` instead.
 * :c:func:`PySlice_GetIndicesEx`:
   Use :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` instead.
-* :c:func:`!PyUnicode_AsDecodedObject`:
-  Use :c:func:`PyCodec_Decode` instead.
-* :c:func:`!PyUnicode_AsDecodedUnicode`:
-  Use :c:func:`PyCodec_Decode` instead.
-* :c:func:`!PyUnicode_AsEncodedObject`:
-  Use :c:func:`PyCodec_Encode` instead.
-* :c:func:`!PyUnicode_AsEncodedUnicode`:
-  Use :c:func:`PyCodec_Encode` instead.
 * :c:func:`PyUnicode_READY`:
   Unneeded since Python 3.12
 * :c:func:`!PyErr_Display`:
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
index 2ce3a008b71..f8bcaecb98f 100644
--- a/Include/unicodeobject.h
+++ b/Include/unicodeobject.h
@@ -344,7 +344,8 @@ PyAPI_FUNC(PyObject*) PyUnicode_Decode(
 /* Decode a Unicode object unicode and return the result as Python
    object.
 
-   This API is DEPRECATED. The only supported standard encoding is rot13.
+   This API is DEPRECATED and will be removed in 3.15.
+   The only supported standard encoding is rot13.
    Use PyCodec_Decode() to decode with rot13 and non-standard codecs
    that decode from str. */
 
@@ -357,7 +358,8 @@ Py_DEPRECATED(3.6) PyAPI_FUNC(PyObject*) PyUnicode_AsDecodedObject(
 /* Decode a Unicode object unicode and return the result as Unicode
    object.
 
-   This API is DEPRECATED. The only supported standard encoding is rot13.
+   This API is DEPRECATED and will be removed in 3.15.
+   The only supported standard encoding is rot13.
    Use PyCodec_Decode() to decode with rot13 and non-standard codecs
    that decode from str to str. */
 
@@ -370,7 +372,8 @@ Py_DEPRECATED(3.6) PyAPI_FUNC(PyObject*) PyUnicode_AsDecodedUnicode(
 /* Encodes a Unicode object and returns the result as Python
    object.
 
-   This API is DEPRECATED.  It is superseded by PyUnicode_AsEncodedString()
+   This API is DEPRECATED and will be removed in 3.15.
+   It is superseded by PyUnicode_AsEncodedString()
    since all standard encodings (except rot13) encode str to bytes.
    Use PyCodec_Encode() for encoding with rot13 and non-standard codecs
    that encode form str to non-bytes. */
@@ -393,7 +396,8 @@ PyAPI_FUNC(PyObject*) PyUnicode_AsEncodedString(
 /* Encodes a Unicode object and returns the result as Unicode
    object.
 
-   This API is DEPRECATED.  The only supported standard encodings is rot13.
+   This API is DEPRECATED and will be removed in 3.15.
+   The only supported standard encodings is rot13.
    Use PyCodec_Encode() to encode with rot13 and non-standard codecs
    that encode from str to str. */
 
diff --git a/Misc/NEWS.d/next/C_API/2025-04-22-13-59-30.gh-issue-132798.asfafhs.rst b/Misc/NEWS.d/next/C_API/2025-04-22-13-59-30.gh-issue-132798.asfafhs.rst
new file mode 100644
index 00000000000..d779d5a37e7
--- /dev/null
+++ b/Misc/NEWS.d/next/C_API/2025-04-22-13-59-30.gh-issue-132798.asfafhs.rst
@@ -0,0 +1,3 @@
+Deprecated and undocumented functions :c:func:`!PyUnicode_AsEncodedObject`,
+:c:func:`!PyUnicode_AsDecodedObject`, :c:func:`!PyUnicode_AsEncodedUnicode`
+and :c:func:`!PyUnicode_AsDecodedUnicode` are scheduled for removal in 3.15.
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index e01a10fc19e..53c50734281 100644
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -3733,7 +3733,8 @@ PyUnicode_AsDecodedObject(PyObject *unicode,
     }
 
     if (PyErr_WarnEx(PyExc_DeprecationWarning,
-                     "PyUnicode_AsDecodedObject() is deprecated; "
+                     "PyUnicode_AsDecodedObject() is deprecated "
+                     "and will be removed in 3.15; "
                      "use PyCodec_Decode() to decode from str", 1) < 0)
         return NULL;
 
@@ -3757,7 +3758,8 @@ PyUnicode_AsDecodedUnicode(PyObject *unicode,
     }
 
     if (PyErr_WarnEx(PyExc_DeprecationWarning,
-                     "PyUnicode_AsDecodedUnicode() is deprecated; "
+                     "PyUnicode_AsDecodedUnicode() is deprecated "
+                     "and will be removed in 3.15; "
                      "use PyCodec_Decode() to decode from str to str", 1) < 0)
         return NULL;
 
@@ -3796,7 +3798,8 @@ PyUnicode_AsEncodedObject(PyObject *unicode,
     }
 
     if (PyErr_WarnEx(PyExc_DeprecationWarning,
-                     "PyUnicode_AsEncodedObject() is deprecated; "
+                     "PyUnicode_AsEncodedObject() is deprecated "
+                     "and will be removed in 3.15; "
                      "use PyUnicode_AsEncodedString() to encode from str to bytes "
                      "or PyCodec_Encode() for generic encoding", 1) < 0)
         return NULL;
@@ -4019,7 +4022,8 @@ PyUnicode_AsEncodedUnicode(PyObject *unicode,
     }
 
     if (PyErr_WarnEx(PyExc_DeprecationWarning,
-                     "PyUnicode_AsEncodedUnicode() is deprecated; "
+                     "PyUnicode_AsEncodedUnicode() is deprecated "
+                     "and will be removed in 3.15; "
                      "use PyCodec_Encode() to encode from str to str", 1) < 0)
         return NULL;