
``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 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 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 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 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 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 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 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 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-Endcoding*
   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).
