(original) (raw)

changeset: 86304:32f3d6721c84 parent: 86301:500b4b62c19a parent: 86303:b607ce6c9ee6 user: Nick Coghlan ncoghlan@gmail.com date: Mon Oct 14 00:55:46 2013 +1000 files: Doc/library/codecs.rst Doc/whatsnew/3.4.rst Misc/NEWS description: Issue #17827: document codecs.encode and codecs.decode - Merge from 3.3 - Added to What's New since these are more important in 3.x, as the bytes<->bytes and str<->str codecs don't fit the text model convenience methods in 3.x the way they did the basestring<->basestring methods in the 2.x text model - Included under Library in Misc/NEWS for the same reason diff -r 500b4b62c19a -r 32f3d6721c84 Doc/library/codecs.rst --- a/Doc/library/codecs.rst Sun Oct 13 13:41:59 2013 +0000 +++ b/Doc/library/codecs.rst Mon Oct 14 00:55:46 2013 +1000 @@ -22,6 +22,25 @@ It defines the following functions: +.. function:: encode(obj, encoding='utf-8', errors='strict') + + Encodes *obj* using the codec registered for *encoding*. + + *Errors* may be given to set the desired error handling scheme. The + default error handler is ``strict`` meaning that encoding errors raise + :exc:`ValueError` (or a more codec specific subclass, such as + :exc:`UnicodeEncodeError`). Refer to :ref:`codec-base-classes` for more + information on codec error handling. + +.. function:: decode(obj, encoding='utf-8', errors='strict') + + Decodes *obj* using the codec registered for *encoding*. + + *Errors* may be given to set the desired error handling scheme. The + default error handler is ``strict`` meaning that decoding errors raise + :exc:`ValueError` (or a more codec specific subclass, such as + :exc:`UnicodeDecodeError`). Refer to :ref:`codec-base-classes` for more + information on codec error handling. .. function:: register(search_function) diff -r 500b4b62c19a -r 32f3d6721c84 Doc/whatsnew/3.4.rst --- a/Doc/whatsnew/3.4.rst Sun Oct 13 13:41:59 2013 +0000 +++ b/Doc/whatsnew/3.4.rst Mon Oct 14 00:55:46 2013 +1000 @@ -197,6 +197,19 @@ plain tuple. (Contributed by Claudiu Popa in :issue:`17818`.) +codecs +------ + +The :meth:`codecs.encode` and :meth:`codecs.decode` convenience functions are +now properly documented. These functions have existed in the :mod:`codecs` +module since ~2004, but were previously only discoverable through runtime +introspection. + +Unlike the convenience methods on :class:`str`, :class:`bytes` and +:class:`bytearray`, these convenience functions support arbitrary codecs, +rather than being limited to Unicode text encodings. + + colorsys -------- diff -r 500b4b62c19a -r 32f3d6721c84 Misc/NEWS --- a/Misc/NEWS Sun Oct 13 13:41:59 2013 +0000 +++ b/Misc/NEWS Mon Oct 14 00:55:46 2013 +1000 @@ -42,6 +42,9 @@ Library ------- +- Issue #17827: Add the missing documentation for ``codecs.encode`` and + ``codecs.decode``. + - Issue #19218: Rename collections.abc to _collections_abc in order to speed up interpreter start. /ncoghlan@gmail.com