| 1 |
:mod:`!email.iterators`: Iterators |
| 2 |
---------------------------------- |
| 3 |
|
| 4 |
.. module:: email.iterators |
| 5 |
:synopsis: Iterate over a message object tree. |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/email/iterators.py` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
Iterating over a message object tree is fairly easy with the |
| 12 |
:meth:`Message.walk <email.message.Message.walk>` method. The |
| 13 |
:mod:`!email.iterators` module provides some useful higher level iterations over |
| 14 |
message object trees. |
| 15 |
|
| 16 |
|
| 17 |
.. function:: body_line_iterator(msg, decode=False) |
| 18 |
|
| 19 |
This iterates over all the payloads in all the subparts of *msg*, returning the |
| 20 |
string payloads line-by-line. It skips over all the subpart headers, and it |
| 21 |
skips over any subpart with a payload that isn't a Python string. This is |
| 22 |
somewhat equivalent to reading the flat text representation of the message from |
| 23 |
a file using :meth:`~io.TextIOBase.readline`, skipping over all the |
| 24 |
intervening headers. |
| 25 |
|
| 26 |
Optional *decode* is passed through to :meth:`Message.get_payload |
| 27 |
<email.message.Message.get_payload>`. |
| 28 |
|
| 29 |
|
| 30 |
.. function:: typed_subpart_iterator(msg, maintype='text', subtype=None) |
| 31 |
|
| 32 |
This iterates over all the subparts of *msg*, returning only those subparts that |
| 33 |
match the MIME type specified by *maintype* and *subtype*. |
| 34 |
|
| 35 |
Note that *subtype* is optional; if omitted, then subpart MIME type matching is |
| 36 |
done only with the main type. *maintype* is optional too; it defaults to |
| 37 |
:mimetype:`text`. |
| 38 |
|
| 39 |
Thus, by default :func:`typed_subpart_iterator` returns each subpart that has a |
| 40 |
MIME type of :mimetype:`text/\*`. |
| 41 |
|
| 42 |
|
| 43 |
The following function has been added as a useful debugging tool. It should |
| 44 |
*not* be considered part of the supported public interface for the package. |
| 45 |
|
| 46 |
.. function:: _structure(msg, fp=None, level=0, include_default=False) |
| 47 |
|
| 48 |
Prints an indented representation of the content types of the message object |
| 49 |
structure. For example: |
| 50 |
|
| 51 |
.. testsetup:: |
| 52 |
|
| 53 |
import email |
| 54 |
from email.iterators import _structure |
| 55 |
somefile = open('../Lib/test/test_email/data/msg_02.txt') |
| 56 |
|
| 57 |
.. doctest:: |
| 58 |
|
| 59 |
>>> msg = email.message_from_file(somefile) |
| 60 |
>>> _structure(msg) |
| 61 |
multipart/mixed |
| 62 |
text/plain |
| 63 |
text/plain |
| 64 |
multipart/digest |
| 65 |
message/rfc822 |
| 66 |
text/plain |
| 67 |
message/rfc822 |
| 68 |
text/plain |
| 69 |
message/rfc822 |
| 70 |
text/plain |
| 71 |
message/rfc822 |
| 72 |
text/plain |
| 73 |
message/rfc822 |
| 74 |
text/plain |
| 75 |
text/plain |
| 76 |
|
| 77 |
.. testcleanup:: |
| 78 |
|
| 79 |
somefile.close() |
| 80 |
|
| 81 |
Optional *fp* is a file-like object to print the output to. It must be |
| 82 |
suitable for Python's :func:`print` function. *level* is used internally. |
| 83 |
*include_default*, if true, prints the default type as well. |