mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-10 11:00:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

Issue #15984: Correct PyUnicode_FromObject() and _FromEncodedObject() docs

Browse source
This commit is contained in:
Martin Panter 2016-04-15 00:56:21 +00:00
parent 6245cb3c01
commit 20d325574e
2 changed files with 15 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

12
Doc/c-api/unicode.rst
View file

@ -556,14 +556,13 @@ APIs:
.. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, \ .. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, \
const char *encoding, const char *errors) const char *encoding, const char *errors)
Coerce an encoded object *obj* to a Unicode object and return a reference with Decode an encoded object *obj* to a Unicode object.
incremented refcount.
:class:`bytes`, :class:`bytearray` and other :class:`bytes`, :class:`bytearray` and other
:term:`bytes-like objects <bytes-like object>` :term:`bytes-like objects <bytes-like object>`
are decoded according to the given *encoding* and using the error handling 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 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 All other objects, including Unicode objects, cause a :exc:`TypeError` to be
set. set.
@ -745,8 +744,11 @@ Extension modules can continue using them, as they will not be removed in Python
.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj) .. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used Copy an instance of a Unicode subtype to a new true Unicode object if
throughout the interpreter whenever coercion to Unicode is needed. 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 Locale Encoding

24
Include/unicodeobject.h
View file

@ -844,17 +844,13 @@ PyAPI_FUNC(int) PyUnicode_Resize(
Py_ssize_t length /* New length */ Py_ssize_t length /* New length */
); );
/* Coerce obj to a Unicode object and return a reference with /* Decode obj to an Unicode object.
*incremented* refcount.
Coercion is done in the following way: 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".
1. bytes, bytearray and other bytes-like objects are decoded All other objects (including Unicode objects) raise an exception.
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.
The API returns NULL in case of an error. The caller is responsible The API returns NULL in case of an error. The caller is responsible
for decref'ing the returned objects. for decref'ing the returned objects.
@ -867,13 +863,9 @@ PyAPI_FUNC(PyObject*) PyUnicode_FromEncodedObject(
const char *errors /* error handling */ const char *errors /* error handling */
); );
/* Coerce obj to a Unicode object and return a reference with /* Copy an instance of a Unicode subtype to a new true Unicode object if
*incremented* refcount. necessary. If obj is already a true Unicode object (not a subtype), return
the 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.
The API returns NULL in case of an error. The caller is responsible The API returns NULL in case of an error. The caller is responsible
for decref'ing the returned objects. for decref'ing the returned objects.