``mimetools`` --- Tools for parsing MIME messages
*************************************************

Deprecated since version 2.3: The ``email`` package should be used in
preference to the ``mimetools`` module.  This module is present only
to maintain backward compatibility, and it has been removed in 3.x.

This module defines a subclass of the ``rfc822`` module's ``Message``
class and a number of utility functions that are useful for the
manipulation for MIME multipart or encoded message.

It defines the following items:

class class mimetools.Message(fp[, seekable])

   Return a new instance of the ``Message`` class.  This is a subclass
   of the ``rfc822.Message`` class, with some additional methods (see
   below).  The *seekable* argument has the same meaning as for
   ``rfc822.Message``.

mimetools.choose_boundary()

   Return a unique string that has a high likelihood of being usable
   as a part boundary.  The string has the form
   ``'hostipaddr.uid.pid.timestamp.random'``.

mimetools.decode(input, output, encoding)

   Read data encoded using the allowed MIME *encoding* from open file
   object *input* and write the decoded data to open file object
   *output*.  Valid values for *encoding* include ``'base64'``,
   ``'quoted-printable'``, ``'uuencode'``, ``'x-uuencode'``,
   ``'uue'``, ``'x-uue'``, ``'7bit'``, and  ``'8bit'``.  Decoding
   messages encoded in ``'7bit'`` or ``'8bit'`` has no effect.  The
   input is simply copied to the output.

mimetools.encode(input, output, encoding)

   Read data from open file object *input* and write it encoded using
   the allowed MIME *encoding* to open file object *output*. Valid
   values for *encoding* are the same as for ``decode()``.

mimetools.copyliteral(input, output)

   Read lines from open file *input* until EOF and write them to open
   file *output*.

mimetools.copybinary(input, output)

   Read blocks until EOF from open file *input* and write them to open
   file *output*.  The block size is currently fixed at 8192.

See also:

   Module ``email``
      Comprehensive email handling package; supersedes the
      ``mimetools`` module.

   Module ``rfc822``
      Provides the base class for ``mimetools.Message``.

   Module ``multifile``
      Support for reading files which contain distinct parts, such as
      MIME data.

   http://faqs.cs.uu.nl/na-dir/mail/mime-faq/.html
      The MIME Frequently Asked Questions document.  For an overview
      of MIME, see the answer to question 1.1 in Part 1 of this
      document.


Additional Methods of Message Objects
=====================================

The ``Message`` class defines the following methods in addition to the
``rfc822.Message`` methods:

Message.getplist()

   Return the parameter list of the *Content-Type* header. This is a
   list of strings.  For parameters of the form ``key=value``, *key*
   is converted to lower case but *value* is not.  For example, if the
   message contains the header ``Content-type: text/html; spam=1;
   Spam=2; Spam`` then ``getplist()`` will return the Python list
   ``['spam=1', 'spam=2', 'Spam']``.

Message.getparam(name)

   Return the *value* of the first parameter (as returned by
   ``getplist()``) of the form ``name=value`` for the given *name*.
   If *value* is surrounded by quotes of the form '``<``...``>``' or
   '``"``...``"``', these are removed.

Message.getencoding()

   Return the encoding specified in the *Content-Transfer-Encoding*
   message header.  If no such header exists, return ``'7bit'``.  The
   encoding is converted to lower case.

Message.gettype()

   Return the message type (of the form ``type/subtype``) as specified
   in the *Content-Type* header.  If no such header exists, return
   ``'text/plain'``.  The type is converted to lower case.

Message.getmaintype()

   Return the main type as specified in the *Content-Type* header.  If
   no such header exists, return ``'text'``.  The main type is
   converted to lower case.

Message.getsubtype()

   Return the subtype as specified in the *Content-Type* header.  If
   no such header exists, return ``'plain'``.  The subtype is
   converted to lower case.