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