1 

     2 :mod:`mimetools` --- Tools for parsing MIME messages

     3 ====================================================

     4 

     5 .. module:: mimetools

     6    :synopsis: Tools for parsing MIME-style message bodies.

     7    :deprecated:

     8 

     9 

    10 .. deprecated:: 2.3

    11    The :mod:`email` package should be used in preference to the :mod:`mimetools`

    12    module.  This module is present only to maintain backward compatibility, and

    13    it has been removed in 3.x.

    14 

    15 .. index:: module: rfc822

    16 

    17 This module defines a subclass of the :mod:`rfc822` module's :class:`Message`

    18 class and a number of utility functions that are useful for the manipulation for

    19 MIME multipart or encoded message.

    20 

    21 It defines the following items:

    22 

    23 

    24 .. class:: Message(fp[, seekable])

    25 

    26    Return a new instance of the :class:`Message` class.  This is a subclass of the

    27    :class:`rfc822.Message` class, with some additional methods (see below).  The

    28    *seekable* argument has the same meaning as for :class:`rfc822.Message`.

    29 

    30 

    31 .. function:: choose_boundary()

    32 

    33    Return a unique string that has a high likelihood of being usable as a part

    34    boundary.  The string has the form ``'hostipaddr.uid.pid.timestamp.random'``.

    35 

    36 

    37 .. function:: decode(input, output, encoding)

    38 

    39    Read data encoded using the allowed MIME *encoding* from open file object

    40    *input* and write the decoded data to open file object *output*.  Valid values

    41    for *encoding* include ``'base64'``, ``'quoted-printable'``, ``'uuencode'``,

    42    ``'x-uuencode'``, ``'uue'``, ``'x-uue'``, ``'7bit'``, and  ``'8bit'``.  Decoding

    43    messages encoded in ``'7bit'`` or ``'8bit'`` has no effect.  The input is simply

    44    copied to the output.

    45 

    46 

    47 .. function:: encode(input, output, encoding)

    48 

    49    Read data from open file object *input* and write it encoded using the allowed

    50    MIME *encoding* to open file object *output*. Valid values for *encoding* are

    51    the same as for :meth:`decode`.

    52 

    53 

    54 .. function:: copyliteral(input, output)

    55 

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

    57    *output*.

    58 

    59 

    60 .. function:: copybinary(input, output)

    61 

    62    Read blocks until EOF from open file *input* and write them to open file

    63    *output*.  The block size is currently fixed at 8192.

    64 

    65 

    66 .. seealso::

    67 

    68    Module :mod:`email`

    69       Comprehensive email handling package; supersedes the :mod:`mimetools` module.

    70 

    71    Module :mod:`rfc822`

    72       Provides the base class for :class:`mimetools.Message`.

    73 

    74    Module :mod:`multifile`

    75       Support for reading files which contain distinct parts, such as MIME data.

    76 

    77    http://faqs.cs.uu.nl/na-dir/mail/mime-faq/.html

    78       The MIME Frequently Asked Questions document.  For an overview of MIME, see the

    79       answer to question 1.1 in Part 1 of this document.

    80 

    81 

    82 .. _mimetools-message-objects:

    83 

    84 Additional Methods of Message Objects

    85 -------------------------------------

    86 

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

    88 :class:`rfc822.Message` methods:

    89 

    90 

    91 .. method:: Message.getplist()

    92 

    93    Return the parameter list of the :mailheader:`Content-Type` header. This is a

    94    list of strings.  For parameters of the form ``key=value``, *key* is converted

    95    to lower case but *value* is not.  For example, if the message contains the

    96    header ``Content-type: text/html; spam=1; Spam=2; Spam`` then :meth:`getplist`

    97    will return the Python list ``['spam=1', 'spam=2', 'Spam']``.

    98 

    99 

   100 .. method:: Message.getparam(name)

   101 

   102    Return the *value* of the first parameter (as returned by :meth:`getplist`) of

   103    the form ``name=value`` for the given *name*.  If *value* is surrounded by

   104    quotes of the form '``<``...\ ``>``' or '``"``...\ ``"``', these are removed.

   105 

   106 

   107 .. method:: Message.getencoding()

   108 

   109    Return the encoding specified in the :mailheader:`Content-Transfer-Encoding`

   110    message header.  If no such header exists, return ``'7bit'``.  The encoding is

   111    converted to lower case.

   112 

   113 

   114 .. method:: Message.gettype()

   115 

   116    Return the message type (of the form ``type/subtype``) as specified in the

   117    :mailheader:`Content-Type` header.  If no such header exists, return

   118    ``'text/plain'``.  The type is converted to lower case.

   119 

   120 

   121 .. method:: Message.getmaintype()

   122 

   123    Return the main type as specified in the :mailheader:`Content-Type` header.  If

   124    no such header exists, return ``'text'``.  The main type is converted to lower

   125    case.

   126 

   127 

   128 .. method:: Message.getsubtype()

   129 

   130    Return the subtype as specified in the :mailheader:`Content-Type` header.  If no

   131    such header exists, return ``'plain'``.  The subtype is converted to lower case.

   132