Doc/lib/emailgenerator.tex

\declaremodule{standard}{email.Generator}
\modulesynopsis{Generate flat text email messages from a message structure.}

One of the most common tasks is to generate the flat text of the email
message represented by a message object structure.  You will need to do
this if you want to send your message via the \refmodule{smtplib}
module or the \refmodule{nntplib} module, or print the message on the
console.  Taking a message object structure and producing a flat text
document is the job of the \class{Generator} class.

Again, as with the \refmodule{email.Parser} module, you aren't limited
to the functionality of the bundled generator; you could write one
from scratch yourself.  However the bundled generator knows how to
generate most email in a standards-compliant way, should handle MIME
and non-MIME email messages just fine, and is designed so that the
transformation from flat text, to a message structure via the
\class{Parser} class, and back to flat text, is idempotent (the input
is identical to the output).

Here are the public methods of the \class{Generator} class:

\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
    maxheaderlen}}}
The constructor for the \class{Generator} class takes a file-like
object called \var{outfp} for an argument.  \var{outfp} must support
the \method{write()} method and be usable as the output file in a
Python 2.0 extended print statement.

Optional \var{mangle_from_} is a flag that, when \code{True}, puts a
\samp{>} character in front of any line in the body that starts exactly as
\samp{From } (i.e. \code{From} followed by a space at the front of the
line).  This is the only guaranteed portable way to avoid having such
lines be mistaken for a Unix mailbox format envelope header separator (see
\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
for details).  \var{mangle_from_} defaults to \code{True}, but you
might want to set this to \code{False} if you are not writing Unix
mailbox format files.

Optional \var{maxheaderlen} specifies the longest length for a
non-continued header.  When a header line is longer than
\var{maxheaderlen} (in characters, with tabs expanded to 8 spaces),
the header will be broken on semicolons and continued as per
\rfc{2822}.  If no semicolon is found, then the header is left alone.
Set to zero to disable wrapping headers.  Default is 78, as
recommended (but not required) by \rfc{2822}.
\end{classdesc}

The other public \class{Generator} methods are:

\begin{methoddesc}[Generator]{flatten()}{msg\optional{, unixfrom}}
Print the textual representation of the message object structure rooted at
\var{msg} to the output file specified when the \class{Generator}
instance was created.  Sub-objects are visited depth-first and the
resulting text will be properly MIME encoded.

Optional \var{unixfrom} is a flag that forces the printing of the
envelope header delimiter before the first \rfc{2822} header of the
root message object.  If the root object has no envelope header, a
standard one is crafted.  By default, this is set to \code{False} to
inhibit the printing of the envelope delimiter.

Note that for sub-objects, no envelope header is ever printed.

\versionadded{2.2.2}
\end{methoddesc}

\begin{methoddesc}[Generator]{clone}{fp}
Return an independent clone of this \class{Generator} instance with
the exact same options.

\versionadded{2.2.2}
\end{methoddesc}

\begin{methoddesc}[Generator]{write}{s}
Write the string \var{s} to the underlying file object,
i.e. \var{outfp} passed to \class{Generator}'s constructor.  This
provides just enough file-like API for \class{Generator} instances to
be used in extended print statements.
\end{methoddesc}

As a convenience, see the methods \method{Message.as_string()} and
\code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
simplify the generation of a formatted string representation of a
message object.  For more detail, see \refmodule{email.Message}.

The \module{email.Generator} module also provides a derived class,
called \class{DecodedGenerator} which is like the \class{Generator}
base class, except that non-\mimetype{text} parts are substituted with
a format string representing the part.

\begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{,
    maxheaderlen\optional{, fmt}}}}

This class, derived from \class{Generator} walks through all the
subparts of a message.  If the subpart is of main type
\mimetype{text}, then it prints the decoded payload of the subpart.
Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the
\class{Generator} base class.

If the subpart is not of main type \mimetype{text}, optional \var{fmt}
is a format string that is used instead of the message
payload.  \var{fmt} is expanded with the following keywords (in
\samp{\%(keyword)s} format):

type       : Full MIME type of the non-\mimetype{text} part
maintype   : Main MIME type of the non-\mimetype{text} part
subtype    : Sub-MIME type of the non-\mimetype{text} part
filename   : Filename of the non-\mimetype{text} part
description: Description associated with the non-\mimetype{text} part
encoding   : Content transfer encoding of the non-\mimetype{text} part

The default value for \var{fmt} is \code{None}, meaning

\begin{verbatim}
[Non-text (%(type)s) part of message omitted, filename %(filename)s]
\end{verbatim}

\versionadded{2.2.2}
\end{classdesc}

\subsubsection{Deprecated methods}

The following methods are deprecated in \module{email} version 2.
They are documented here for completeness.

\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
This method is identical to the \method{flatten()} method.

\deprecated{2.2.2}{Use the \method{flatten()} method instead.}
\end{methoddesc}