Doc/library/email.parser.rst

   1 :mod:`email`: Parsing email messages
   2 ------------------------------------
   3
   4 .. module:: email.parser
   5    :synopsis: Parse flat text email messages to produce a message object structure.
   6
   7
   8 Message object structures can be created in one of two ways: they can be created
   9 from whole cloth by instantiating :class:`Message` objects and stringing them
  10 together via :meth:`attach` and :meth:`set_payload` calls, or they can be
  11 created by parsing a flat text representation of the email message.
  12
  13 The :mod:`email` package provides a standard parser that understands most email
  14 document structures, including MIME documents.  You can pass the parser a string
  15 or a file object, and the parser will return to you the root :class:`Message`
  16 instance of the object structure.  For simple, non-MIME messages the payload of
  17 this root object will likely be a string containing the text of the message.
  18 For MIME messages, the root object will return ``True`` from its
  19 :meth:`is_multipart` method, and the subparts can be accessed via the
  20 :meth:`get_payload` and :meth:`walk` methods.
  21
  22 There are actually two parser interfaces available for use, the classic
  23 :class:`Parser` API and the incremental :class:`FeedParser` API.  The classic
  24 :class:`Parser` API is fine if you have the entire text of the message in memory
  25 as a string, or if the entire message lives in a file on the file system.
  26 :class:`FeedParser` is more appropriate for when you're reading the message from
  27 a stream which might block waiting for more input (e.g. reading an email message
  28 from a socket).  The :class:`FeedParser` can consume and parse the message
  29 incrementally, and only returns the root object when you close the parser [#]_.
  30
  31 Note that the parser can be extended in limited ways, and of course you can
  32 implement your own parser completely from scratch.  There is no magical
  33 connection between the :mod:`email` package's bundled parser and the
  34 :class:`Message` class, so your custom parser can create message object trees
  35 any way it finds necessary.
  36
  37
  38 FeedParser API
  39 ^^^^^^^^^^^^^^
  40
  41 .. versionadded:: 2.4
  42
  43 The :class:`FeedParser`, imported from the :mod:`email.feedparser` module,
  44 provides an API that is conducive to incremental parsing of email messages, such
  45 as would be necessary when reading the text of an email message from a source
  46 that can block (e.g. a socket).  The :class:`FeedParser` can of course be used
  47 to parse an email message fully contained in a string or a file, but the classic
  48 :class:`Parser` API may be more convenient for such use cases.  The semantics
  49 and results of the two parser APIs are identical.
  50
  51 The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch
  52 of text until there's no more to feed it, then close the parser to retrieve the
  53 root message object.  The :class:`FeedParser` is extremely accurate when parsing
  54 standards-compliant messages, and it does a very good job of parsing
  55 non-compliant messages, providing information about how a message was deemed
  56 broken.  It will populate a message object's *defects* attribute with a list of
  57 any problems it found in a message.  See the :mod:`email.errors` module for the
  58 list of defects that it can find.
  59
  60 Here is the API for the :class:`FeedParser`:
  61
  62
  63 .. class:: FeedParser([_factory])
  64
  65    Create a :class:`FeedParser` instance.  Optional *_factory* is a no-argument
  66    callable that will be called whenever a new message object is needed.  It
  67    defaults to the :class:`email.message.Message` class.
  68
  69
  70 .. method:: FeedParser.feed(data)
  71
  72    Feed the :class:`FeedParser` some more data.  *data* should be a string
  73    containing one or more lines.  The lines can be partial and the
  74    :class:`FeedParser` will stitch such partial lines together properly.  The lines
  75    in the string can have any of the common three line endings, carriage return,
  76    newline, or carriage return and newline (they can even be mixed).
  77
  78
  79 .. method:: FeedParser.close()
  80
  81    Closing a :class:`FeedParser` completes the parsing of all previously fed data,
  82    and returns the root message object.  It is undefined what happens if you feed
  83    more data to a closed :class:`FeedParser`.
  84
  85
  86 Parser class API
  87 ^^^^^^^^^^^^^^^^
  88
  89 The :class:`Parser` class, imported from the :mod:`email.parser` module,
  90 provides an API that can be used to parse a message when the complete contents
  91 of the message are available in a string or file.  The :mod:`email.parser`
  92 module also provides a second class, called :class:`HeaderParser` which can be
  93 used if you're only interested in the headers of the message.
  94 :class:`HeaderParser` can be much faster in these situations, since it does not
  95 attempt to parse the message body, instead setting the payload to the raw body
  96 as a string. :class:`HeaderParser` has the same API as the :class:`Parser`
  97 class.
  98
  99
 100 .. class:: Parser([_class])
 101
 102    The constructor for the :class:`Parser` class takes an optional argument
 103    *_class*.  This must be a callable factory (such as a function or a class), and
 104    it is used whenever a sub-message object needs to be created.  It defaults to
 105    :class:`Message` (see :mod:`email.message`).  The factory will be called without
 106    arguments.
 107
 108    The optional *strict* flag is ignored.
 109
 110    .. deprecated:: 2.4
 111       Because the :class:`Parser` class is a backward compatible API wrapper
 112       around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is
 113       effectively non-strict.  You should simply stop passing a *strict* flag to
 114       the :class:`Parser` constructor.
 115
 116    .. versionchanged:: 2.2.2
 117       The *strict* flag was added.
 118
 119    .. versionchanged:: 2.4
 120       The *strict* flag was deprecated.
 121
 122 The other public :class:`Parser` methods are:
 123
 124
 125 .. method:: Parser.parse(fp[, headersonly])
 126
 127    Read all the data from the file-like object *fp*, parse the resulting text, and
 128    return the root message object.  *fp* must support both the :meth:`readline` and
 129    the :meth:`read` methods on file-like objects.
 130
 131    The text contained in *fp* must be formatted as a block of :rfc:`2822` style
 132    headers and header continuation lines, optionally preceded by a envelope
 133    header.  The header block is terminated either by the end of the data or by a
 134    blank line.  Following the header block is the body of the message (which may
 135    contain MIME-encoded subparts).
 136
 137    Optional *headersonly* is as with the :meth:`parse` method.
 138
 139    .. versionchanged:: 2.2.2
 140       The *headersonly* flag was added.
 141
 142
 143 .. method:: Parser.parsestr(text[, headersonly])
 144
 145    Similar to the :meth:`parse` method, except it takes a string object instead of
 146    a file-like object.  Calling this method on a string is exactly equivalent to
 147    wrapping *text* in a :class:`StringIO` instance first and calling :meth:`parse`.
 148
 149    Optional *headersonly* is a flag specifying whether to stop parsing after
 150    reading the headers or not.  The default is ``False``, meaning it parses the
 151    entire contents of the file.
 152
 153    .. versionchanged:: 2.2.2
 154       The *headersonly* flag was added.
 155
 156 Since creating a message object structure from a string or a file object is such
 157 a common task, two functions are provided as a convenience.  They are available
 158 in the top-level :mod:`email` package namespace.
 159
 160
 161 .. function:: message_from_string(s[, _class[, strict]])
 162
 163    Return a message object structure from a string.  This is exactly equivalent to
 164    ``Parser().parsestr(s)``.  Optional *_class* and *strict* are interpreted as
 165    with the :class:`Parser` class constructor.
 166
 167    .. versionchanged:: 2.2.2
 168       The *strict* flag was added.
 169
 170
 171 .. function:: message_from_file(fp[, _class[, strict]])
 172
 173    Return a message object structure tree from an open file object.  This is
 174    exactly equivalent to ``Parser().parse(fp)``.  Optional *_class* and *strict*
 175    are interpreted as with the :class:`Parser` class constructor.
 176
 177    .. versionchanged:: 2.2.2
 178       The *strict* flag was added.
 179
 180 Here's an example of how you might use this at an interactive Python prompt::
 181
 182    >>> import email
 183    >>> msg = email.message_from_string(myString)
 184
 185
 186 Additional notes
 187 ^^^^^^^^^^^^^^^^
 188
 189 Here are some notes on the parsing semantics:
 190
 191 * Most non-\ :mimetype:`multipart` type messages are parsed as a single message
 192   object with a string payload.  These objects will return ``False`` for
 193   :meth:`is_multipart`.  Their :meth:`get_payload` method will return a string
 194   object.
 195
 196 * All :mimetype:`multipart` type messages will be parsed as a container message
 197   object with a list of sub-message objects for their payload.  The outer
 198   container message will return ``True`` for :meth:`is_multipart` and their
 199   :meth:`get_payload` method will return the list of :class:`Message` subparts.
 200
 201 * Most messages with a content type of :mimetype:`message/\*` (e.g.
 202   :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
 203   parsed as container object containing a list payload of length 1.  Their
 204   :meth:`is_multipart` method will return ``True``.  The single element in the
 205   list payload will be a sub-message object.
 206
 207 * Some non-standards compliant messages may not be internally consistent about
 208   their :mimetype:`multipart`\ -edness.  Such messages may have a
 209   :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
 210   :meth:`is_multipart` method may return ``False``.  If such messages were parsed
 211   with the :class:`FeedParser`, they will have an instance of the
 212   :class:`MultipartInvariantViolationDefect` class in their *defects* attribute
 213   list.  See :mod:`email.errors` for details.
 214
 215 .. rubric:: Footnotes
 216
 217 .. [#] As of email package version 3.0, introduced in Python 2.4, the classic
 218    :class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so the
 219    semantics and results are identical between the two parsers.
 220