diff options
Diffstat (limited to 'Doc/lib/emailgenerator.tex')
-rw-r--r-- | Doc/lib/emailgenerator.tex | 133 |
1 files changed, 0 insertions, 133 deletions
diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex deleted file mode 100644 index 7ab0a53..0000000 --- a/Doc/lib/emailgenerator.tex +++ /dev/null @@ -1,133 +0,0 @@ -\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://www.jwz.org/doc/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} |