summaryrefslogtreecommitdiffstats
path: root/Doc/library/email.mime.rst
blob: 6f1b0aea989c23176a51b314a93a48f707e9dba1 (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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
:mod:`email`: Creating email and MIME objects from scratch
----------------------------------------------------------

.. module:: email.mime
   :synopsis: Build MIME messages. 


Ordinarily, you get a message object structure by passing a file or some text to
a parser, which parses the text and returns the root message object.  However
you can also build a complete message structure from scratch, or even individual
:class:`Message` objects by hand.  In fact, you can also take an existing
structure and add new :class:`Message` objects, move them around, etc.  This
makes a very convenient interface for slicing-and-dicing MIME messages.

You can create a new object structure by creating :class:`Message` instances,
adding attachments and all the appropriate headers manually.  For MIME messages
though, the :mod:`email` package provides some convenient subclasses to make
things easier.

Here are the classes:


.. class:: MIMEBase(_maintype, _subtype, **_params)

   Module: :mod:`email.mime.base`

   This is the base class for all the MIME-specific subclasses of :class:`Message`.
   Ordinarily you won't create instances specifically of :class:`MIMEBase`,
   although you could.  :class:`MIMEBase` is provided primarily as a convenient
   base class for more specific MIME-aware subclasses.

   *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
   or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
   type  (e.g. :mimetype:`plain` or :mimetype:`gif`).  *_params* is a parameter
   key/value dictionary and is passed directly to :meth:`Message.add_header`.

   The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
   (based on *_maintype*, *_subtype*, and *_params*), and a
   :mailheader:`MIME-Version` header (always set to ``1.0``).


.. class:: MIMENonMultipart()

   Module: :mod:`email.mime.nonmultipart`

   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
   messages that are not :mimetype:`multipart`.  The primary purpose of this class
   is to prevent the use of the :meth:`attach` method, which only makes sense for
   :mimetype:`multipart` messages.  If :meth:`attach` is called, a
   :exc:`MultipartConversionError` exception is raised.

   .. versionadded:: 2.2.2


.. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]])

   Module: :mod:`email.mime.multipart`

   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
   messages that are :mimetype:`multipart`.  Optional *_subtype* defaults to
   :mimetype:`mixed`, but can be used to specify the subtype of the message.  A
   :mailheader:`Content-Type` header of :mimetype:`multipart/`*_subtype* will be
   added to the message object.  A :mailheader:`MIME-Version` header will also be
   added.

   Optional *boundary* is the multipart boundary string.  When ``None`` (the
   default), the boundary is calculated when needed.

   *_subparts* is a sequence of initial subparts for the payload.  It must be
   possible to convert this sequence to a list.  You can always attach new subparts
   to the message by using the :meth:`Message.attach` method.

   Additional parameters for the :mailheader:`Content-Type` header are taken from
   the keyword arguments, or passed into the *_params* argument, which is a keyword
   dictionary.

   .. versionadded:: 2.2.2


.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])

   Module: :mod:`email.mime.application`

   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
   used to represent MIME message objects of major type :mimetype:`application`.
   *_data* is a string containing the raw byte data.  Optional *_subtype* specifies
   the MIME subtype and defaults to :mimetype:`octet-stream`.

   Optional *_encoder* is a callable (i.e. function) which will perform the actual
   encoding of the data for transport.  This callable takes one argument, which is
   the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
   :meth:`set_payload` to change the payload to encoded form.  It should also add
   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
   object as necessary.  The default encoding is base64.  See the
   :mod:`email.encoders` module for a list of the built-in encoders.

   *_params* are passed straight through to the base class constructor.

   .. versionadded:: 2.5


.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])

   Module: :mod:`email.mime.audio`

   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
   create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
   string containing the raw audio data.  If this data can be decoded by the
   standard Python module :mod:`sndhdr`, then the subtype will be automatically
   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
   specify the audio subtype via the *_subtype* parameter.  If the minor type could
   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.

   Optional *_encoder* is a callable (i.e. function) which will perform the actual
   encoding of the audio data for transport.  This callable takes one argument,
   which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
   :meth:`set_payload` to change the payload to encoded form.  It should also add
   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
   object as necessary.  The default encoding is base64.  See the
   :mod:`email.encoders` module for a list of the built-in encoders.

   *_params* are passed straight through to the base class constructor.


.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])

   Module: :mod:`email.mime.image`

   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
   create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
   string containing the raw image data.  If this data can be decoded by the
   standard Python module :mod:`imghdr`, then the subtype will be automatically
   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
   specify the image subtype via the *_subtype* parameter.  If the minor type could
   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.

   Optional *_encoder* is a callable (i.e. function) which will perform the actual
   encoding of the image data for transport.  This callable takes one argument,
   which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
   :meth:`set_payload` to change the payload to encoded form.  It should also add
   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
   object as necessary.  The default encoding is base64.  See the
   :mod:`email.encoders` module for a list of the built-in encoders.

   *_params* are passed straight through to the :class:`MIMEBase` constructor.


.. class:: MIMEMessage(_msg[, _subtype])

   Module: :mod:`email.mime.message`

   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
   to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
   payload, and must be an instance of class :class:`Message` (or a subclass
   thereof), otherwise a :exc:`TypeError` is raised.

   Optional *_subtype* sets the subtype of the message; it defaults to
   :mimetype:`rfc822`.


.. class:: MIMEText(_text[, _subtype[, _charset]])

   Module: :mod:`email.mime.text`

   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
   create MIME objects of major type :mimetype:`text`. *_text* is the string for
   the payload.  *_subtype* is the minor type and defaults to :mimetype:`plain`.
   *_charset* is the character set of the text and is passed as a parameter to the
   :class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``.  No guessing
   or encoding is performed on the text data.

   .. versionchanged:: 2.4
      The previously deprecated *_encoding* argument has been removed.  Encoding
      happens implicitly based on the *_charset* argument.