A few remarks from a perspective of a person who still does not understand all nooks and crannies of the Python codecs system and the *codecs* module.

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:24: but there are also codecs that encode text to text, and bytes to bytes. Shouldn't be a note about arbitrary-types codecs added *here*?

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:164: .. function:: register_error(name, error_handler) For this function and the functions described below, the above sentence "To simplify access to the various codecs, the module provides these additional functions which use :func:`lookup` for the codec lookup:" (line 112) is not appropriate. Some other sentence should be placed here (introducing error-handling-related functions.

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:182: Decoding and translating works similarly, except :exc:`UnicodeDecodeError` or Possible beginner's questions: What is "translating"? When it is performed? How can it be differentiated from subsequent encoding + decoding?

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:250: :func:`open` function; the ``'b'`` is automatically added. I would add something like: "Please note that when you need to use just an ordinary :term:`text encoding` the built-in :func:`open` function is the recommended (and, typically, more efficient) way to operate on text files".

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:325: .. _surrogateescape: Should be moved to the place above the ".. _error-handlers:" line (341).

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:335: Each codec has to define four interfaces to make it usable as codec in Python: Possible beginner's questions: is a codec an instance of :class:`Codec`? Or of :class:`CodecInfo`? What does it mean that it define those *four* intefraces? How is it related to the stateless/incremental/decoder/encoder and stream writer/reader classes described below? Why here only *four* interfaces and not *six* interfaces are mentioned? (i.e., what about *incremental encoder* and *incremental decoder?*)

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:687: providing the *errors* keyword argument. These parameters are defined: The "parameters" word does not seem to be the correct term here...

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcod... Doc/library/codecs.rst:689: * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. Only these three and not, e.g. 'surrogateescape'? Shouldn't be a reference to ".. _error-handlers:" be used here instead of this enumeration? (with a caution that the "only for encoding" handlers are disallowed)

http://bugs.python.org/review/19548/