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