Vast update to email version 2. This could surely use proofreading.

1 files changed, 159 insertions, 0 deletions

diff --git a/Doc/lib/emailmimebase.tex b/Doc/lib/emailmimebase.tex
new file mode 100644
index 0000000..97c3eda
--- /dev/null
+++ b/Doc/lib/emailmimebase.tex
@@ -0,0 +1,159 @@
+Ordinarily, you get a message object structure by passing a file or
+some text to a parser, which parses the text and returns the root of
+the message object structure.  However you can also build a complete
+object structure from scratch, or even individual \class{Message}
+objects by hand.  In fact, you can also take an existing structure and
+add new \class{Message} objects, move them around, etc.  This makes a
+very convenient interface for slicing-and-dicing MIME messages.
+
+You can create a new object structure by creating \class{Message}
+instances, adding attachments and all the appropriate headers manually.
+For MIME messages though, the \module{email} package provides some
+convenient subclasses to make things easier.  Each of these classes
+should be imported from a module with the same name as the class, from
+within the \module{email} package.  E.g.:
+
+\begin{verbatim}
+import email.MIMEImage.MIMEImage
+\end{verbatim}
+
+or
+
+\begin{verbatim}
+from email.MIMEText import MIMEText
+\end{verbatim}
+
+Here are the classes:
+
+\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
+This is the base class for all the MIME-specific subclasses of
+\class{Message}.  Ordinarily you won't create instances specifically
+of \class{MIMEBase}, although you could.  \class{MIMEBase} is provided
+primarily as a convenient base class for more specific MIME-aware
+subclasses.
+
+\var{_maintype} is the \mailheader{Content-Type} major type
+(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the
+\mailheader{Content-Type} minor type 
+(e.g. \mimetype{plain} or \mimetype{gif}).  \var{_params} is a parameter
+key/value dictionary and is passed directly to
+\method{Message.add_header()}.
+
+The \class{MIMEBase} class always adds a \mailheader{Content-Type} header
+(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a
+\mailheader{MIME-Version} header (always set to \code{1.0}).
+\end{classdesc}
+
+\begin{classdesc}{MIMENonMultipart}{}
+A subclass of \class{MIMEBase}, this is an intermediate base class for
+MIME messages that are not \mimetype{multipart}.  The primary purpose
+of this class is to prevent the use of the \method{attach()} method,
+which only makes sense for \mimetype{multipart} messages.  If
+\method{attach()} is called, a \exception{MultipartConversionError}
+exception is raised.
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{,
+    boundary\optional{, _subparts\optional{, _params}}}}}
+
+A subclass of \class{MIMEBase}, this is an intermediate base class for
+MIME messages that are \mimetype{multipart}.  Optional \var{_subtype}
+defaults to \mimetype{mixed}, but can be used to specify the subtype
+of the message.  A \mailheader{Content-Type} header of
+\mimetype{multipart/}\var{_subtype} will be added to the message
+object.  A \mailheader{MIME-Version} header will also be added.
+
+Optional \var{boundary} is the multipart boundary string.  When
+\code{None} (the default), the boundary is calculated when needed.
+
+\var{_subparts} is a sequence of initial subparts for the payload.  It
+must be possible to convert this sequence to a list.  You can always
+attach new subparts to the message by using the
+\method{Message.attach()} method.
+
+Additional parameters for the \mailheader{Content-Type} header are
+taken from the keyword arguments, or passed into the \var{_params}
+argument, which is a keyword dictionary.
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
+    _encoder\optional{, **_params}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class
+is used to create MIME message objects of major type \mimetype{audio}.
+\var{_audiodata} is a string containing the raw audio data.  If this
+data can be decoded by the standard Python module \refmodule{sndhdr},
+then the subtype will be automatically included in the
+\mailheader{Content-Type} header.  Otherwise you can explicitly specify the
+audio subtype via the \var{_subtype} parameter.  If the minor type could
+not be guessed and \var{_subtype} was not given, then \exception{TypeError}
+is raised.
+
+Optional \var{_encoder} is a callable (i.e. function) which will
+perform the actual encoding of the audio data for transport.  This
+callable takes one argument, which is the \class{MIMEAudio} instance.
+It should use \method{get_payload()} and \method{set_payload()} to
+change the payload to encoded form.  It should also add any
+\mailheader{Content-Transfer-Encoding} or other headers to the message
+object as necessary.  The default encoding is \emph{Base64}.  See the
+\refmodule{email.Encoders} module for a list of the built-in encoders.
+
+\var{_params} are passed straight through to the base class constructor.
+\end{classdesc}
+
+\begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
+    _encoder\optional{, **_params}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is
+used to create MIME message objects of major type \mimetype{image}.
+\var{_imagedata} is a string containing the raw image data.  If this
+data can be decoded by the standard Python module \refmodule{imghdr},
+then the subtype will be automatically included in the
+\mailheader{Content-Type} header.  Otherwise you can explicitly specify the
+image subtype via the \var{_subtype} parameter.  If the minor type could
+not be guessed and \var{_subtype} was not given, then \exception{TypeError}
+is raised.
+
+Optional \var{_encoder} is a callable (i.e. function) which will
+perform the actual encoding of the image data for transport.  This
+callable takes one argument, which is the \class{MIMEImage} instance.
+It should use \method{get_payload()} and \method{set_payload()} to
+change the payload to encoded form.  It should also add any
+\mailheader{Content-Transfer-Encoding} or other headers to the message
+object as necessary.  The default encoding is \emph{Base64}.  See the
+\refmodule{email.Encoders} module for a list of the built-in encoders.
+
+\var{_params} are passed straight through to the \class{MIMEBase}
+constructor.
+\end{classdesc}
+
+\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
+A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class
+is used to create MIME objects of main type \mimetype{message}.
+\var{_msg} is used as the payload, and must be an instance of class
+\class{Message} (or a subclass thereof), otherwise a
+\exception{TypeError} is raised.
+
+Optional \var{_subtype} sets the subtype of the message; it defaults
+to \mimetype{rfc822}.
+\end{classdesc}
+
+\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
+    _charset\optional{, _encoder}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
+used to create MIME objects of major type \mimetype{text}.
+\var{_text} is the string for the payload.  \var{_subtype} is the
+minor type and defaults to \mimetype{plain}.  \var{_charset} is the
+character set of the text and is passed as a parameter to the
+\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}.  No
+guessing or encoding is performed on the text data, but a newline is
+appended to \var{_text} if it doesn't already end with a newline.
+
+\deprecated{2.2.2}{The \var{_encoding} argument has been deprecated.
+Encoding now happens implicitly based on the \var{_charset} argument.}
+\end{classdesc}