18.1.4. "email.mime": Creating email and MIME objects from scratch
******************************************************************

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 "Message" objects by hand.
In fact, you can also take an existing structure and add new "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 "Message" instances,
adding attachments and all the appropriate headers manually.  For MIME
messages though, the "email" package provides some convenient
subclasses to make things easier.

Here are the classes:

class email.mime.base.MIMEBase(_maintype, _subtype, **_params)

   Module: "email.mime.base"

   This is the base class for all the MIME-specific subclasses of
   "Message".  Ordinarily you won’t create instances specifically of
   "MIMEBase", although you could.  "MIMEBase" is provided primarily
   as a convenient base class for more specific MIME-aware subclasses.

   *_maintype* is the *Content-Type* major type (e.g. *text* or
   *image*), and *_subtype* is the *Content-Type* minor type  (e.g.
   *plain* or *gif*).  *_params* is a parameter key/value dictionary
   and is passed directly to "Message.add_header".

   The "MIMEBase" class always adds a *Content-Type* header (based on
   *_maintype*, *_subtype*, and *_params*), and a *MIME-Version*
   header (always set to "1.0").

class email.mime.nonmultipart.MIMENonMultipart

   Module: "email.mime.nonmultipart"

   A subclass of "MIMEBase", this is an intermediate base class for
   MIME messages that are not *multipart*.  The primary purpose of
   this class is to prevent the use of the "attach()" method, which
   only makes sense for *multipart* messages.  If "attach()" is
   called, a "MultipartConversionError" exception is raised.

   New in version 2.2.2.

class email.mime.multipart.MIMEMultipart([_subtype[, boundary[, _subparts[, _params]]]])

   Module: "email.mime.multipart"

   A subclass of "MIMEBase", this is an intermediate base class for
   MIME messages that are *multipart*.  Optional *_subtype* defaults
   to *mixed*, but can be used to specify the subtype of the message.
   A *Content-Type* header of *multipart/_subtype* will be added to
   the message object.  A *MIME-Version* header will also be added.

   Optional *boundary* is the multipart boundary string.  When "None"
   (the default), the boundary is calculated when needed (for example,
   when the message is serialized).

   *_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
   "Message.attach" method.

   Additional parameters for the *Content-Type* header are taken from
   the keyword arguments, or passed into the *_params* argument, which
   is a keyword dictionary.

   New in version 2.2.2.

class email.mime.application.MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])

   Module: "email.mime.application"

   A subclass of "MIMENonMultipart", the "MIMEApplication" class is
   used to represent MIME message objects of major type *application*.
   *_data* is a string containing the raw byte data.  Optional
   *_subtype* specifies the MIME subtype and defaults to *octet-
   stream*.

   Optional *_encoder* is a callable (i.e. function) which will
   perform the actual encoding of the data for transport.  This
   callable takes one argument, which is the "MIMEApplication"
   instance. It should use "get_payload()" and "set_payload()" to
   change the payload to encoded form.  It should also add any
   *Content-Transfer-Encoding* or other headers to the message object
   as necessary.  The default encoding is base64.  See the
   "email.encoders" module for a list of the built-in encoders.

   *_params* are passed straight through to the base class
   constructor.

   New in version 2.5.

class email.mime.audio.MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])

   Module: "email.mime.audio"

   A subclass of "MIMENonMultipart", the "MIMEAudio" class is used to
   create MIME message objects of major type *audio*. *_audiodata* is
   a string containing the raw audio data.  If this data can be
   decoded by the standard Python module "sndhdr", then the subtype
   will be automatically included in the *Content-Type* header.
   Otherwise you can explicitly specify the audio subtype via the
   *_subtype* parameter.  If the minor type could not be guessed and
   *_subtype* was not given, then "TypeError" is raised.

   Optional *_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 "MIMEAudio" instance. It
   should use "get_payload()" and "set_payload()" to change the
   payload to encoded form.  It should also add any *Content-Transfer-
   Encoding* or other headers to the message object as necessary.  The
   default encoding is base64.  See the "email.encoders" module for a
   list of the built-in encoders.

   *_params* are passed straight through to the base class
   constructor.

class email.mime.image.MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])

   Module: "email.mime.image"

   A subclass of "MIMENonMultipart", the "MIMEImage" class is used to
   create MIME message objects of major type *image*. *_imagedata* is
   a string containing the raw image data.  If this data can be
   decoded by the standard Python module "imghdr", then the subtype
   will be automatically included in the *Content-Type* header.
   Otherwise you can explicitly specify the image subtype via the
   *_subtype* parameter.  If the minor type could not be guessed and
   *_subtype* was not given, then "TypeError" is raised.

   Optional *_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 "MIMEImage" instance. It
   should use "get_payload()" and "set_payload()" to change the
   payload to encoded form.  It should also add any *Content-Transfer-
   Encoding* or other headers to the message object as necessary.  The
   default encoding is base64.  See the "email.encoders" module for a
   list of the built-in encoders.

   *_params* are passed straight through to the "MIMEBase"
   constructor.

class email.mime.message.MIMEMessage(_msg[, _subtype])

   Module: "email.mime.message"

   A subclass of "MIMENonMultipart", the "MIMEMessage" class is used
   to create MIME objects of main type *message*. *_msg* is used as
   the payload, and must be an instance of class "Message" (or a
   subclass thereof), otherwise a "TypeError" is raised.

   Optional *_subtype* sets the subtype of the message; it defaults to
   *rfc822*.

class email.mime.text.MIMEText(_text[, _subtype[, _charset]])

   Module: "email.mime.text"

   A subclass of "MIMENonMultipart", the "MIMEText" class is used to
   create MIME objects of major type *text*. *_text* is the string for
   the payload.  *_subtype* is the minor type and defaults to *plain*.
   *_charset* is the character set of the text and is passed as a
   parameter to the "MIMENonMultipart" constructor; it defaults to
   "us-ascii".  If *_text* is unicode, it is encoded using the
   *output_charset* of *_charset*, otherwise it is used as-is.

   Changed in version 2.4: The previously deprecated *_encoding*
   argument has been removed.  Content Transfer Encoding now happens
   implicitly based on the *_charset* argument.

   Unless the "_charset" parameter is explicitly set to "None", the
   MIMEText object created will have both a *Content-Type* header with
   a "charset" parameter, and a *Content-Transfer-Encoding* header.
   This means that a subsequent "set_payload" call will not result in
   an encoded payload, even if a charset is passed in the
   "set_payload" command.  You can “reset” this behavior by deleting
   the "Content-Transfer-Encoding" header, after which a "set_payload"
   call will automatically encode the new payload (and add a new
   *Content-Transfer-Encoding* header).
