160 lines
7.1 KiB
TeX
160 lines
7.1 KiB
TeX
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
|
|
message object. However you can also build a complete message
|
|
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 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 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}
|