1 :mod:`email`: Iterators

     2 -----------------------

     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 

    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 

    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 

    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