7.1.2.2 Parser class API

7.1.2.2 Parser class API

The Parser class, imported from the email.parser module, provides an API that can be used to parse a message when the complete contents of the message are available in a string or file. The email.parser module also provides a second class, called HeaderParser which can be used if you're only interested in the headers of the message. 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. HeaderParser has the same API as the Parser class.

class Parser(

[_class])

The constructor for the Parser class takes an optional argument _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 Message (see email.message). The factory will be called without arguments.

The optional strict flag is ignored.

Deprecated since release 2.4. Because the Parser class is a backward compatible API wrapper around the new-in-Python 2.4 FeedParser, all parsing is effectively non-strict. You should simply stop passing a strict flag to the Parser constructor.

Changed in version 2.2.2: The strict flag was added. Changed in version 2.4: The strict flag was deprecated.

The other public Parser methods are:

parse(

fp[, headersonly])

Read all the data from the file-like object fp, parse the resulting text, and return the root message object. fp must support both the readline() and the read() methods on file-like objects.

The text contained in fp must be formatted as a block of RFC 2822 style headers and header continuation lines, optionally preceded by a 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 headersonly is as with the parse() method.

Changed in version 2.2.2: The headersonly flag was added.

parsestr(

text[, headersonly])

Similar to the 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 text in a StringIO instance first and calling parse().

Optional headersonly is a flag specifying whether to stop parsing after reading the headers or not. The default is False, meaning it parses the entire contents of the file.

Changed in version 2.2.2: The headersonly flag was added.

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 email package namespace.

message_from_string(

s[, _class[, strict]])

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 Parser class constructor.

Changed in version 2.2.2: The strict flag was added.

message_from_file(

fp[, _class[, strict]])

Return a message object structure tree from an open file object. This is exactly equivalent to Parser().parse(fp). Optional _class and strict are interpreted as with the Parser class constructor.

Changed in version 2.2.2: The strict flag was added.

Here's an example of how you might use this at an interactive Python prompt:

>>> import email
>>> msg = email.message_from_string(myString)

---

Python Library Reference

Previous: 7.1.2.1 FeedParser API Up: 7.1.2 Parsing email messages Next: 7.1.2.3 Additional notes

---

Release 2.5, documentation updated on 19th September, 2006.