l4/pkg/python/contrib/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
  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