source: trunk/essentials/dev-lang/python/Doc/lib/emailparser.tex@ 3368

\declaremodule{standard}{email.parser}
\modulesynopsis{Parse flat text email messages to produce a message
                object structure.}

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{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 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 \code{True} from its
\method{is_multipart()} method, and the subparts can be accessed via
the \method{get_payload()} and \method{walk()} methods.

There are actually two parser interfaces available for use, the classic
\class{Parser} API and the incremental \class{FeedParser} API.  The classic
\class{Parser} API is fine if you have the entire text of the message in
memory as a string, or if the entire message lives in a file on the file
system.  \class{FeedParser} is more appropriate for when you're reading the
message from a stream which might block waiting for more input (e.g. reading
an email message from a socket).  The \class{FeedParser} can consume and parse
the message incrementally, and only returns the root object when you close the
parser\footnote{As of email package version 3.0, introduced in
Python 2.4, the classic \class{Parser} was re-implemented in terms of the
\class{FeedParser}, so the semantics and results are identical between the two
parsers.}.

Note that the parser can be extended in limited ways, and of course
you can implement your own parser completely from scratch.  There is
no magical connection between the \module{email} package's bundled