email5 bytes parsing patch

Doc/library/email.parser.rst

Index: Doc/library/email.parser.rst
===================================================================
--- Doc/library/email.parser.rst	(revision 85191)
+++ Doc/library/email.parser.rst	(working copy)
@@ -34,7 +34,13 @@
 :class:`~email.message.Message` class, so your custom parser can create message
 object trees any way it finds necessary.
 
+The parser expects its input in the form of strings.  To handle binary input
+data, the data must be decoded as ASCII.  If the input contains non-ASCII data,
+use the `surrogateescape` error handler to do the decoding.  The standard model
+recognizes binary data escaped in this way and transforms it back to bytes for
+processing and re-decoding as needed.
 
+
 FeedParser API
 ^^^^^^^^^^^^^^
 
@@ -71,7 +77,8 @@
       :class:`FeedParser` will stitch such partial lines together properly.  The
       lines in the string can have any of the common three line endings,
       carriage return, newline, or carriage return and newline (they can even be
-      mixed).
+      mixed).  The lines may contain binary data escaped using the `surrogateescape`
+      error handler; this data will be recognized as binary data by the model.

[barry, 2010/10/04 17:34:35]

Do you want to add a "new in python 3.2" note for this and other changes to
email 5.1?

[r.david.murray, 2010/10/06 01:20:39]

Yes.  Though in this case I'm going to make a BytesFeedParser instead of
documenting surrogateescape.

 
    .. method:: close()
 
@@ -138,25 +145,37 @@
       reading the headers or not.  The default is ``False``, meaning it parses
       the entire contents of the file.
 
+   .. method:: parsebytes(bytes, headersonly=False)
 
+      Like :meth:`parsestr` except that it accepts bytes and decodes them
+      using the ASCII codec and the `surrogateescape` error handler.
+
+
 Since creating a message object structure from a string or a file object is such
-a common task, two functions are provided as a convenience.  They are available
+a common task, three functions are provided as a convenience.  They are available
 in the top-level :mod:`email` package namespace.
 
 .. currentmodule:: email
 
-.. function:: message_from_string(s[, _class][, strict])
+.. function:: message_from_string(s, _class=email.message.Message, strict=None)
 
    Return a message object structure from a string.  This is exactly equivalent to
    ``Parser().parsestr(s)``.  Optional *_class* and *strict* are interpreted as
    with the :class:`Parser` class constructor.
 
+.. function:: message_from_bytes(s, _class=email.message.Message, strict=None)
 
-.. function:: message_from_file(fp[, _class][, strict])
+   Return a message object structure from a byte string.  This is a convience
+   wrapper around :func:`message_from_string` that decodes the bytes using
+   the ASCII codec and the `surrogateescape` error handler.
 
+.. function:: message_from_file(fp, _class=email.message.Message, strict=None)
+
    Return a message object structure tree from an open :term:`file object`.
    This is exactly equivalent to ``Parser().parse(fp)``.  Optional *_class*
    and *strict* are interpreted as with the :class:`Parser` class constructor.
+   To process a binary file, open it as a text file decoded with the ASCII
+   codec and the `surrogateescape` error handler.
 
 Here's an example of how you might use this at an interactive Python prompt::