Vast update to email version 2. This could surely use proofreading.

Doc/lib/emailencoders.tex

@@ -17,8 +17,8 @@ set the \mailheader{Content-Transfer-Encoding} header as appropriate.
 Here are the encoding functions provided:
 
 \begin{funcdesc}{encode_quopri}{msg}
-Encodes the payload into \emph{Quoted-Printable} form and sets the
-\code{Content-Transfer-Encoding:} header to
+Encodes the payload into quoted-Printable form and sets the
+\mailheader{Content-Transfer-Encoding} header to
 \code{quoted-printable}\footnote{Note that encoding with
 \method{encode_quopri()} also encodes all tabs and space characters in
 the data.}.
@@ -27,11 +27,11 @@ printable data, but contains a few unprintable characters.
 \end{funcdesc}
 
 \begin{funcdesc}{encode_base64}{msg}
-Encodes the payload into \emph{Base64} form and sets the
+Encodes the payload into base64 form and sets the
 \mailheader{Content-Transfer-Encoding} header to
 \code{base64}.  This is a good encoding to use when most of your payload
 is unprintable data since it is a more compact form than
-Quoted-Printable.  The drawback of Base64 encoding is that it
+quoted-printable.  The drawback of base64 encoding is that it
 renders the text non-human readable.
 \end{funcdesc}
 

Doc/lib/emailexc.tex

@@ -21,7 +21,7 @@ a message, this class is derived from \exception{MessageParseError}.
 It can be raised from the \method{Parser.parse()} or
 \method{Parser.parsestr()} methods.
 
-Situations where it can be raised include finding a \emph{Unix-From}
+Situations where it can be raised include finding an envelope
 header after the first \rfc{2822} header of the message, finding a
 continuation line before the first \rfc{2822} header is found, or finding
 a line in the headers which is neither a header or a continuation
@@ -35,7 +35,8 @@ It can be raised from the \method{Parser.parse()} or
 \method{Parser.parsestr()} methods.
 
 Situations where it can be raised include not being able to find the
-starting or terminating boundary in a \mimetype{multipart/*} message.
+starting or terminating boundary in a \mimetype{multipart/*} message
+when strict parsing is used.
 \end{excclassdesc}
 
 \begin{excclassdesc}{MultipartConversionError}{}
@@ -45,4 +46,9 @@ message's \mailheader{Content-Type} main type is not either
 \mimetype{multipart} or missing.  \exception{MultipartConversionError}
 multiply inherits from \exception{MessageError} and the built-in
 \exception{TypeError}.
+
+Since \method{Message.add_payload()} is deprecated, this exception is
+rarely raised in practice.  However the exception may also be raised
+if the \method{attach()} method is called on an instance of a class
+derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}).
 \end{excclassdesc}

Doc/lib/emailgenerator.tex

 \declaremodule{standard}{email.Generator}
-\modulesynopsis{Generate flat text email messages from a message object tree.}
+\modulesynopsis{Generate flat text email messages from a message structure.}
 
 One of the most common tasks is to generate the flat text of the email
-message represented by a message object tree.  You will need to do
+message represented by a message object structure.  You will need to do
 this if you want to send your message via the \refmodule{smtplib}
 module or the \refmodule{nntplib} module, or print the message on the
-console.  Taking a message object tree and producing a flat text
+console.  Taking a message object structure and producing a flat text
 document is the job of the \class{Generator} class.
 
 Again, as with the \refmodule{email.Parser} module, you aren't limited
@@ -13,10 +13,9 @@ to the functionality of the bundled generator; you could write one
 from scratch yourself.  However the bundled generator knows how to
 generate most email in a standards-compliant way, should handle MIME
 and non-MIME email messages just fine, and is designed so that the
-transformation from flat text, to an object tree via the
-\class{Parser} class,
-and back to flat text, is idempotent (the input is identical to the
-output).
+transformation from flat text, to a message structure via the
+\class{Parser} class, and back to flat text, is idempotent (the input
+is identical to the output).
 
 Here are the public methods of the \class{Generator} class:
 
@@ -27,14 +26,16 @@ object called \var{outfp} for an argument.  \var{outfp} must support
 the \method{write()} method and be usable as the output file in a
 Python 2.0 extended print statement.
 
-Optional \var{mangle_from_} is a flag that, when true, puts a \samp{>}
-character in front of any line in the body that starts exactly as
+Optional \var{mangle_from_} is a flag that, when \code{True}, puts a
+\samp{>} character in front of any line in the body that starts exactly as
 \samp{From } (i.e. \code{From} followed by a space at the front of the
 line).  This is the only guaranteed portable way to avoid having such
-lines be mistaken for \emph{Unix-From} headers (see
+lines be mistaken for a Unix mailbox format envelope header separator (see
 \ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
 {http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
-for details).
+for details).  \var{mangle_from_} defaults to \code{True}, but you
+might want to set this to \code{False} if you are not writing Unix
+mailbox format files.
 
 Optional \var{maxheaderlen} specifies the longest length for a
 non-continued header.  When a header line is longer than
@@ -47,20 +48,28 @@ recommended (but not required) by \rfc{2822}.
 
 The other public \class{Generator} methods are:
 
-\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
-Print the textual representation of the message object tree rooted at
+\begin{methoddesc}[Generator]{flatten()}{msg\optional{, unixfrom}}
+Print the textual representation of the message object structure rooted at
 \var{msg} to the output file specified when the \class{Generator}
 instance was created.  Sub-objects are visited depth-first and the
 resulting text will be properly MIME encoded.
 
 Optional \var{unixfrom} is a flag that forces the printing of the
-\emph{Unix-From} (a.k.a. envelope header or \code{From_} header)
-delimiter before the first \rfc{2822} header of the root message
-object.  If the root object has no \emph{Unix-From} header, a standard
-one is crafted.  By default, this is set to 0 to inhibit the printing
-of the \emph{Unix-From} delimiter.
+envelope header delimiter before the first \rfc{2822} header of the
+root message object.  If the root object has no envelope header, a
+standard one is crafted.  By default, this is set to \code{False} to
+inhibit the printing of the envelope delimiter.
+
+Note that for sub-objects, no envelope header is ever printed.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Generator]{clone}{fp}
+Return an independent clone of this \class{Generator} instance with
+the exact same options.
 
-Note that for sub-objects, no \emph{Unix-From} header is ever printed.
+\versionadded{2.2.2}
 \end{methoddesc}
 
 \begin{methoddesc}[Generator]{write}{s}
@@ -74,3 +83,49 @@ As a convenience, see the methods \method{Message.as_string()} and
 \code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
 simplify the generation of a formatted string representation of a
 message object.  For more detail, see \refmodule{email.Message}.
+
+The \module{email.Generator} module also provides a derived class,
+called \class{DecodedGenerator} which is like the \class{Generator}
+base class, except that non-\mimetype{text} parts are substituted with
+a format string representing the part.
+
+\begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{,
+    maxheaderlen\optional{, fmt}}}}
+
+This class, derived from \class{Generator} walks through all the
+subparts of a message.  If the subpart is of main type
+\mimetype{text}, then it prints the decoded payload of the subpart.
+Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the
+\class{Generator} base class.
+
+If the subpart is not of main type \mimetype{text}, optional \var{fmt}
+is a format string that is used instead of the message
+payload.  \var{fmt} is expanded with the following keywords (in
+\samp{\%(keyword)s} format):
+
+type       : Full MIME type of the non-\mimetype{text} part
+maintype   : Main MIME type of the non-\mimetype{text} part
+subtype    : Sub-MIME type of the non-\mimetype{text} part
+filename   : Filename of the non-\mimetype{text} part
+description: Description associated with the non-\mimetype{text} part
+encoding   : Content transfer encoding of the non-\mimetype{text} part
+
+The default value for \var{fmt} is \code{None}, meaning
+
+\begin{verbatim}
+[Non-text (%(type)s) part of message omitted, filename %(filename)s]
+\end{verbatim}
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\subsubsection{Deprecated methods}
+
+The following methods are deprecated in \module{email} version 2.
+They are documented here for completeness.
+
+\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
+This method is identical to the \method{flatten()} method.
+
+\deprecated{2.2.2}{Use the \method{flatten()} method instead.}
+\end{methoddesc}

Doc/lib/emailiter.tex

@@ -29,3 +29,35 @@ Thus, by default \function{typed_subpart_iterator()} returns each
 subpart that has a MIME type of \mimetype{text/*}.
 \end{funcdesc}
 
+The following function has been added as a useful debugging tool.  It
+should \emph{not} be considered part of the supported public interface
+for the package.
+
+\begin{funcdesc}{_structure}{msg\optional{, fp\optional{, level}}}
+Prints an indented representation of the content types of the
+message object structure.  For example:
+
+\begin{verbatim}
+>>> msg = email.message_from_file(somefile)
+>>> _structure(msg)
+multipart/mixed
+    text/plain
+    text/plain
+    multipart/digest
+        message/rfc822
+            text/plain
+        message/rfc822
+            text/plain
+        message/rfc822
+            text/plain
+        message/rfc822
+            text/plain
+        message/rfc822
+            text/plain
+    text/plain
+\end{verbatim}
+
+Optional \var{fp} is a file-like object to print the output to.  It
+must be suitable for Python's extended print statement.  \var{level}
+is used internally.
+\end{funcdesc}

Doc/lib/emailmimebase.tex

+Ordinarily, you get a message object structure by passing a file or
+some text to a parser, which parses the text and returns the root of
+the message object structure.  However you can also build a complete
+object structure from scratch, or even individual \class{Message}
+objects by hand.  In fact, you can also take an existing structure and
+add new \class{Message} objects, move them around, etc.  This makes a
+very convenient interface for slicing-and-dicing MIME messages.
+
+You can create a new object structure by creating \class{Message}
+instances, adding attachments and all the appropriate headers manually.
+For MIME messages though, the \module{email} package provides some
+convenient subclasses to make things easier.  Each of these classes
+should be imported from a module with the same name as the class, from
+within the \module{email} package.  E.g.:
+
+\begin{verbatim}
+import email.MIMEImage.MIMEImage
+\end{verbatim}
+
+or
+
+\begin{verbatim}
+from email.MIMEText import MIMEText
+\end{verbatim}
+
+Here are the classes:
+
+\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
+This is the base class for all the MIME-specific subclasses of
+\class{Message}.  Ordinarily you won't create instances specifically
+of \class{MIMEBase}, although you could.  \class{MIMEBase} is provided
+primarily as a convenient base class for more specific MIME-aware
+subclasses.
+
+\var{_maintype} is the \mailheader{Content-Type} major type
+(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the
+\mailheader{Content-Type} minor type 
+(e.g. \mimetype{plain} or \mimetype{gif}).  \var{_params} is a parameter
+key/value dictionary and is passed directly to
+\method{Message.add_header()}.
+
+The \class{MIMEBase} class always adds a \mailheader{Content-Type} header
+(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a
+\mailheader{MIME-Version} header (always set to \code{1.0}).
+\end{classdesc}
+
+\begin{classdesc}{MIMENonMultipart}{}
+A subclass of \class{MIMEBase}, this is an intermediate base class for
+MIME messages that are not \mimetype{multipart}.  The primary purpose
+of this class is to prevent the use of the \method{attach()} method,
+which only makes sense for \mimetype{multipart} messages.  If
+\method{attach()} is called, a \exception{MultipartConversionError}
+exception is raised.
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{,
+    boundary\optional{, _subparts\optional{, _params}}}}}
+
+A subclass of \class{MIMEBase}, this is an intermediate base class for
+MIME messages that are \mimetype{multipart}.  Optional \var{_subtype}
+defaults to \mimetype{mixed}, but can be used to specify the subtype
+of the message.  A \mailheader{Content-Type} header of
+\mimetype{multipart/}\var{_subtype} will be added to the message
+object.  A \mailheader{MIME-Version} header will also be added.
+
+Optional \var{boundary} is the multipart boundary string.  When
+\code{None} (the default), the boundary is calculated when needed.
+
+\var{_subparts} is a sequence of initial subparts for the payload.  It
+must be possible to convert this sequence to a list.  You can always
+attach new subparts to the message by using the
+\method{Message.attach()} method.
+
+Additional parameters for the \mailheader{Content-Type} header are
+taken from the keyword arguments, or passed into the \var{_params}
+argument, which is a keyword dictionary.
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
+    _encoder\optional{, **_params}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class
+is used to create MIME message objects of major type \mimetype{audio}.
+\var{_audiodata} is a string containing the raw audio data.  If this
+data can be decoded by the standard Python module \refmodule{sndhdr},
+then the subtype will be automatically included in the
+\mailheader{Content-Type} header.  Otherwise you can explicitly specify the
+audio subtype via the \var{_subtype} parameter.  If the minor type could
+not be guessed and \var{_subtype} was not given, then \exception{TypeError}
+is raised.
+
+Optional \var{_encoder} is a callable (i.e. function) which will
+perform the actual encoding of the audio data for transport.  This
+callable takes one argument, which is the \class{MIMEAudio} instance.
+It should use \method{get_payload()} and \method{set_payload()} to
+change the payload to encoded form.  It should also add any
+\mailheader{Content-Transfer-Encoding} or other headers to the message
+object as necessary.  The default encoding is \emph{Base64}.  See the
+\refmodule{email.Encoders} module for a list of the built-in encoders.
+
+\var{_params} are passed straight through to the base class constructor.
+\end{classdesc}
+
+\begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
+    _encoder\optional{, **_params}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is
+used to create MIME message objects of major type \mimetype{image}.
+\var{_imagedata} is a string containing the raw image data.  If this
+data can be decoded by the standard Python module \refmodule{imghdr},
+then the subtype will be automatically included in the
+\mailheader{Content-Type} header.  Otherwise you can explicitly specify the
+image subtype via the \var{_subtype} parameter.  If the minor type could
+not be guessed and \var{_subtype} was not given, then \exception{TypeError}
+is raised.
+
+Optional \var{_encoder} is a callable (i.e. function) which will
+perform the actual encoding of the image data for transport.  This
+callable takes one argument, which is the \class{MIMEImage} instance.
+It should use \method{get_payload()} and \method{set_payload()} to
+change the payload to encoded form.  It should also add any
+\mailheader{Content-Transfer-Encoding} or other headers to the message
+object as necessary.  The default encoding is \emph{Base64}.  See the
+\refmodule{email.Encoders} module for a list of the built-in encoders.
+
+\var{_params} are passed straight through to the \class{MIMEBase}
+constructor.
+\end{classdesc}
+
+\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
+A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class
+is used to create MIME objects of main type \mimetype{message}.
+\var{_msg} is used as the payload, and must be an instance of class
+\class{Message} (or a subclass thereof), otherwise a
+\exception{TypeError} is raised.
+
+Optional \var{_subtype} sets the subtype of the message; it defaults
+to \mimetype{rfc822}.
+\end{classdesc}
+
+\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
+    _charset\optional{, _encoder}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
+used to create MIME objects of major type \mimetype{text}.
+\var{_text} is the string for the payload.  \var{_subtype} is the
+minor type and defaults to \mimetype{plain}.  \var{_charset} is the
+character set of the text and is passed as a parameter to the
+\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}.  No
+guessing or encoding is performed on the text data, but a newline is
+appended to \var{_text} if it doesn't already end with a newline.
+
+\deprecated{2.2.2}{The \var{_encoding} argument has been deprecated.
+Encoding now happens implicitly based on the \var{_charset} argument.}
+\end{classdesc}

Doc/lib/emailparser.tex

 \declaremodule{standard}{email.Parser}
 \modulesynopsis{Parse flat text email messages to produce a message
-	        object tree.}
+	        object structure.}
 
-Message object trees can be created in one of two ways: they can be
+Message object structures can be created in one of two ways: they can be
 created from whole cloth by instantiating \class{Message} objects and
-stringing them together via \method{add_payload()} and
+stringing them together via \method{attach()} and
 \method{set_payload()} calls, or they can be created by parsing a flat text
 representation of the email message.
 
 The \module{email} package provides a standard parser that understands
 most email document structures, including MIME documents.  You can
 pass the parser a string or a file object, and the parser will return
-to you the root \class{Message} instance of the object tree.  For
+to you the root \class{Message} instance of the object structure.  For
 simple, non-MIME messages the payload of this root object will likely
 be a string containing the text of the message.  For MIME
-messages, the root object will return true from its
+messages, the root object will return \code{True} from its
 \method{is_multipart()} method, and the subparts can be accessed via
 the \method{get_payload()} and \method{walk()} methods.
 
@@ -27,28 +27,46 @@ message object trees any way it finds necessary.
 The primary parser class is \class{Parser} which parses both the
 headers and the payload of the message.  In the case of
 \mimetype{multipart} messages, it will recursively parse the body of
-the container message.  The \module{email.Parser} module also provides
-a second class, called \class{HeaderParser} which can be used if
-you're only interested in the headers of the message.
-\class{HeaderParser} can be much faster in this situations, since it
-does not attempt to parse the message body, instead setting the
-payload to the raw body as a string.  \class{HeaderParser} has the
-same API as the \class{Parser} class.
+the container message.  Two modes of parsing are supported,
+\emph{strict} parsing, which will usually reject any non-RFC compliant
+message, and \emph{lax} parsing, which attempts to adjust for common
+MIME formatting problems.
+
+The \module{email.Parser} module also provides a second class, called
+\class{HeaderParser} which can be used if you're only interested in
+the headers of the message. \class{HeaderParser} can be much faster in
+these situations, since it does not attempt to parse the message body,
+instead setting the payload to the raw body as a string.
+\class{HeaderParser} has the same API as the \class{Parser} class.
 
 \subsubsection{Parser class API}
 
-\begin{classdesc}{Parser}{\optional{_class}}
-The constructor for the \class{Parser} class takes a single optional
+\begin{classdesc}{Parser}{\optional{_class\optional{, strict}}}
+The constructor for the \class{Parser} class takes an optional
 argument \var{_class}.  This must be a callable factory (such as a
 function or a class), and it is used whenever a sub-message object
 needs to be created.  It defaults to \class{Message} (see
 \refmodule{email.Message}).  The factory will be called without
 arguments.
+
+The optional \var{strict} flag specifies whether strict or lax parsing
+should be performed.  Normally, when things like MIME terminating
+boundaries are missing, or when messages contain other formatting
+problems, the \class{Parser} will raise a
+\exception{MessageParseError}.  However, when lax parsing is enabled,
+the \class{Parser} will attempt to workaround such broken formatting
+to produce a usable message structure (this doesn't mean
+\exception{MessageParseError}s are never raised; some ill-formatted
+messages just can't be parsed).  The \var{strict} flag defaults to
+\code{False} since lax parsing usually provides the most convenient
+behavior.
+
+\versionchanged[The \var{strict} flag was added]{2.2.2}
 \end{classdesc}
 
 The other public \class{Parser} methods are:
 
-\begin{methoddesc}[Parser]{parse}{fp}
+\begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}}
 Read all the data from the file-like object \var{fp}, parse the
 resulting text, and return the root message object.  \var{fp} must
 support both the \method{readline()} and the \method{read()} methods
@@ -56,32 +74,49 @@ on file-like objects.
 
 The text contained in \var{fp} must be formatted as a block of \rfc{2822}
 style headers and header continuation lines, optionally preceeded by a
-\emph{Unix-From} header.  The header block is terminated either by the
+envelope header.  The header block is terminated either by the
 end of the data or by a blank line.  Following the header block is the
 body of the message (which may contain MIME-encoded subparts).
+
+Optional \var{headersonly} is a flag specifying whether to stop
+parsing after reading the headers or not.  The default is \code{False},
+meaning it parses the entire contents of the file.
+
+\versionchanged[The \var{headersonly} flag was added]{2.2.2}
 \end{methoddesc}
 
-\begin{methoddesc}[Parser]{parsestr}{text}
+\begin{methoddesc}[Parser]{parsestr}{text\optional{, headersonly}}
 Similar to the \method{parse()} method, except it takes a string
 object instead of a file-like object.  Calling this method on a string
 is exactly equivalent to wrapping \var{text} in a \class{StringIO}
 instance first and calling \method{parse()}.
+
+Optional \var{headersonly} is a flag specifying whether to stop
+parsing after reading the headers or not.  The default is \code{False},
+meaning it parses the entire contents of the file.
+
+\versionchanged[The \var{headersonly} flag was added]{2.2.2}
 \end{methoddesc}
 
-Since creating a message object tree from a string or a file object is
-such a common task, two functions are provided as a convenience.  They
-are available in the top-level \module{email} package namespace.
+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 in the top-level \module{email}
+package namespace.
 
-\begin{funcdesc}{message_from_string}{s\optional{, _class}}
+\begin{funcdesc}{message_from_string}{s\optional{, _class\optional{, strict}}}
 Return a message object tree from a string.  This is exactly
-equivalent to \code{Parser().parsestr(s)}.  Optional \var{_class} is
-interpreted as with the \class{Parser} class constructor.
+equivalent to \code{Parser().parsestr(s)}.  Optional \var{_class} and
+\var{strict} are interpreted as with the \class{Parser} class constructor.
+
+\versionchanged[The \var{strict} flag was added]{2.2.2}
 \end{funcdesc}
 
-\begin{funcdesc}{message_from_file}{fp\optional{, _class}}
+\begin{funcdesc}{message_from_file}{fp\optional{, _class\optional{, strict}}}
 Return a message object tree from an open file object.  This is exactly
-equivalent to \code{Parser().parse(fp)}.  Optional \var{_class} is
-interpreted as with the \class{Parser} class constructor.
+equivalent to \code{Parser().parse(fp)}.  Optional \var{_class} and
+\var{strict} are interpreted as with the \class{Parser} class constructor.
+
+\versionchanged[The \var{strict} flag was added]{2.2.2}
 \end{funcdesc}
 
 Here's an example of how you might use this at an interactive Python
@@ -99,15 +134,17 @@ Here are some notes on the parsing semantics:
 \begin{itemize}
 \item Most non-\mimetype{multipart} type messages are parsed as a single
       message object with a string payload.  These objects will return
-      0 for \method{is_multipart()}.
-\item One exception is for \mimetype{message/delivery-status} type
-      messages.  Because the body of such messages consist of
-      blocks of headers, \class{Parser} will create a non-multipart
-      object containing non-multipart subobjects for each header
-      block.
-\item Another exception is for \mimetype{message/*} types (more
-      general than \mimetype{message/delivery-status}).  These are
-      typically \mimetype{message/rfc822} messages, represented as a
-      non-multipart object containing a singleton payload which is
-      another non-multipart \class{Message} instance.
+      \code{False} for \method{is_multipart()}.  Their
+      \method{get_payload()} method will return a string object.
+\item All \mimetype{multipart} type messages will be parsed as a
+      container message object with a list of sub-message objects for
+      their payload.  These messages will return \code{True} for
+      \method{is_multipart()} and their \method{get_payload()} method
+      will return a list of \class{Message} instances.
+\item Most messages with a content type of \mimetype{message/*}
+      (e.g. \mimetype{message/deliver-status} and
+      \mimetype{message/rfc822}) will also be parsed as container
+      object containing a list payload of length 1.  Their
+      \method{is_multipart()} method will return \code{True}.  The
+      single element in the list payload will be a sub-message object.
 \end{itemize}

Doc/lib/emailutil.tex

@@ -21,10 +21,10 @@ Parse address -- which should be the value of some address-containing
 field such as \mailheader{To} or \mailheader{Cc} -- into its constituent
 \emph{realname} and \emph{email address} parts.  Returns a tuple of that
 information, unless the parse fails, in which case a 2-tuple of
-\code{(None, None)} is returned.
+\code{('', '')} is returned.
 \end{funcdesc}
 
-\begin{funcdesc}{dump_address_pair}{pair}
+\begin{funcdesc}{formataddr}{pair}
 The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
 \code{(realname, email_address)} and returns the string value suitable
 for a \mailheader{To} or \mailheader{Cc} header.  If the first element of
@@ -48,27 +48,6 @@ all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
 \end{verbatim}
 \end{funcdesc}
 
-\begin{funcdesc}{decode}{s}
-This method decodes a string according to the rules in \rfc{2047}.  It
-returns the decoded string as a Python unicode string.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
-This method encodes a string according to the rules in \rfc{2047}.  It
-is not actually the inverse of \function{decode()} since it doesn't
-handle multiple character sets or multiple string parts needing
-encoding.  In fact, the input string \var{s} must already be encoded
-in the \var{charset} character set (Python can't reliably guess what
-character set a string might be encoded in).  The default
-\var{charset} is \samp{iso-8859-1}.
-
-\var{encoding} must be either the letter \character{q} for
-Quoted-Printable or \character{b} for Base64 encoding.  If
-neither, a \exception{ValueError} is raised.  Both the \var{charset} and
-the \var{encoding} strings are case-insensitive, and coerced to lower
-case in the returned string.
-\end{funcdesc}
-
 \begin{funcdesc}{parsedate}{date}
 Attempts to parse a date according to the rules in \rfc{2822}.
 however, some mailers don't follow that format as specified, so
@@ -116,7 +95,48 @@ Optional \var{timeval} if given is a floating point time value as
 accepted by \function{time.gmtime()} and \function{time.localtime()},
 otherwise the current time is used.
 
-Optional \var{localtime} is a flag that when true, interprets
+Optional \var{localtime} is a flag that when \code{True}, interprets
 \var{timeval}, and returns a date relative to the local timezone
 instead of UTC, properly taking daylight savings time into account.
+The default is \code{False} meaning UTC is used.
+\end{funcdesc}
+
+\begin{funcdesc}{make_msgid}{\optional{idstring}}
+Returns a string suitable for an \rfc{2822}-compliant
+\mailheader{Message-ID} header.  Optional \var{idstring} if given, is
+a string used to strengthen the uniqueness of the message id.
+\end{funcdesc}
+
+\begin{funcdesc}{decode_rfc2231}{s}
+Decode the string \var{s} according to \rfc{2231}.
+\end{funcdesc}
+
+\begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}}
+Encode the string \var{s} according to \rfc{2231}.  Optional
+\var{charset} and \var{language}, if given is the character set name
+and language name to use.  If neither is given, \var{s} is returned
+as-is.  If \var{charset} is given but \var{language} is not, the
+string is encoded using the empty string for \var{language}.
 \end{funcdesc}
+
+\begin{funcdesc}{decode_params}{params}
+Decode parameters list according to \rfc{2231}.  \var{params} is a
+sequence of 2-tuples containing elements of the form
+\code{(content-type, string-value)}.
+\end{funcdesc}
+
+The following functions have been deprecated:
+
+\begin{funcdesc}{dump_address_pair}{pair}
+\deprecated{2.2.2}{Use \function{formataddr()} instead.}
+\end{funcdesc}
+
+\begin{funcdesc}{decode}{s}
+\deprecated{2.2.2}{Use \method{Header.decode_header()} instead.}
+\end{funcdesc}
+
+
+\begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
+\deprecated{2.2.2}{Use \method{Header.encode()} instead.}
+\end{funcdesc}
+