/Doc/library/mimetools.rst

  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
 17This module defines a subclass of the :mod:`rfc822` module's :class:`Message`
 18class and a number of utility functions that are useful for the manipulation for
 19MIME multipart or encoded message.
 20
 21It 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
 84Additional Methods of Message Objects
 85-------------------------------------
 86
 87The :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