classification
Title: Document codecs.encode and codecs.decode
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Grant, barry, docs@python, ezio.melotti, flox, ncoghlan, python-dev, tshepang
Priority: normal Keywords: easy, patch

Created on 2013-04-24 13:45 by ncoghlan, last changed 2013-11-04 10:08 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
17827.diff Grant, 2013-07-08 07:17 17827-3.4 review
issue17827_docs_py27.diff ncoghlan, 2013-11-04 09:28 Docs patch for Python 2.7 review
Messages (13)
msg187700 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-04-24 13:45
The codecs module has long offered encode() and decode() convenience functions (since 2004: http://hg.python.org/cpython-fullhistory/rev/8ea2cb1ec598), but they're not documented (except through docstrings). We should fix that.

From the docstrings:
==========
encode(obj, [encoding[,errors]]) -> object

Encodes obj using the codec registered for encoding. encoding defaults
to the default encoding. errors may be given to set a different error
handling scheme. Default is 'strict' meaning that encoding errors raise
a ValueError. Other possible values are 'ignore', 'replace' and
'xmlcharrefreplace' as well as any other name registered with
codecs.register_error that can handle ValueErrors.
==========
decode(obj, [encoding[,errors]]) -> object

Decodes obj using the codec registered for encoding. encoding defaults
to the default encoding. errors may be given to set a different error
handling scheme. Default is 'strict' meaning that encoding errors raise
a ValueError. Other possible values are 'ignore' and 'replace'
as well as any other name registered with codecs.register_error that is
able to handle ValueErrors.
==========

Note that the difference between the convenience functions in the codecs module and the methods on str, bytes and bytearray is that the latter have additional type checks to limit their usage to text encodings. str.encode expects a str->bytes conversion, while bytes.decode and bytearray.decode both expect the codec to produce a str object. codecs.encode and codecs.decode are both arbitrary object->object conversions, limited only by whatever the chosen codec supports.
msg187765 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-04-25 07:51
Note that in 2.7, these docs should have a ":versionadded: 2.4" marker, while in 3.3 and 3.4, they shouldn't have a version added marker at all.

These functions should also get an entry in the 3.4 What's New, even though they're not actually new.
msg187866 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2013-04-26 17:38
So, why place them in What's New?
msg187867 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-04-26 17:51
To advertise them?  It should be explained that they are not new, but that now they are documented and can/should be used.
msg187871 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2013-04-26 19:32
I was not aware that such things are placed in What's New. I just looked at such a document for 3.3... makes a lot of sense.
msg187910 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-04-27 15:21
This is only the second case I'm aware of where a particularly interesting piece of functionality didn't get mentioned in the appropriate What's New doc. For the other case, the zipfile execution support, we just added it in to the 2.6 What's New long after 2.6 had been released. To this day, most people don't know about that capability, which is why I suggest it's worth handling the current case (codecs.encode and codecs.decode) differently and noting their existence in the next What's New doc that people are likely to read :)
msg192625 - (view) Author: Grant (Grant) Date: 2013-07-08 07:17
codecs module and 'whats new' doc patch for 3.4
msg198848 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-02 15:17
We should fix the docs for the earlier versions as well.
msg199713 - (view) Author: Roundup Robot (python-dev) Date: 2013-10-13 14:56
New changeset b607ce6c9ee6 by Nick Coghlan in branch '3.3':
Issue #17827: Document codecs.encode and codecs.decode
http://hg.python.org/cpython/rev/b607ce6c9ee6

New changeset 32f3d6721c84 by Nick Coghlan in branch 'default':
Issue #17827: document codecs.encode and codecs.decode
http://hg.python.org/cpython/rev/32f3d6721c84
msg199718 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-13 15:05
Still need to backport this to 2.7

(Thanks for the preliminary patch Grant, but I'm afraid it didn't make it into what I ended up committing)
msg202099 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-11-04 09:28
Hmm, I just noticed an interesting issue here in drafting the 2.7 backport: as near as I can tell, these aren't tested, so other implementations that failed to provide them would pass the 2.7 and 3.3 test suites.
msg202101 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-11-04 09:47
Oops, never mind - the tests are already there (and have been since MAL's original commit prior to Python 2.4), I just fail at searching code.
msg202108 - (view) Author: Roundup Robot (python-dev) Date: 2013-11-04 10:08
New changeset bdb30bdf60a5 by Nick Coghlan in branch '2.7':
Close #17827: Document codecs.encode & codecs.decode
http://hg.python.org/cpython/rev/bdb30bdf60a5
History
Date User Action Args
2013-11-04 10:08:46python-devsetstatus: open -> closed
resolution: fixed
messages: + msg202108

stage: needs patch -> resolved
2013-11-04 09:47:21ncoghlansettitle: Document and test codecs.encode and codecs.decode -> Document codecs.encode and codecs.decode
messages: + msg202101
versions: - Python 3.3, Python 3.4
2013-11-04 09:31:43ncoghlansettitle: Document codecs.encode and codecs.decode -> Document and test codecs.encode and codecs.decode
versions: + Python 3.3, Python 3.4
2013-11-04 09:28:17ncoghlansetfiles: + issue17827_docs_py27.diff

messages: + msg202099
2013-10-13 15:05:57ncoghlansetmessages: + msg199718
versions: - Python 3.3, Python 3.4
2013-10-13 14:56:14python-devsetnosy: + python-dev
messages: + msg199713
2013-10-02 15:17:55ncoghlansetmessages: + msg198848
versions: + Python 2.7, Python 3.3
2013-07-08 07:17:25Grantsetfiles: + 17827.diff
versions: - Python 2.7, Python 3.3
nosy: + Grant

messages: + msg192625

keywords: + patch
2013-04-27 15:21:34ncoghlansetmessages: + msg187910
2013-04-26 19:32:44tshepangsetmessages: + msg187871
2013-04-26 17:51:46ezio.melottisetmessages: + msg187867
2013-04-26 17:38:50tshepangsetnosy: + tshepang
messages: + msg187866
2013-04-25 13:54:08barrysetnosy: + barry
2013-04-25 07:51:29ncoghlansetmessages: + msg187765
2013-04-24 14:23:57floxsetnosy: + flox
2013-04-24 13:49:34ezio.melottisetkeywords: + easy
nosy: + ezio.melotti

type: enhancement
stage: needs patch
2013-04-24 13:45:40ncoghlancreate