R David Murray | 79cf3ba | 2012-05-27 17:10:36 -0400 | [diff] [blame] | 1 | :mod:`email.parser`: Parsing email messages |
| 2 | ------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 9 | from whole cloth by instantiating :class:`~email.message.Message` objects and |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 10 | stringing them together via :meth:`~email.message.Message.attach` and |
| 11 | :meth:`~email.message.Message.set_payload` calls, or they |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 12 | can be created by parsing a flat text representation of the email message. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
| 14 | The :mod:`email` package provides a standard parser that understands most email |
| 15 | document structures, including MIME documents. You can pass the parser a string |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 16 | or a file object, and the parser will return to you the root |
| 17 | :class:`~email.message.Message` instance of the object structure. For simple, |
| 18 | non-MIME messages the payload of this root object will likely be a string |
| 19 | containing the text of the message. For MIME messages, the root object will |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 20 | return ``True`` from its :meth:`~email.message.Message.is_multipart` method, and |
| 21 | the subparts can be accessed via the :meth:`~email.message.Message.get_payload` |
| 22 | and :meth:`~email.message.Message.walk` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | |
| 24 | There are actually two parser interfaces available for use, the classic |
| 25 | :class:`Parser` API and the incremental :class:`FeedParser` API. The classic |
| 26 | :class:`Parser` API is fine if you have the entire text of the message in memory |
| 27 | as a string, or if the entire message lives in a file on the file system. |
| 28 | :class:`FeedParser` is more appropriate for when you're reading the message from |
| 29 | a stream which might block waiting for more input (e.g. reading an email message |
| 30 | from a socket). The :class:`FeedParser` can consume and parse the message |
| 31 | incrementally, and only returns the root object when you close the parser [#]_. |
| 32 | |
| 33 | Note that the parser can be extended in limited ways, and of course you can |
| 34 | implement your own parser completely from scratch. There is no magical |
| 35 | connection between the :mod:`email` package's bundled parser and the |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 36 | :class:`~email.message.Message` class, so your custom parser can create message |
| 37 | object trees any way it finds necessary. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
| 39 | |
| 40 | FeedParser API |
| 41 | ^^^^^^^^^^^^^^ |
| 42 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 63 | .. class:: FeedParser(_factory=email.message.Message, *, policy=policy.compat32) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 69 | If *policy* is specified (it must be an instance of a :mod:`~email.policy` |
R David Murray | a83ade1 | 2014-05-08 10:05:47 -0400 | [diff] [blame] | 70 | class) use the rules it specifies to update the representation of the |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 71 | message. If *policy* is not set, use the :class:`compat32 |
| 72 | <email.policy.Compat32>` policy, which maintains backward compatibility with |
| 73 | the Python 3.2 version of the email package. For more information see the |
| 74 | :mod:`~email.policy` documentation. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 75 | |
| 76 | .. versionchanged:: 3.3 Added the *policy* keyword. |
| 77 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 78 | .. method:: feed(data) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 80 | Feed the :class:`FeedParser` some more data. *data* should be a string |
| 81 | containing one or more lines. The lines can be partial and the |
| 82 | :class:`FeedParser` will stitch such partial lines together properly. The |
| 83 | lines in the string can have any of the common three line endings, |
| 84 | carriage return, newline, or carriage return and newline (they can even be |
| 85 | mixed). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 87 | .. method:: close() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 89 | Closing a :class:`FeedParser` completes the parsing of all previously fed |
| 90 | data, and returns the root message object. It is undefined what happens |
| 91 | if you feed more data to a closed :class:`FeedParser`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 94 | .. class:: BytesFeedParser(_factory=email.message.Message) |
| 95 | |
| 96 | Works exactly like :class:`FeedParser` except that the input to the |
| 97 | :meth:`~FeedParser.feed` method must be bytes and not string. |
| 98 | |
| 99 | .. versionadded:: 3.2 |
| 100 | |
| 101 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | Parser class API |
| 103 | ^^^^^^^^^^^^^^^^ |
| 104 | |
| 105 | The :class:`Parser` class, imported from the :mod:`email.parser` module, |
| 106 | provides an API that can be used to parse a message when the complete contents |
| 107 | of the message are available in a string or file. The :mod:`email.parser` |
R David Murray | b35c850 | 2011-04-13 16:46:05 -0400 | [diff] [blame] | 108 | module also provides header-only parsers, called :class:`HeaderParser` and |
| 109 | :class:`BytesHeaderParser`, which can be used if you're only interested in the |
| 110 | headers of the message. :class:`HeaderParser` and :class:`BytesHeaderParser` |
| 111 | can be much faster in these situations, since they do not attempt to parse the |
| 112 | message body, instead setting the payload to the raw body as a string. They |
| 113 | have the same API as the :class:`Parser` and :class:`BytesParser` classes. |
| 114 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 115 | .. versionadded:: 3.3 |
| 116 | The BytesHeaderParser class. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 117 | |
| 118 | |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 119 | .. class:: Parser(_class=email.message.Message, *, policy=policy.compat32) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
| 121 | The constructor for the :class:`Parser` class takes an optional argument |
| 122 | *_class*. This must be a callable factory (such as a function or a class), and |
| 123 | it is used whenever a sub-message object needs to be created. It defaults to |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 124 | :class:`~email.message.Message` (see :mod:`email.message`). The factory will |
| 125 | be called without arguments. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 127 | If *policy* is specified (it must be an instance of a :mod:`~email.policy` |
R David Murray | a83ade1 | 2014-05-08 10:05:47 -0400 | [diff] [blame] | 128 | class) use the rules it specifies to update the representation of the |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 129 | message. If *policy* is not set, use the :class:`compat32 |
| 130 | <email.policy.Compat32>` policy, which maintains backward compatibility with |
| 131 | the Python 3.2 version of the email package. For more information see the |
| 132 | :mod:`~email.policy` documentation. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 133 | |
| 134 | .. versionchanged:: 3.3 |
| 135 | Removed the *strict* argument that was deprecated in 2.4. Added the |
| 136 | *policy* keyword. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 137 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 138 | The other public :class:`Parser` methods are: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | |
| 140 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 141 | .. method:: parse(fp, headersonly=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 143 | Read all the data from the file-like object *fp*, parse the resulting |
| 144 | text, and return the root message object. *fp* must support both the |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 145 | :meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read` |
| 146 | methods on file-like objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 148 | The text contained in *fp* must be formatted as a block of :rfc:`2822` |
| 149 | style headers and header continuation lines, optionally preceded by a |
| 150 | envelope header. The header block is terminated either by the end of the |
| 151 | data or by a blank line. Following the header block is the body of the |
| 152 | message (which may contain MIME-encoded subparts). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
Georg Brandl | c875d20 | 2012-01-29 15:38:47 +0100 | [diff] [blame] | 154 | Optional *headersonly* is a flag specifying whether to stop parsing after |
| 155 | reading the headers or not. The default is ``False``, meaning it parses |
| 156 | the entire contents of the file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 158 | .. method:: parsestr(text, headersonly=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 160 | Similar to the :meth:`parse` method, except it takes a string object |
| 161 | instead of a file-like object. Calling this method on a string is exactly |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 162 | equivalent to wrapping *text* in a :class:`~io.StringIO` instance first and |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 163 | calling :meth:`parse`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |
Georg Brandl | c875d20 | 2012-01-29 15:38:47 +0100 | [diff] [blame] | 165 | Optional *headersonly* is as with the :meth:`parse` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 167 | |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 168 | .. class:: BytesParser(_class=email.message.Message, *, policy=policy.compat32) |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 169 | |
| 170 | This class is exactly parallel to :class:`Parser`, but handles bytes input. |
| 171 | The *_class* and *strict* arguments are interpreted in the same way as for |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 172 | the :class:`Parser` constructor. |
| 173 | |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 174 | If *policy* is specified (it must be an instance of a :mod:`~email.policy` |
R David Murray | a83ade1 | 2014-05-08 10:05:47 -0400 | [diff] [blame] | 175 | class) use the rules it specifies to update the representation of the |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 176 | message. If *policy* is not set, use the :class:`compat32 |
| 177 | <email.policy.Compat32>` policy, which maintains backward compatibility with |
| 178 | the Python 3.2 version of the email package. For more information see the |
| 179 | :mod:`~email.policy` documentation. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 180 | |
| 181 | .. versionchanged:: 3.3 |
| 182 | Removed the *strict* argument. Added the *policy* keyword. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 183 | |
Jesus Cea | ca2e02c | 2014-09-22 00:43:39 +0200 | [diff] [blame] | 184 | .. method:: parse(fp, headersonly=False) |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 185 | |
| 186 | Read all the data from the binary file-like object *fp*, parse the |
| 187 | resulting bytes, and return the message object. *fp* must support |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 188 | both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read` |
| 189 | methods on file-like objects. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 190 | |
| 191 | The bytes contained in *fp* must be formatted as a block of :rfc:`2822` |
| 192 | style headers and header continuation lines, optionally preceded by a |
| 193 | envelope header. The header block is terminated either by the end of the |
| 194 | data or by a blank line. Following the header block is the body of the |
| 195 | message (which may contain MIME-encoded subparts, including subparts |
| 196 | with a :mailheader:`Content-Transfer-Encoding` of ``8bit``. |
| 197 | |
| 198 | Optional *headersonly* is a flag specifying whether to stop parsing after |
| 199 | reading the headers or not. The default is ``False``, meaning it parses |
| 200 | the entire contents of the file. |
| 201 | |
| 202 | .. method:: parsebytes(bytes, headersonly=False) |
| 203 | |
| 204 | Similar to the :meth:`parse` method, except it takes a byte string object |
| 205 | instead of a file-like object. Calling this method on a byte string is |
| 206 | exactly equivalent to wrapping *text* in a :class:`~io.BytesIO` instance |
| 207 | first and calling :meth:`parse`. |
| 208 | |
| 209 | Optional *headersonly* is as with the :meth:`parse` method. |
| 210 | |
| 211 | .. versionadded:: 3.2 |
| 212 | |
| 213 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 214 | Since creating a message object structure from a string or a file object is such |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 215 | a common task, four functions are provided as a convenience. They are available |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 216 | in the top-level :mod:`email` package namespace. |
| 217 | |
Georg Brandl | a971c65 | 2008-11-07 09:39:56 +0000 | [diff] [blame] | 218 | .. currentmodule:: email |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 219 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 220 | .. function:: message_from_string(s, _class=email.message.Message, *, \ |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 221 | policy=policy.compat32) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 222 | |
| 223 | Return a message object structure from a string. This is exactly equivalent to |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 224 | ``Parser().parsestr(s)``. *_class* and *policy* are interpreted as |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 225 | with the :class:`~email.parser.Parser` class constructor. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 226 | |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 227 | .. versionchanged:: 3.3 |
| 228 | Removed the *strict* argument. Added the *policy* keyword. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 229 | |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 230 | .. function:: message_from_bytes(s, _class=email.message.Message, *, \ |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 231 | policy=policy.compat32) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 233 | Return a message object structure from a byte string. This is exactly |
| 234 | equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 235 | *strict* are interpreted as with the :class:`~email.parser.Parser` class |
| 236 | constructor. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 237 | |
| 238 | .. versionadded:: 3.2 |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 239 | .. versionchanged:: 3.3 |
| 240 | Removed the *strict* argument. Added the *policy* keyword. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 241 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 242 | .. function:: message_from_file(fp, _class=email.message.Message, *, \ |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 243 | policy=policy.compat32) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 244 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 245 | Return a message object structure tree from an open :term:`file object`. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 246 | This is exactly equivalent to ``Parser().parse(fp)``. *_class* |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 247 | and *policy* are interpreted as with the :class:`~email.parser.Parser` class |
| 248 | constructor. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 250 | .. versionchanged:: |
| 251 | Removed the *strict* argument. Added the *policy* keyword. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 252 | |
| 253 | .. function:: message_from_binary_file(fp, _class=email.message.Message, *, \ |
R David Murray | e252446 | 2014-05-06 21:33:18 -0400 | [diff] [blame] | 254 | policy=policy.compat32) |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 255 | |
| 256 | Return a message object structure tree from an open binary :term:`file |
| 257 | object`. This is exactly equivalent to ``BytesParser().parse(fp)``. |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 258 | *_class* and *policy* are interpreted as with the |
| 259 | :class:`~email.parser.Parser` class constructor. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 260 | |
| 261 | .. versionadded:: 3.2 |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 262 | .. versionchanged:: 3.3 |
| 263 | Removed the *strict* argument. Added the *policy* keyword. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 264 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 265 | Here's an example of how you might use this at an interactive Python prompt:: |
| 266 | |
| 267 | >>> import email |
Andrew Svetlov | 439e17f | 2012-08-12 15:16:42 +0300 | [diff] [blame] | 268 | >>> msg = email.message_from_string(myString) # doctest: +SKIP |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 269 | |
| 270 | |
| 271 | Additional notes |
| 272 | ^^^^^^^^^^^^^^^^ |
| 273 | |
| 274 | Here are some notes on the parsing semantics: |
| 275 | |
| 276 | * Most non-\ :mimetype:`multipart` type messages are parsed as a single message |
| 277 | object with a string payload. These objects will return ``False`` for |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 278 | :meth:`~email.message.Message.is_multipart`. Their |
| 279 | :meth:`~email.message.Message.get_payload` method will return a string object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 280 | |
| 281 | * All :mimetype:`multipart` type messages will be parsed as a container message |
| 282 | object with a list of sub-message objects for their payload. The outer |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 283 | container message will return ``True`` for |
| 284 | :meth:`~email.message.Message.is_multipart` and their |
| 285 | :meth:`~email.message.Message.get_payload` method will return the list of |
| 286 | :class:`~email.message.Message` subparts. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 287 | |
| 288 | * Most messages with a content type of :mimetype:`message/\*` (e.g. |
| 289 | :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be |
| 290 | parsed as container object containing a list payload of length 1. Their |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 291 | :meth:`~email.message.Message.is_multipart` method will return ``True``. |
| 292 | The single element in the list payload will be a sub-message object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
| 294 | * Some non-standards compliant messages may not be internally consistent about |
| 295 | their :mimetype:`multipart`\ -edness. Such messages may have a |
| 296 | :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 297 | :meth:`~email.message.Message.is_multipart` method may return ``False``. |
| 298 | If such messages were parsed with the :class:`~email.parser.FeedParser`, |
| 299 | they will have an instance of the |
| 300 | :class:`~email.errors.MultipartInvariantViolationDefect` class in their |
| 301 | *defects* attribute list. See :mod:`email.errors` for details. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 302 | |
| 303 | .. rubric:: Footnotes |
| 304 | |
| 305 | .. [#] As of email package version 3.0, introduced in Python 2.4, the classic |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 306 | :class:`~email.parser.Parser` was re-implemented in terms of the |
| 307 | :class:`~email.parser.FeedParser`, so the semantics and results are |
| 308 | identical between the two parsers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 309 | |