Issue #28426: Deprecated undocumented functions PyUnicode_AsEncodedObject(),

PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and
PyUnicode_AsEncodedUnicode().

diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index b7c857445c0dc6c824ac0929ec9a48c6d9d3da2b..e88d618adbdd598e75fb4340010134b8dde3f568 100644 (file)
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -1230,7 +1230,10 @@ Deprecated Python modules, functions and methods
 Deprecated functions and types of the C API
 -------------------------------------------
 
-* None yet.
+* Undocumented functions :c:func:`PyUnicode_AsEncodedObject`,
+  :c:func:`PyUnicode_AsDecodedObject`, :c:func:`PyUnicode_AsEncodedUnicode`
+  and :c:func:`PyUnicode_AsDecodedUnicode` are deprecated now.
+  Use :ref:`generic codec based API <codec-registry>` instead.
 
 
 Deprecated features

diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
index 643d10d2741d08679f3568e08b12faeb2e55a201..5711de0164eacad23e75dcbcf37defd9f32f4a24 100644 (file)
--- a/Include/unicodeobject.h
+++ b/Include/unicodeobject.h
@@ -1171,22 +1171,30 @@ PyAPI_FUNC(PyObject*) PyUnicode_Decode(
     );
 
 /* Decode a Unicode object unicode and return the result as Python
-   object. */
+   object.
+
+   This API is DEPRECATED. The only supported standard encoding is rot13.
+   Use PyCodec_Decode() to decode with rot13 and non-standard codecs
+   that decode from str. */
 
 PyAPI_FUNC(PyObject*) PyUnicode_AsDecodedObject(
     PyObject *unicode,          /* Unicode object */
     const char *encoding,       /* encoding */
     const char *errors          /* error handling */
-    );
+    ) Py_DEPRECATED(3.6);
 
 /* Decode a Unicode object unicode and return the result as Unicode
-   object. */
+   object.
+
+   This API is DEPRECATED. The only supported standard encoding is rot13.
+   Use PyCodec_Decode() to decode with rot13 and non-standard codecs
+   that decode from str to str. */
 
 PyAPI_FUNC(PyObject*) PyUnicode_AsDecodedUnicode(
     PyObject *unicode,          /* Unicode object */
     const char *encoding,       /* encoding */
     const char *errors          /* error handling */
-    );
+    ) Py_DEPRECATED(3.6);
 
 /* Encodes a Py_UNICODE buffer of the given size and returns a
    Python string object. */
@@ -1201,13 +1209,18 @@ PyAPI_FUNC(PyObject*) PyUnicode_Encode(
 #endif
 
 /* Encodes a Unicode object and returns the result as Python
-   object. */
+   object.
+
+   This API is DEPRECATED.  It is superceeded 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. */
 
 PyAPI_FUNC(PyObject*) PyUnicode_AsEncodedObject(
     PyObject *unicode,          /* Unicode object */
     const char *encoding,       /* encoding */
     const char *errors          /* error handling */
-    );
+    ) Py_DEPRECATED(3.6);
 
 /* Encodes a Unicode object and returns the result as Python string
    object. */
@@ -1219,13 +1232,17 @@ PyAPI_FUNC(PyObject*) PyUnicode_AsEncodedString(
     );
 
 /* Encodes a Unicode object and returns the result as Unicode
-   object. */
+   object.
+
+   This API is DEPRECATED.  The only supported standard encodings is rot13.
+   Use PyCodec_Encode() to encode with rot13 and non-standard codecs
+   that encode from str to str. */
 
 PyAPI_FUNC(PyObject*) PyUnicode_AsEncodedUnicode(
     PyObject *unicode,          /* Unicode object */
     const char *encoding,       /* encoding */
     const char *errors          /* error handling */
-    );
+    ) Py_DEPRECATED(3.6);
 
 /* Build an encoding map. */
 

diff --git a/Misc/NEWS b/Misc/NEWS
index a6b340f4d599cf4cc701d73794497f8cb9c08532..86650814dfa8359adf36de549b98b6d532907151 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -349,6 +349,13 @@ Windows
 
 - Issue #28138: Windows ._pth file should allow import site
 
+C API
+-----
+
+- Issue #28426: Deprecated undocumented functions PyUnicode_AsEncodedObject(),
+  PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and
+  PyUnicode_AsEncodedUnicode().
+
 Build
 -----
 

diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index 6cf5cb2a41fb384d6cab284b7b35d584e34b3908..e45f3d7c27b923c05d167860e0cc92ea5f23a6a3 100644 (file)
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -3241,6 +3241,11 @@ PyUnicode_AsDecodedObject(PyObject *unicode,
         return NULL;
     }
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "PyUnicode_AsDecodedObject() is deprecated; "
+                     "use PyCodec_Decode() to decode from str", 1) < 0)
+        return NULL;
+
     if (encoding == NULL)
         encoding = PyUnicode_GetDefaultEncoding();
 
@@ -3260,6 +3265,11 @@ PyUnicode_AsDecodedUnicode(PyObject *unicode,
         goto onError;
     }
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "PyUnicode_AsDecodedUnicode() is deprecated; "
+                     "use PyCodec_Decode() to decode from str to str", 1) < 0)
+        return NULL;
+
     if (encoding == NULL)
         encoding = PyUnicode_GetDefaultEncoding();
 
@@ -3310,6 +3320,12 @@ PyUnicode_AsEncodedObject(PyObject *unicode,
         goto onError;
     }
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "PyUnicode_AsEncodedObject() is deprecated; "
+                     "use PyUnicode_AsEncodedString() to encode from str to bytes "
+                     "or PyCodec_Encode() for generic encoding", 1) < 0)
+        return NULL;
+
     if (encoding == NULL)
         encoding = PyUnicode_GetDefaultEncoding();
 
@@ -3635,6 +3651,11 @@ PyUnicode_AsEncodedUnicode(PyObject *unicode,
         goto onError;
     }
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "PyUnicode_AsEncodedUnicode() is deprecated; "
+                     "use PyCodec_Encode() to encode from str to str", 1) < 0)
+        return NULL;
+
     if (encoding == NULL)
         encoding = PyUnicode_GetDefaultEncoding();