Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 1 | \declaremodule{standard}{email.Iterators} |
| 2 | \modulesynopsis{Iterate over a message object tree.} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 3 | |
| 4 | Iterating over a message object tree is fairly easy with the |
| 5 | \method{Message.walk()} method. The \module{email.Iterators} module |
| 6 | provides some useful higher level iterations over message object |
| 7 | trees. |
| 8 | |
| 9 | \begin{funcdesc}{body_line_iterator}{msg} |
| 10 | This iterates over all the payloads in all the subparts of \var{msg}, |
| 11 | returning the string payloads line-by-line. It skips over all the |
| 12 | subpart headers, and it skips over any subpart with a payload that |
| 13 | isn't a Python string. This is somewhat equivalent to reading the |
| 14 | flat text representation of the message from a file using |
| 15 | \method{readline()}, skipping over all the intervening headers. |
| 16 | \end{funcdesc} |
| 17 | |
| 18 | \begin{funcdesc}{typed_subpart_iterator}{msg\optional{, |
| 19 | maintype\optional{, subtype}}} |
| 20 | This iterates over all the subparts of \var{msg}, returning only those |
| 21 | subparts that match the MIME type specified by \var{maintype} and |
| 22 | \var{subtype}. |
| 23 | |
| 24 | Note that \var{subtype} is optional; if omitted, then subpart MIME |
| 25 | type matching is done only with the main type. \var{maintype} is |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 26 | optional too; it defaults to \mimetype{text}. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 27 | |
| 28 | Thus, by default \function{typed_subpart_iterator()} returns each |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 29 | subpart that has a MIME type of \mimetype{text/*}. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 30 | \end{funcdesc} |
| 31 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 32 | The following function has been added as a useful debugging tool. It |
| 33 | should \emph{not} be considered part of the supported public interface |
| 34 | for the package. |
| 35 | |
| 36 | \begin{funcdesc}{_structure}{msg\optional{, fp\optional{, level}}} |
| 37 | Prints an indented representation of the content types of the |
| 38 | message object structure. For example: |
| 39 | |
| 40 | \begin{verbatim} |
| 41 | >>> msg = email.message_from_file(somefile) |
| 42 | >>> _structure(msg) |
| 43 | multipart/mixed |
| 44 | text/plain |
| 45 | text/plain |
| 46 | multipart/digest |
| 47 | message/rfc822 |
| 48 | text/plain |
| 49 | message/rfc822 |
| 50 | text/plain |
| 51 | message/rfc822 |
| 52 | text/plain |
| 53 | message/rfc822 |
| 54 | text/plain |
| 55 | message/rfc822 |
| 56 | text/plain |
| 57 | text/plain |
| 58 | \end{verbatim} |
| 59 | |
| 60 | Optional \var{fp} is a file-like object to print the output to. It |
| 61 | must be suitable for Python's extended print statement. \var{level} |
| 62 | is used internally. |
| 63 | \end{funcdesc} |