changeset:   104746:15a494886c5a
branch:      3.6
parent:      104744:fe9f361f3751
user:        Serhiy Storchaka <storchaka@gmail.com>
date:        Thu Oct 27 21:05:49 2016 +0300
files:       Doc/whatsnew/3.6.rst Include/unicodeobject.h Misc/NEWS Objects/unicodeobject.c
description:
Issue #28426: Deprecated undocumented functions PyUnicode_AsEncodedObject(),
PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and
PyUnicode_AsEncodedUnicode().


diff -r fe9f361f3751 -r 15a494886c5a Doc/whatsnew/3.6.rst
--- a/Doc/whatsnew/3.6.rst	Thu Oct 27 19:33:05 2016 +0300
+++ b/Doc/whatsnew/3.6.rst	Thu Oct 27 21:05:49 2016 +0300
@@ -1230,7 +1230,10 @@
 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 -r fe9f361f3751 -r 15a494886c5a Include/unicodeobject.h
--- a/Include/unicodeobject.h	Thu Oct 27 19:33:05 2016 +0300
+++ b/Include/unicodeobject.h	Thu Oct 27 21:05:49 2016 +0300
@@ -1171,22 +1171,30 @@
     );
 
 /* 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 @@
 #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 @@
     );
 
 /* 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 -r fe9f361f3751 -r 15a494886c5a Misc/NEWS
--- a/Misc/NEWS	Thu Oct 27 19:33:05 2016 +0300
+++ b/Misc/NEWS	Thu Oct 27 21:05:49 2016 +0300
@@ -349,6 +349,13 @@
 
 - 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 -r fe9f361f3751 -r 15a494886c5a Objects/unicodeobject.c
--- a/Objects/unicodeobject.c	Thu Oct 27 19:33:05 2016 +0300
+++ b/Objects/unicodeobject.c	Thu Oct 27 21:05:49 2016 +0300
@@ -3241,6 +3241,11 @@
         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 @@
         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 @@
         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 @@
         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();