Doc/lib/emailiter.tex

   1 \declaremodule{standard}{email.Iterators}
   2 \modulesynopsis{Iterate over a  message object tree.}
   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\optional{, decode}}
  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
  17 Optional \var{decode} is passed through to \method{Message.get_payload()}.
  18 \end{funcdesc}
  19
  20 \begin{funcdesc}{typed_subpart_iterator}{msg\optional{,
  21     maintype\optional{, subtype}}}
  22 This iterates over all the subparts of \var{msg}, returning only those
  23 subparts that match the MIME type specified by \var{maintype} and
  24 \var{subtype}.
  25
  26 Note that \var{subtype} is optional; if omitted, then subpart MIME
  27 type matching is done only with the main type.  \var{maintype} is
  28 optional too; it defaults to \mimetype{text}.
  29
  30 Thus, by default \function{typed_subpart_iterator()} returns each
  31 subpart that has a MIME type of \mimetype{text/*}.
  32 \end{funcdesc}
  33
  34 The following function has been added as a useful debugging tool.  It
  35 should \emph{not} be considered part of the supported public interface
  36 for the package.
  37
  38 \begin{funcdesc}{_structure}{msg\optional{, fp\optional{, level}}}
  39 Prints an indented representation of the content types of the
  40 message object structure.  For example:
  41
  42 \begin{verbatim}
  43 >>> msg = email.message_from_file(somefile)
  44 >>> _structure(msg)
  45 multipart/mixed
  46     text/plain
  47     text/plain
  48     multipart/digest
  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         message/rfc822
  58             text/plain
  59     text/plain
  60 \end{verbatim}
  61
  62 Optional \var{fp} is a file-like object to print the output to.  It
  63 must be suitable for Python's extended print statement.  \var{level}
  64 is used internally.
  65 \end{funcdesc}