Yeah, the documentation for the email stuff is in the dev docs.  There's a short summary in the changes section of the email intro with links to the classes and methods that are affected.  But basically you call BinaryFeedParser and feed it a binary data, and everything else works just like it did before, including the fact that get_payload() with no arguments returns a string.  If there is non-ASCII data in that string and no charset was specified the binary data will get trashed though.  To get the binary data out you call it with decode=True.

I believe you are right that the io module does not support intermixing calls to the main object and its buffer attribute; that's why detach was introduced, I believe.  Antoine is nosy on this issue now; he can correct me if I'm wrong.

So unfortunately I think we do need to come at this starting from binary at the beginning and *decoding* as needed (I believe http uses latin-1 when no charset is specified, but I need to double check that).  That still leaves the problem of what if anything to do about existing programs that expect every value in a FieldStorage to be a string.  Introduce a new method or parameter for getting the binary version of the value, possibly with some flag indicating that parsing detected non-ascii data?