Doc/lib/emailgenerator.tex

   1 \declaremodule{standard}{email.Generator}
   2 \modulesynopsis{Generate flat text email messages from a message structure.}
   3
   4 One of the most common tasks is to generate the flat text of the email
   5 message represented by a message object structure.  You will need to do
   6 this if you want to send your message via the \refmodule{smtplib}
   7 module or the \refmodule{nntplib} module, or print the message on the
   8 console.  Taking a message object structure and producing a flat text
   9 document is the job of the \class{Generator} class.
  10
  11 Again, as with the \refmodule{email.Parser} module, you aren't limited
  12 to the functionality of the bundled generator; you could write one
  13 from scratch yourself.  However the bundled generator knows how to
  14 generate most email in a standards-compliant way, should handle MIME
  15 and non-MIME email messages just fine, and is designed so that the
  16 transformation from flat text, to a message structure via the
  17 \class{Parser} class, and back to flat text, is idempotent (the input
  18 is identical to the output).
  19
  20 Here are the public methods of the \class{Generator} class:
  21
  22 \begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
  23     maxheaderlen}}}
  24 The constructor for the \class{Generator} class takes a file-like
  25 object called \var{outfp} for an argument.  \var{outfp} must support
  26 the \method{write()} method and be usable as the output file in a
  27 Python extended print statement.
  28
  29 Optional \var{mangle_from_} is a flag that, when \code{True}, puts a
  30 \samp{>} character in front of any line in the body that starts exactly as
  31 \samp{From }, i.e. \code{From} followed by a space at the beginning of the
  32 line.  This is the only guaranteed portable way to avoid having such
  33 lines be mistaken for a Unix mailbox format envelope header separator (see
  34 \ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
  35 {http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
  36 for details).  \var{mangle_from_} defaults to \code{True}, but you
  37 might want to set this to \code{False} if you are not writing Unix
  38 mailbox format files.
  39
  40 Optional \var{maxheaderlen} specifies the longest length for a
  41 non-continued header.  When a header line is longer than
  42 \var{maxheaderlen} (in characters, with tabs expanded to 8 spaces),
  43 the header will be broken on semicolons and continued as per
  44 \rfc{2822}.  If no semicolon is found, then the header is left alone.
  45 Set to zero to disable wrapping headers.  Default is 78, as
  46 recommended (but not required) by \rfc{2822}.
  47 \end{classdesc}
  48
  49 The other public \class{Generator} methods are:
  50
  51 \begin{methoddesc}[Generator]{flatten}{msg\optional{, unixfrom}}
  52 Print the textual representation of the message object structure rooted at
  53 \var{msg} to the output file specified when the \class{Generator}
  54 instance was created.  Subparts are visited depth-first and the
  55 resulting text will be properly MIME encoded.
  56
  57 Optional \var{unixfrom} is a flag that forces the printing of the
  58 envelope header delimiter before the first \rfc{2822} header of the
  59 root message object.  If the root object has no envelope header, a
  60 standard one is crafted.  By default, this is set to \code{False} to
  61 inhibit the printing of the envelope delimiter.
  62
  63 Note that for subparts, no envelope header is ever printed.
  64
  65 \versionadded{2.2.2}
  66 \end{methoddesc}
  67
  68 \begin{methoddesc}[Generator]{clone}{fp}
  69 Return an independent clone of this \class{Generator} instance with
  70 the exact same options.
  71
  72 \versionadded{2.2.2}
  73 \end{methoddesc}
  74
  75 \begin{methoddesc}[Generator]{write}{s}
  76 Write the string \var{s} to the underlying file object,
  77 i.e. \var{outfp} passed to \class{Generator}'s constructor.  This
  78 provides just enough file-like API for \class{Generator} instances to
  79 be used in extended print statements.
  80 \end{methoddesc}
  81
  82 As a convenience, see the methods \method{Message.as_string()} and
  83 \code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
  84 simplify the generation of a formatted string representation of a
  85 message object.  For more detail, see \refmodule{email.Message}.
  86
  87 The \module{email.Generator} module also provides a derived class,
  88 called \class{DecodedGenerator} which is like the \class{Generator}
  89 base class, except that non-\mimetype{text} parts are substituted with
  90 a format string representing the part.
  91
  92 \begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{,
  93     maxheaderlen\optional{, fmt}}}}
  94
  95 This class, derived from \class{Generator} walks through all the
  96 subparts of a message.  If the subpart is of main type
  97 \mimetype{text}, then it prints the decoded payload of the subpart.
  98 Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the
  99 \class{Generator} base class.
 100
 101 If the subpart is not of main type \mimetype{text}, optional \var{fmt}
 102 is a format string that is used instead of the message payload.
 103 \var{fmt} is expanded with the following keywords, \samp{\%(keyword)s}
 104 format:
 105
 106 \begin{itemize}
 107 \item \code{type} -- Full MIME type of the non-\mimetype{text} part
 108
 109 \item \code{maintype} -- Main MIME type of the non-\mimetype{text} part
 110
 111 \item \code{subtype} -- Sub-MIME type of the non-\mimetype{text} part
 112
 113 \item \code{filename} -- Filename of the non-\mimetype{text} part
 114
 115 \item \code{description} -- Description associated with the
 116       non-\mimetype{text} part
 117
 118 \item \code{encoding} -- Content transfer encoding of the
 119       non-\mimetype{text} part
 120
 121 \end{itemize}
 122
 123 The default value for \var{fmt} is \code{None}, meaning
 124
 125 \begin{verbatim}
 126 [Non-text (%(type)s) part of message omitted, filename %(filename)s]
 127 \end{verbatim}
 128
 129 \versionadded{2.2.2}
 130 \end{classdesc}
 131
 132 \subsubsection{Deprecated methods}
 133
 134 The following methods are deprecated in \module{email} version 2.
 135 They are documented here for completeness.
 136
 137 \begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
 138 This method is identical to the \method{flatten()} method.
 139
 140 \deprecated{2.2.2}{Use the \method{flatten()} method instead.}
 141 \end{methoddesc}