[Python-checkins] cpython (3.3): document that encoding error handlers may return bytes (#16585)

[benjamin.peterson]

http://hg.python.org/cpython/rev/777aabdff35a
changeset:   80693:777aabdff35a
branch:      3.3
parent:      80691:5c88c72dec60
user:        Benjamin Peterson <benjamin at python.org>
date:        Sun Dec 02 11:26:10 2012 -0500
summary:
  document that encoding error handlers may return bytes (#16585)

files:
  Doc/library/codecs.rst |  17 ++++++++++-------
  1 files changed, 10 insertions(+), 7 deletions(-)


diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -155,13 +155,16 @@
    when *name* is specified as the errors parameter.
 
    For encoding *error_handler* will be called with a :exc:`UnicodeEncodeError`
-   instance, which contains information about the location of the error. The error
-   handler must either raise this or a different exception or return a tuple with a
-   replacement for the unencodable part of the input and a position where encoding
-   should continue. The encoder will encode the replacement and continue encoding
-   the original input at the specified position. Negative position values will be
-   treated as being relative to the end of the input string. If the resulting
-   position is out of bound an :exc:`IndexError` will be raised.
+   instance, which contains information about the location of the error. The
+   error handler must either raise this or a different exception or return a
+   tuple with a replacement for the unencodable part of the input and a position
+   where encoding should continue. The replacement may be either :class:`str` or
+   :class:`bytes`.  If the replacement is bytes, the encoder will simply copy
+   them into the output buffer. If the replacement is a string, the encoder will
+   encode the replacement.  Encoding continues on original input at the
+   specified position. Negative position values will be treated as being
+   relative to the end of the input string. If the resulting position is out of
+   bound an :exc:`IndexError` will be raised.
 
    Decoding and translating works similar, except :exc:`UnicodeDecodeError` or
    :exc:`UnicodeTranslateError` will be passed to the handler and that the

-- 
Repository URL: http://hg.python.org/cpython