/Doc/library/email.iterators.rst

 1:mod:`email`: Iterators
 2-----------------------
 3
 4.. module:: email.iterators
 5   :synopsis: Iterate over a  message object tree.
 6
 7
 8Iterating over a message object tree is fairly easy with the
 9:meth:`Message.walk` method.  The :mod:`email.iterators` module provides some
10useful higher level iterations over message object trees.
11
12
13.. function:: body_line_iterator(msg[, decode])
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
24.. function:: typed_subpart_iterator(msg[, maintype[, subtype]])
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
36The 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
40.. function:: _structure(msg[, fp[, level]])
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
63   Optional *fp* is a file-like object to print the output to.  It must be suitable
64   for Python's extended print statement.  *level* is used internally.
65