Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(5)

Side by Side Diff: Doc/library/email.parser.rst

Issue 18761: Fix internal doc references for the email package (Closed)
Patch Set: Created 6 years, 5 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « Doc/library/email.mime.rst ('k') | Doc/library/email.policy.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`email.parser`: Parsing email messages 1 :mod:`email.parser`: Parsing email messages
2 ------------------------------------------- 2 -------------------------------------------
3 3
4 .. module:: email.parser 4 .. module:: email.parser
5 :synopsis: Parse flat text email messages to produce a message object structu re. 5 :synopsis: Parse flat text email messages to produce a message object structu re.
6 6
7 7
8 Message object structures can be created in one of two ways: they can be created 8 Message object structures can be created in one of two ways: they can be created
9 from whole cloth by instantiating :class:`~email.message.Message` objects and 9 from whole cloth by instantiating :class:`~email.message.Message` objects and
10 stringing them together via :meth:`attach` and :meth:`set_payload` calls, or the y 10 stringing them together via :meth:`~email.message.Message.attach` and
11 :meth:`~email.message.Message.set_payload` calls, or they
11 can be created by parsing a flat text representation of the email message. 12 can be created by parsing a flat text representation of the email message.
12 13
13 The :mod:`email` package provides a standard parser that understands most email 14 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 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 16 or a file object, and the parser will return to you the root
16 :class:`~email.message.Message` instance of the object structure. For simple, 17 :class:`~email.message.Message` instance of the object structure. For simple,
17 non-MIME messages the payload of this root object will likely be a string 18 non-MIME messages the payload of this root object will likely be a string
18 containing the text of the message. For MIME messages, the root object will 19 containing the text of the message. For MIME messages, the root object will
19 return ``True`` from its :meth:`is_multipart` method, and the subparts can be 20 return ``True`` from its :meth:`~email.message.Message.is_multipart` method, and
20 accessed via the :meth:`get_payload` and :meth:`walk` methods. 21 the subparts can be accessed via the :meth:`~email.message.Message.get_payload`
22 and :meth:`~email.message.Message.walk` methods.
21 23
22 There are actually two parser interfaces available for use, the classic 24 There are actually two parser interfaces available for use, the classic
23 :class:`Parser` API and the incremental :class:`FeedParser` API. The classic 25 :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 26 :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. 27 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 28 :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 29 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 30 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 [#]_. 31 incrementally, and only returns the root object when you close the parser [#]_.
30 32
(...skipping 96 matching lines...) Expand 10 before | Expand all | Expand 10 after
127 Removed the *strict* argument that was deprecated in 2.4. Added the 129 Removed the *strict* argument that was deprecated in 2.4. Added the
128 *policy* keyword. 130 *policy* keyword.
129 131
130 The other public :class:`Parser` methods are: 132 The other public :class:`Parser` methods are:
131 133
132 134
133 .. method:: parse(fp, headersonly=False) 135 .. method:: parse(fp, headersonly=False)
134 136
135 Read all the data from the file-like object *fp*, parse the resulting 137 Read all the data from the file-like object *fp*, parse the resulting
136 text, and return the root message object. *fp* must support both the 138 text, and return the root message object. *fp* must support both the
137 :meth:`readline` and the :meth:`read` methods on file-like objects. 139 :meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read`
140 methods on file-like objects.
138 141
139 The text contained in *fp* must be formatted as a block of :rfc:`2822` 142 The text contained in *fp* must be formatted as a block of :rfc:`2822`
140 style headers and header continuation lines, optionally preceded by a 143 style headers and header continuation lines, optionally preceded by a
141 envelope header. The header block is terminated either by the end of the 144 envelope header. The header block is terminated either by the end of the
142 data or by a blank line. Following the header block is the body of the 145 data or by a blank line. Following the header block is the body of the
143 message (which may contain MIME-encoded subparts). 146 message (which may contain MIME-encoded subparts).
144 147
145 Optional *headersonly* is a flag specifying whether to stop parsing after 148 Optional *headersonly* is a flag specifying whether to stop parsing after
146 reading the headers or not. The default is ``False``, meaning it parses 149 reading the headers or not. The default is ``False``, meaning it parses
147 the entire contents of the file. 150 the entire contents of the file.
(...skipping 18 matching lines...) Expand all
166 controls a number of aspects of the parser's operation. The default 169 controls a number of aspects of the parser's operation. The default
167 policy maintains backward compatibility. 170 policy maintains backward compatibility.
168 171
169 .. versionchanged:: 3.3 172 .. versionchanged:: 3.3
170 Removed the *strict* argument. Added the *policy* keyword. 173 Removed the *strict* argument. Added the *policy* keyword.
171 174
172 .. method:: parse(fp, headeronly=False) 175 .. method:: parse(fp, headeronly=False)
173 176
174 Read all the data from the binary file-like object *fp*, parse the 177 Read all the data from the binary file-like object *fp*, parse the
175 resulting bytes, and return the message object. *fp* must support 178 resulting bytes, and return the message object. *fp* must support
176 both the :meth:`readline` and the :meth:`read` methods on file-like 179 both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
177 objects. 180 methods on file-like objects.
178 181
179 The bytes contained in *fp* must be formatted as a block of :rfc:`2822` 182 The bytes contained in *fp* must be formatted as a block of :rfc:`2822`
180 style headers and header continuation lines, optionally preceded by a 183 style headers and header continuation lines, optionally preceded by a
181 envelope header. The header block is terminated either by the end of the 184 envelope header. The header block is terminated either by the end of the
182 data or by a blank line. Following the header block is the body of the 185 data or by a blank line. Following the header block is the body of the
183 message (which may contain MIME-encoded subparts, including subparts 186 message (which may contain MIME-encoded subparts, including subparts
184 with a :mailheader:`Content-Transfer-Encoding` of ``8bit``. 187 with a :mailheader:`Content-Transfer-Encoding` of ``8bit``.
185 188
186 Optional *headersonly* is a flag specifying whether to stop parsing after 189 Optional *headersonly* is a flag specifying whether to stop parsing after
187 reading the headers or not. The default is ``False``, meaning it parses 190 reading the headers or not. The default is ``False``, meaning it parses
(...skipping 15 matching lines...) Expand all
203 a common task, four functions are provided as a convenience. They are available 206 a common task, four functions are provided as a convenience. They are available
204 in the top-level :mod:`email` package namespace. 207 in the top-level :mod:`email` package namespace.
205 208
206 .. currentmodule:: email 209 .. currentmodule:: email
207 210
208 .. function:: message_from_string(s, _class=email.message.Message, *, \ 211 .. function:: message_from_string(s, _class=email.message.Message, *, \
209 policy=policy.default) 212 policy=policy.default)
210 213
211 Return a message object structure from a string. This is exactly equivalent to 214 Return a message object structure from a string. This is exactly equivalent to
212 ``Parser().parsestr(s)``. *_class* and *policy* are interpreted as 215 ``Parser().parsestr(s)``. *_class* and *policy* are interpreted as
213 with the :class:`Parser` class constructor. 216 with the :class:`~email.parser.Parser` class constructor.
214 217
215 .. versionchanged:: 3.3 218 .. versionchanged:: 3.3
216 Removed the *strict* argument. Added the *policy* keyword. 219 Removed the *strict* argument. Added the *policy* keyword.
217 220
218 .. function:: message_from_bytes(s, _class=email.message.Message, *, \ 221 .. function:: message_from_bytes(s, _class=email.message.Message, *, \
219 policy=policy.default) 222 policy=policy.default)
220 223
221 Return a message object structure from a byte string. This is exactly 224 Return a message object structure from a byte string. This is exactly
222 equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and 225 equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and
223 *strict* are interpreted as with the :class:`Parser` class constructor. 226 *strict* are interpreted as with the :class:`~email.parser.Parser` class
227 constructor.
224 228
225 .. versionadded:: 3.2 229 .. versionadded:: 3.2
226 .. versionchanged:: 3.3 230 .. versionchanged:: 3.3
227 Removed the *strict* argument. Added the *policy* keyword. 231 Removed the *strict* argument. Added the *policy* keyword.
228 232
229 .. function:: message_from_file(fp, _class=email.message.Message, *, \ 233 .. function:: message_from_file(fp, _class=email.message.Message, *, \
230 policy=policy.default) 234 policy=policy.default)
231 235
232 Return a message object structure tree from an open :term:`file object`. 236 Return a message object structure tree from an open :term:`file object`.
233 This is exactly equivalent to ``Parser().parse(fp)``. *_class* 237 This is exactly equivalent to ``Parser().parse(fp)``. *_class*
234 and *policy* are interpreted as with the :class:`Parser` class constructor. 238 and *policy* are interpreted as with the :class:`~email.parser.Parser` class
239 constructor.
235 240
236 .. versionchanged:: 241 .. versionchanged::
237 Removed the *strict* argument. Added the *policy* keyword. 242 Removed the *strict* argument. Added the *policy* keyword.
238 243
239 .. function:: message_from_binary_file(fp, _class=email.message.Message, *, \ 244 .. function:: message_from_binary_file(fp, _class=email.message.Message, *, \
240 policy=policy.default) 245 policy=policy.default)
241 246
242 Return a message object structure tree from an open binary :term:`file 247 Return a message object structure tree from an open binary :term:`file
243 object`. This is exactly equivalent to ``BytesParser().parse(fp)``. 248 object`. This is exactly equivalent to ``BytesParser().parse(fp)``.
244 *_class* and *policy* are interpreted as with the :class:`Parser` 249 *_class* and *policy* are interpreted as with the
245 class constructor. 250 :class:`~email.parser.Parser` class constructor.
246 251
247 .. versionadded:: 3.2 252 .. versionadded:: 3.2
248 .. versionchanged:: 3.3 253 .. versionchanged:: 3.3
249 Removed the *strict* argument. Added the *policy* keyword. 254 Removed the *strict* argument. Added the *policy* keyword.
250 255
251 Here's an example of how you might use this at an interactive Python prompt:: 256 Here's an example of how you might use this at an interactive Python prompt::
252 257
253 >>> import email 258 >>> import email
254 >>> msg = email.message_from_string(myString) # doctest: +SKIP 259 >>> msg = email.message_from_string(myString) # doctest: +SKIP
255 260
256 261
257 Additional notes 262 Additional notes
258 ^^^^^^^^^^^^^^^^ 263 ^^^^^^^^^^^^^^^^
259 264
260 Here are some notes on the parsing semantics: 265 Here are some notes on the parsing semantics:
261 266
262 * Most non-\ :mimetype:`multipart` type messages are parsed as a single message 267 * Most non-\ :mimetype:`multipart` type messages are parsed as a single message
263 object with a string payload. These objects will return ``False`` for 268 object with a string payload. These objects will return ``False`` for
264 :meth:`is_multipart`. Their :meth:`get_payload` method will return a string 269 :meth:`~email.message.Message.is_multipart`. Their
265 object. 270 :meth:`~email.message.Message.get_payload` method will return a string object.
266 271
267 * All :mimetype:`multipart` type messages will be parsed as a container message 272 * All :mimetype:`multipart` type messages will be parsed as a container message
268 object with a list of sub-message objects for their payload. The outer 273 object with a list of sub-message objects for their payload. The outer
269 container message will return ``True`` for :meth:`is_multipart` and their 274 container message will return ``True`` for
270 :meth:`get_payload` method will return the list of :class:`~email.message.Mess age` 275 :meth:`~email.message.Message.is_multipart` and their
271 subparts. 276 :meth:`~email.message.Message.get_payload` method will return the list of
277 :class:`~email.message.Message` subparts.
272 278
273 * Most messages with a content type of :mimetype:`message/\*` (e.g. 279 * Most messages with a content type of :mimetype:`message/\*` (e.g.
274 :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be 280 :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
275 parsed as container object containing a list payload of length 1. Their 281 parsed as container object containing a list payload of length 1. Their
276 :meth:`is_multipart` method will return ``True``. The single element in the 282 :meth:`~email.message.Message.is_multipart` method will return ``True``.
277 list payload will be a sub-message object. 283 The single element in the list payload will be a sub-message object.
278 284
279 * Some non-standards compliant messages may not be internally consistent about 285 * Some non-standards compliant messages may not be internally consistent about
280 their :mimetype:`multipart`\ -edness. Such messages may have a 286 their :mimetype:`multipart`\ -edness. Such messages may have a
281 :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their 287 :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
282 :meth:`is_multipart` method may return ``False``. If such messages were parse d 288 :meth:`~email.message.Message.is_multipart` method may return ``False``.
283 with the :class:`FeedParser`, they will have an instance of the 289 If such messages were parsed with the :class:`~email.parser.FeedParser`,
284 :class:`MultipartInvariantViolationDefect` class in their *defects* attribute 290 they will have an instance of the
285 list. See :mod:`email.errors` for details. 291 :class:`~email.errors.MultipartInvariantViolationDefect` class in their
292 *defects* attribute list. See :mod:`email.errors` for details.
286 293
287 .. rubric:: Footnotes 294 .. rubric:: Footnotes
288 295
289 .. [#] As of email package version 3.0, introduced in Python 2.4, the classic 296 .. [#] As of email package version 3.0, introduced in Python 2.4, the classic
290 :class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so th e 297 :class:`~email.parser.Parser` was re-implemented in terms of the
291 semantics and results are identical between the two parsers. 298 :class:`~email.parser.FeedParser`, so the semantics and results are
299 identical between the two parsers.
292 300
OLDNEW
« no previous file with comments | « Doc/library/email.mime.rst ('k') | Doc/library/email.policy.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+