From cbaac31621cb912f7d791f9953b36a3f764b5fcc Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 22 Apr 2025 14:01:38 +0100 Subject: [PATCH 1/5] Schedule removal of functions --- Doc/deprecations/c-api-pending-removal-in-3.15.rst | 8 ++++++++ Doc/deprecations/c-api-pending-removal-in-future.rst | 8 -------- Include/unicodeobject.h | 12 ++++++++---- .../2025-04-22-13-59-30.gh-issue-132798.asfafhs.rst | 3 +++ Objects/unicodeobject.c | 12 ++++++++---- 5 files changed, 27 insertions(+), 16 deletions(-) create mode 100644 Misc/NEWS.d/next/C_API/2025-04-22-13-59-30.gh-issue-132798.asfafhs.rst 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 666a1622dd0b29..8c78336071b728 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,14 @@ 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. +* :c:func:`!PyUnicode_AsEncodedObject`: + Use :c:func:`PyCodec_Encode` instead. +* :c:func:`!PyUnicode_AsEncodedUnicode`: + Use :c:func:`PyCodec_Encode` instead. * 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 1003047344a3cc..841d1b455b6bec 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 2ce3a008b7129e..f8bcaecb98fb9c 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 00000000000000..d779d5a37e7209 --- /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 e01a10fc19e904..53c50734281db9 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; From 2336f07a05cf9467932ca9f3172de16b331598f3 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 22 Apr 2025 15:28:23 +0100 Subject: [PATCH 2/5] Add notes on return types --- Doc/deprecations/c-api-pending-removal-in-3.15.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 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 8c78336071b728..7c56f7b3d11409 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.15.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.15.rst @@ -11,13 +11,17 @@ Pending removal in Python 3.15 * :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. + Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") + may return a type other than :c:type:`str`, such as :c:type:`bytes`. * :c:func:`!PyUnicode_AsDecodedUnicode`: - Use :c:func:`PyCodec_Decode` instead. + Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") + may return a type other than :c:type:`str`, such as :c:type:`bytes`. * :c:func:`!PyUnicode_AsEncodedObject`: - Use :c:func:`PyCodec_Encode` instead. + Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") + may return a type other than :c:type:`str`, such as :c:type:`bytes`. * :c:func:`!PyUnicode_AsEncodedUnicode`: - Use :c:func:`PyCodec_Encode` instead. + Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") + may return a type other than :c:type:`str`, such as :c:type:`bytes`. * Python initialization functions, deprecated in Python 3.13: * :c:func:`Py_GetPath`: From 4740a083a094bb6189fcba280e84a9e21e8dece9 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 22 Apr 2025 16:04:04 +0100 Subject: [PATCH 3/5] Fix docs --- Doc/deprecations/c-api-pending-removal-in-3.15.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 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 7c56f7b3d11409..4b577db154ae5c 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.15.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.15.rst @@ -12,16 +12,16 @@ Pending removal in Python 3.15 Use :c:type:`wchar_t` instead. * :c:func:`!PyUnicode_AsDecodedObject`: Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") - may return a type other than :c:type:`str`, such as :c:type:`bytes`. + may return a type other than :class:`str`, such as :class:`bytes`. * :c:func:`!PyUnicode_AsDecodedUnicode`: Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") - may return a type other than :c:type:`str`, such as :c:type:`bytes`. + may return a type other than :class:`str`, such as :class:`bytes`. * :c:func:`!PyUnicode_AsEncodedObject`: Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") - may return a type other than :c:type:`str`, such as :c:type:`bytes`. + may return a type other than :class:`str`, such as :class:`bytes`. * :c:func:`!PyUnicode_AsEncodedUnicode`: Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") - may return a type other than :c:type:`str`, such as :c:type:`bytes`. + may return a type other than :class:`str`, such as :class:`bytes`. * Python initialization functions, deprecated in Python 3.13: * :c:func:`Py_GetPath`: From f75be1057b43101af5cda346ad310200090099ab Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 22 Apr 2025 16:14:22 +0100 Subject: [PATCH 4/5] Fixup --- Doc/deprecations/c-api-pending-removal-in-3.15.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 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 4b577db154ae5c..dccc0b24959bc5 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.15.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.15.rst @@ -11,14 +11,12 @@ Pending removal in Python 3.15 * :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; Note that some codecs (for example, "base64") - may return a type other than :class:`str`, such as :class:`bytes`. + 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_Decode` instead; Note that some codecs (for example, "base64") - may return a type other than :class:`str`, such as :class:`bytes`. + Use :c:func:`PyCodec_Decode` instead. * :c:func:`!PyUnicode_AsEncodedUnicode`: 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`. From 0db25d060b3fa50d1e0d30c35afb84d147e99b74 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 25 Apr 2025 12:16:48 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Victor Stinner --- Doc/deprecations/c-api-pending-removal-in-3.15.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 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 dccc0b24959bc5..a5cc8f1d5b3475 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.15.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.15.rst @@ -16,10 +16,10 @@ Pending removal in Python 3.15 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_Decode` instead. + Use :c:func:`PyCodec_Encode` instead. * :c:func:`!PyUnicode_AsEncodedUnicode`: - 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`. + 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`: