summaryrefslogtreecommitdiffstats
path: root/Doc/library/mimetools.rst
blob: 8da385e0ce5a697cef8734c29c2620a66f3fb4c0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

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

.. module:: mimetools
   :synopsis: Tools for parsing MIME-style message bodies.
   :deprecated:


.. deprecated:: 2.3
   The :mod:`email` package should be used in preference to the :mod:`mimetools`
   module.  This module is present only to maintain backward compatibility.

.. index:: module: rfc822

This module defines a subclass of the :mod:`rfc822` module's :class:`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:: Message(fp[, seekable])

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


.. function:: 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'``.


.. function:: 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.


.. function:: 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 :meth:`decode`.


.. function:: copyliteral(input, output)

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


.. function:: 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.


.. seealso::

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

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

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

   http://www.cs.uu.nl/wais/html/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.


.. _mimetools-message-objects:

Additional Methods of Message Objects
-------------------------------------

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


.. method:: Message.getplist()

   Return the parameter list of the :mailheader:`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 :meth:`getplist`
   will return the Python list ``['spam=1', 'spam=2', 'Spam']``.


.. method:: Message.getparam(name)

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


.. method:: Message.getencoding()

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


.. method:: Message.gettype()

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


.. method:: Message.getmaintype()

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


.. method:: Message.getsubtype()

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