diff options
Diffstat (limited to 'Doc/library/email.parser.rst')
-rw-r--r-- | Doc/library/email.parser.rst | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst new file mode 100644 index 0000000..048ed22 --- /dev/null +++ b/Doc/library/email.parser.rst @@ -0,0 +1,220 @@ +:mod:`email`: Parsing email messages +------------------------------------ + +.. module:: email.parser + :synopsis: 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 :meth:`attach` and :meth:`set_payload` calls, or they can be +created by parsing a flat text representation of the email message. + +The :mod:`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 ``True`` from its +:meth:`is_multipart` method, and the subparts can be accessed via the +:meth:`get_payload` and :meth:`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 [#]_. + +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 :mod:`email` package's bundled parser and the +:class:`Message` class, so your custom parser can create message object trees +any way it finds necessary. + + +FeedParser API +^^^^^^^^^^^^^^ + +.. versionadded:: 2.4 + +The :class:`FeedParser`, imported from the :mod:`email.feedparser` module, +provides an API that is conducive to incremental parsing of email messages, such +as would be necessary when reading the text of an email message from a source +that can block (e.g. a socket). The :class:`FeedParser` can of course be used +to parse an email message fully contained in a string or a file, but the classic +:class:`Parser` API may be more convenient for such use cases. The semantics +and results of the two parser APIs are identical. + +The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch +of text until there's no more to feed it, then close the parser to retrieve the +root message object. The :class:`FeedParser` is extremely accurate when parsing +standards-compliant messages, and it does a very good job of parsing +non-compliant messages, providing information about how a message was deemed +broken. It will populate a message object's *defects* attribute with a list of +any problems it found in a message. See the :mod:`email.errors` module for the +list of defects that it can find. + +Here is the API for the :class:`FeedParser`: + + +.. class:: FeedParser([_factory]) + + Create a :class:`FeedParser` instance. Optional *_factory* is a no-argument + callable that will be called whenever a new message object is needed. It + defaults to the :class:`email.message.Message` class. + + +.. method:: FeedParser.feed(data) + + Feed the :class:`FeedParser` some more data. *data* should be a string + containing one or more lines. The lines can be partial and the + :class:`FeedParser` will stitch such partial lines together properly. The lines + in the string can have any of the common three line endings, carriage return, + newline, or carriage return and newline (they can even be mixed). + + +.. method:: FeedParser.close() + + Closing a :class:`FeedParser` completes the parsing of all previously fed data, + and returns the root message object. It is undefined what happens if you feed + more data to a closed :class:`FeedParser`. + + +Parser class API +^^^^^^^^^^^^^^^^ + +The :class:`Parser` class, imported from the :mod:`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 :mod:`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. + + +.. class:: Parser([_class]) + + The constructor for the :class:`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 + :class:`Message` (see :mod:`email.message`). The factory will be called without + arguments. + + The optional *strict* flag is ignored. + + .. deprecated:: 2.4 + Because the :class:`Parser` class is a backward compatible API wrapper + around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is + effectively non-strict. You should simply stop passing a *strict* flag to + the :class:`Parser` constructor. + + .. versionchanged:: 2.2.2 + The *strict* flag was added. + + .. versionchanged:: 2.4 + The *strict* flag was deprecated. + +The other public :class:`Parser` methods are: + + +.. method:: Parser.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 :meth:`readline` and + the :meth:`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 :meth:`parse` method. + + .. versionchanged:: 2.2.2 + The *headersonly* flag was added. + + +.. method:: Parser.parsestr(text[, headersonly]) + + Similar to the :meth:`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 :class:`StringIO` instance first and calling :meth:`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. + + .. versionchanged:: 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 :mod:`email` package namespace. + + +.. function:: 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 :class:`Parser` class constructor. + + .. versionchanged:: 2.2.2 + The *strict* flag was added. + + +.. function:: 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 :class:`Parser` class constructor. + + .. versionchanged:: 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) + + +Additional notes +^^^^^^^^^^^^^^^^ + +Here are some notes on the parsing semantics: + +* Most non-\ :mimetype:`multipart` type messages are parsed as a single message + object with a string payload. These objects will return ``False`` for + :meth:`is_multipart`. Their :meth:`get_payload` method will return a string + object. + +* All :mimetype:`multipart` type messages will be parsed as a container message + object with a list of sub-message objects for their payload. The outer + container message will return ``True`` for :meth:`is_multipart` and their + :meth:`get_payload` method will return the list of :class:`Message` subparts. + +* Most messages with a content type of :mimetype:`message/\*` (e.g. + :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be + parsed as container object containing a list payload of length 1. Their + :meth:`is_multipart` method will return ``True``. The single element in the + list payload will be a sub-message object. + +* Some non-standards compliant messages may not be internally consistent about + their :mimetype:`multipart`\ -edness. Such messages may have a + :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their + :meth:`is_multipart` method may return ``False``. If such messages were parsed + with the :class:`FeedParser`, they will have an instance of the + :class:`MultipartInvariantViolationDefect` class in their *defects* attribute + list. See :mod:`email.errors` for details. + +.. rubric:: Footnotes + +.. [#] 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. + |