> To make the distinction easier to remember, would it help if the
> methods that are currently set to return bytes instead accepted the
> typical encoding+errors parameters, with parallel *b APIs to get at
> the raw bytes?

Not really, no. For raw messages, which encoding+errors must be used
depends on the returned contents, it's not something the client can know
up front; moreover, different parts of the returned bytes may need
decoding using different encodings (for example if there are several
MIME parts to the message). People should use the email package to parse
the raw messages, as I assume they already do in 2.x.

Apart from raw message bodies, NNTP data has well-defined encodings and
that's why I can take and return unicode (although as stated, I also use
surrogateescape to be fault-tolerant in the face of broken servers).

> My concern with the current API is that there isn't a clear indicator
> during normal programming as to which APIs return strings and which
> return the raw bytes and hence require further decoding.

That's a documentation issue. I haven't touched the docs yet :)