134 lines
5.5 KiB
TeX
134 lines
5.5 KiB
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, imported from the
|
|
\module{email.generator} module:
|
|
|
|
\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 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 beginning 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 split as defined in the \module{email.header.Header}
|
|
class. Set to zero to disable header wrapping. The 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. Subparts 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 subparts, 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, \samp{\%(keyword)s}
|
|
format:
|
|
|
|
\begin{itemize}
|
|
\item \code{type} -- Full MIME type of the non-\mimetype{text} part
|
|
|
|
\item \code{maintype} -- Main MIME type of the non-\mimetype{text} part
|
|
|
|
\item \code{subtype} -- Sub-MIME type of the non-\mimetype{text} part
|
|
|
|
\item \code{filename} -- Filename of the non-\mimetype{text} part
|
|
|
|
\item \code{description} -- Description associated with the
|
|
non-\mimetype{text} part
|
|
|
|
\item \code{encoding} -- Content transfer encoding of the
|
|
non-\mimetype{text} part
|
|
|
|
\end{itemize}
|
|
|
|
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}
|
|
|
|
\versionchanged[The previously deprecated method \method{__call__()} was
|
|
removed]{2.5}
|