Add C-API documentation for PyUnicode_AsDecodedObject/Unicode and PyUnicode_AsEncodedObject/Unicode

[vstinner]

BPO	9076
Nosy	@malemburg, @birkenfeld, @vstinner
Superseder	bpo-10435: Document unicode C-API in reST
Files	remove_unicode_codec.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2010-11-16.16:31:41.912>
created_at = <Date 2010-06-24.23:28:49.674>
labels = ['docs']
title = 'Add C-API documentation for PyUnicode_AsDecodedObject/Unicode and PyUnicode_AsEncodedObject/Unicode'
updated_at = <Date 2010-11-16.16:31:41.910>
user = 'https://github.com/vstinner'

bugs.python.org fields:

activity = <Date 2010-11-16.16:31:41.910>
actor = 'georg.brandl'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-11-16.16:31:41.912>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2010-06-24.23:28:49.674>
creator = 'vstinner'
dependencies = []
files = ['17763']
hgrepos = []
issue_num = 9076
keywords = ['patch']
message_count = 3.0
messages = ['108565', '108581', '121305']
nosy_count = 4.0
nosy_names = ['lemburg', 'georg.brandl', 'vstinner', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = None
status = 'closed'
superseder = '10435'
type = None
url = 'https://bugs.python.org/issue9076'
versions = ['Python 3.2']

[vstinner]

The following 4 functions are public but not documented and not used in Python3:

• PyUnicode_AsDecodedObject(), PyUnicode_AsEncodedObject()
• PyUnicode_AsDecodedUnicode(), PyUnicode_AsEncodedUnicode()

In Python2, PyUnicode_AsDecodedObject() was used by unicode.decode() method, but Python3 has no more str.decode() method (see the recent discussion on python-dev mailing list about .transform() / .untransform()).

In Python2, unicode.encode() uses PyUnicode_AsEncodedObject(), but in Python3 str.encode() uses PyUnicode_AsEncodedString() which ensures that the result type is bytes.

PyUnicode_AsDecodedUnicode() and PyUnicode_AsEncodedUnicode() were added by Marc-Andre Lemburg in r63986. These functions may be used for .transform() / .untranform() proposition, but this proposition is not yet accepted and the functions are now unused.

If you decide to keep one of these functions, the function have to be documented.

[malemburg]

STINNER Victor wrote:

New submission from STINNER Victor <victor.stinner@haypocalc.com>:

The following 4 functions are public but not documented and not used in Python3:

• PyUnicode_AsDecodedObject(), PyUnicode_AsEncodedObject()
• PyUnicode_AsDecodedUnicode(), PyUnicode_AsEncodedUnicode()

In Python2, PyUnicode_AsDecodedObject() was used by unicode.decode() method, but Python3 has no more str.decode() method (see the recent discussion on python-dev mailing list about .transform() / .untransform()).

In Python2, unicode.encode() uses PyUnicode_AsEncodedObject(), but in Python3 str.encode() uses PyUnicode_AsEncodedString() which ensures that the result type is bytes.

PyUnicode_AsDecodedUnicode() and PyUnicode_AsEncodedUnicode() were added by Marc-Andre Lemburg in r63986. These functions may be used for .transform() / .untranform() proposition, but this proposition is not yet accepted and the functions are now unused.

If you decide to keep one of these functions, the function have to be documented.

Victor, instead of always proposing to remove APIs that don't show
up in the C-API documentation, I'd much rather like to see documentation
patches from you, instead of patches that remove the APIs themselves.

Please also remember that we are still in a transition phase from
Python2 to Python3. The fact that Python3 (currently) doesn't use
an API does not mean that there's no Python2 3rd party code out
there using them, waiting to be ported to Python3.
It also doesn't mean that the APIs are useless.

The cases you are finding are documentation bugs. I don't want to
have to go through discussions about the usefulness of the APIs
each and every time you find one of those documentation bugs.

Furthermore, the above APIs are part of the codec system and
that doesn't have anything to do with some helper methods we have
or don't have on str and bytes objects.

Please also note that all these function *are* documented in the
unicodeobject.h header file.

[birkenfeld]

Documenting Unicode C APIs is now tracked in bpo-10435.