https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst File Doc/library/codecs.rst (right): https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:325: .. _surrogateescape: On 2014/12/26 01:21:35, zuo wrote:

Should be moved to the place above the ".. _error-handlers:" line (341).

Still needs updating in the “default” branch. Not relevant for the 3.4 branch. https://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:335: Each codec has to define four interfaces to make it usable as codec in Python: On 2014/12/26 01:21:35, zuo wrote:

Possible beginner's questions: is a codec an instance of :class:`Codec`? Or of :class:`CodecInfo`? My understanding is a codec is a CodecInfo instance pointing to concrete classes implementing the (stateless) Codec, and/or stateful StreamReader/Writer, IncrementalDe/Encoder interfaces. Not sure on how many of these are mandatory though.

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?*)

https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst File Doc/library/codecs.rst (right): https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:24: bytes. Custom codecs may encode and decode between arbitrary types, but some Does this include non-sequence types? If so, the “length consumed” return value and the StreamReader class make no sense to me, and finalizing incremental codecs becomes more difficult. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:211: a text stream. Perhaps the last sentence is not needed, now that all these functions are introduced as being for binary files. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:382: The standard error handlers are implemented in the following functions: This is just “_Some_ standard error handlers”, since the surrogate handlers are omitted. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:420: Codec Objects On 2014/12/30 14:38:56, zuo wrote:

Still the relation between the `codec` term and the Codec class/objects is not clear IMHO.

A see some term confusion here: the `text encoding` term is defined (in the glossary) just as a *kind of* *codec*, buy *here* the words `encoding` and `decoding` refer to activities (each being a reversal of the other)

Maybe changing the heading to “Stateless Codec Objects” would help? https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:625: *stream* must be a file-like object open for writing binary data. Did you mean to revert to “binary data” here? Patch v3 changed the wording here. https://bugs.python.org/review/19548/diff/13502/Doc/library/codecs.rst#newco... Doc/library/codecs.rst:829: :term:`text encoding` and recreating the On 2014/12/30 14:38:56, zuo wrote: performed

*by* a *codec*.

This was my sloppy wording, when I tried to introduce a link to the glossary. Maybe it should be added a couple sentences later: Transforming a string into a sequence of bytes is known as *encoding*, and recreating the string from the sequence of bytes is known as *decoding*. There are different methods for how this transformation can be done. (These methods are also called :term:`text encodings <text encoding>`.) https://bugs.python.org/review/19548/