[Python-checkins] cpython (3.5): Issue #15984: Correct PyUnicode_FromObject() and _FromEncodedObject() docs

Thu Apr 14 23:35:26 EDT 2016

https://hg.python.org/cpython/rev/af655e73f7bd
changeset: 100979:af655e73f7bd
branch: 3.5
user: Martin Panter <vadmium+py at gmail.com>
date: Fri Apr 15 00:56:21 2016 +0000
summary:
 Issue #15984: Correct PyUnicode_FromObject() and _FromEncodedObject() docs
files:
 Doc/c-api/unicode.rst | 12 +++++++-----
 Include/unicodeobject.h | 28 ++++++++++------------------
 2 files changed, 17 insertions(+), 23 deletions(-)

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -556,14 +556,13 @@
 .. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, \
 const char *encoding, const char *errors)
 
- Coerce an encoded object *obj* to a Unicode object and return a reference with
- incremented refcount.
+ Decode an encoded object *obj* to a Unicode object.
 
 :class:`bytes`, :class:`bytearray` and other
 :term:`bytes-like objects <bytes-like object>`
 are decoded according to the given *encoding* and using the error handling
 defined by *errors*. Both can be *NULL* to have the interface use the default
- values (see the next section for details).
+ values (see :ref:`builtincodecs` for details).
 
 All other objects, including Unicode objects, cause a :exc:`TypeError` to be
 set.
@@ -745,8 +744,11 @@
 
 .. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
 
- Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
- throughout the interpreter whenever coercion to Unicode is needed.
+ Copy an instance of a Unicode subtype to a new true Unicode object if
+ necessary. If *obj* is already a true Unicode object (not a subtype),
+ return the reference with incremented refcount.
+
+ Objects other than Unicode or its subtypes will cause a :exc:`TypeError`.
 
 
 Locale Encoding
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
--- a/Include/unicodeobject.h
+++ b/Include/unicodeobject.h
@@ -844,17 +844,13 @@
 Py_ssize_t length /* New length */
 );
 
-/* Coerce obj to a Unicode object and return a reference with
- *incremented* refcount.
-
- Coercion is done in the following way:
-
- 1. bytes, bytearray and other bytes-like objects are decoded
- under the assumptions that they contain data using the UTF-8
- encoding. Decoding is done in "strict" mode.
-
- 2. All other objects (including Unicode objects) raise an
- exception.
+/* Decode obj to an Unicode object.
+
+ bytes, bytearray and other bytes-like objects are decoded according to the
+ given encoding and error handler. The encoding and error handler can be
+ NULL to have the interface use UTF-8 and "strict".
+
+ All other objects (including Unicode objects) raise an exception.
 
 The API returns NULL in case of an error. The caller is responsible
 for decref'ing the returned objects.
@@ -867,13 +863,9 @@
 const char *errors /* error handling */
 );
 
-/* Coerce obj to a Unicode object and return a reference with
- *incremented* refcount.
-
- Unicode objects are passed back as-is (subclasses are converted to
- true Unicode objects), all other objects are delegated to
- PyUnicode_FromEncodedObject(obj, NULL, "strict") which results in
- using UTF-8 encoding as basis for decoding the object.
+/* Copy an instance of a Unicode subtype to a new true Unicode object if
+ necessary. If obj is already a true Unicode object (not a subtype), return
+ the reference with *incremented* refcount.
 
 The API returns NULL in case of an error. The caller is responsible
 for decref'ing the returned objects.
-- 
Repository URL: https://hg.python.org/cpython
