Debian Codegraph @

Doc/library/email.mime.rst

raw
1 :mod:`!email.mime`: Creating email and MIME objects from scratch
2 ----------------------------------------------------------------
3
4 .. module:: email.mime
5 :synopsis: Build MIME messages.
6
7 **Source code:** :source:`Lib/email/mime/`
8
9 --------------
10
11 This module is part of the legacy (``Compat32``) email API. Its functionality
12 is partially replaced by the :mod:`~email.contentmanager` in the new API, but
13 in certain applications these classes may still be useful, even in non-legacy
14 code.
15
16 Ordinarily, you get a message object structure by passing a file or some text to
17 a parser, which parses the text and returns the root message object. However
18 you can also build a complete message structure from scratch, or even individual
19 :class:`~email.message.Message` objects by hand. In fact, you can also take an
20 existing structure and add new :class:`~email.message.Message` objects, move them
21 around, etc. This makes a very convenient interface for slicing-and-dicing MIME
22 messages.
23
24 You can create a new object structure by creating :class:`~email.message.Message`
25 instances, adding attachments and all the appropriate headers manually. For MIME
26 messages though, the :mod:`email` package provides some convenient subclasses to
27 make things easier.
28
29 Here are the classes:
30
31 .. module:: email.mime.base
32
33 .. class:: MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)
34
35 Module: :mod:`email.mime.base`
36
37 This is the base class for all the MIME-specific subclasses of
38 :class:`~email.message.Message`. Ordinarily you won't create instances
39 specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase`
40 is provided primarily as a convenient base class for more specific
41 MIME-aware subclasses.
42
43 *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
44 or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
45 type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter
46 key/value dictionary and is passed directly to :meth:`Message.add_header
47 <email.message.Message.add_header>`.
48
49 If *policy* is specified, (defaults to the
50 :class:`compat32 <email.policy.Compat32>` policy) it will be passed to
51 :class:`~email.message.Message`.
52
53 The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
54 (based on *_maintype*, *_subtype*, and *_params*), and a
55 :mailheader:`MIME-Version` header (always set to ``1.0``).
56
57 .. versionchanged:: 3.6
58 Added *policy* keyword-only parameter.
59
60
61 .. module:: email.mime.nonmultipart
62
63 .. class:: MIMENonMultipart()
64
65 Module: :mod:`email.mime.nonmultipart`
66
67 A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
68 class for MIME messages that are not :mimetype:`multipart`. The primary
69 purpose of this class is to prevent the use of the
70 :meth:`~email.message.Message.attach` method, which only makes sense for
71 :mimetype:`multipart` messages. If :meth:`~email.message.Message.attach`
72 is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
73
74
75 .. module:: email.mime.multipart
76
77 .. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, \
78 *, policy=compat32, **_params)
79
80 Module: :mod:`email.mime.multipart`
81
82 A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
83 class for MIME messages that are :mimetype:`multipart`. Optional *_subtype*
84 defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
85 message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype`
86 will be added to the message object. A :mailheader:`MIME-Version` header will
87 also be added.
88
89 Optional *boundary* is the multipart boundary string. When ``None`` (the
90 default), the boundary is calculated when needed (for example, when the
91 message is serialized).
92
93 *_subparts* is a sequence of initial subparts for the payload. It must be
94 possible to convert this sequence to a list. You can always attach new subparts
95 to the message by using the :meth:`Message.attach
96 <email.message.Message.attach>` method.
97
98 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
99
100 Additional parameters for the :mailheader:`Content-Type` header are taken from
101 the keyword arguments, or passed into the *_params* argument, which is a keyword
102 dictionary.
103
104 .. versionchanged:: 3.6
105 Added *policy* keyword-only parameter.
106
107 .. module:: email.mime.application
108
109 .. class:: MIMEApplication(_data, _subtype='octet-stream', \
110 _encoder=email.encoders.encode_base64, \
111 *, policy=compat32, **_params)
112
113 Module: :mod:`email.mime.application`
114
115 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
116 :class:`MIMEApplication` class is used to represent MIME message objects of
117 major type :mimetype:`application`. *_data* contains the bytes for the raw
118 application data. Optional *_subtype* specifies the MIME subtype and defaults
119 to :mimetype:`octet-stream`.
120
121 Optional *_encoder* is a callable (i.e. function) which will perform the actual
122 encoding of the data for transport. This callable takes one argument, which is
123 the :class:`MIMEApplication` instance. It should use
124 :meth:`~email.message.Message.get_payload` and
125 :meth:`~email.message.Message.set_payload` to change the payload to encoded
126 form. It should also add
127 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
128 object as necessary. The default encoding is base64. See the
129 :mod:`email.encoders` module for a list of the built-in encoders.
130
131 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
132
133 *_params* are passed straight through to the base class constructor.
134
135 .. versionchanged:: 3.6
136 Added *policy* keyword-only parameter.
137
138 .. module:: email.mime.audio
139
140 .. class:: MIMEAudio(_audiodata, _subtype=None, \
141 _encoder=email.encoders.encode_base64, \
142 *, policy=compat32, **_params)
143
144 Module: :mod:`email.mime.audio`
145
146 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
147 :class:`MIMEAudio` class is used to create MIME message objects of major type
148 :mimetype:`audio`. *_audiodata* contains the bytes for the raw audio data. If
149 this data can be decoded as au, wav, aiff, or aifc, then the
150 subtype will be automatically included in the :mailheader:`Content-Type` header.
151 Otherwise you can explicitly specify the audio subtype via the *_subtype*
152 argument. If the minor type could not be guessed and *_subtype* was not given,
153 then :exc:`TypeError` is raised.
154
155 Optional *_encoder* is a callable (i.e. function) which will perform the actual
156 encoding of the audio data for transport. This callable takes one argument,
157 which is the :class:`MIMEAudio` instance. It should use
158 :meth:`~email.message.Message.get_payload` and
159 :meth:`~email.message.Message.set_payload` to change the payload to encoded
160 form. It should also add
161 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
162 object as necessary. The default encoding is base64. See the
163 :mod:`email.encoders` module for a list of the built-in encoders.
164
165 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
166
167 *_params* are passed straight through to the base class constructor.
168
169 .. versionchanged:: 3.6
170 Added *policy* keyword-only parameter.
171
172 .. module:: email.mime.image
173
174 .. class:: MIMEImage(_imagedata, _subtype=None, \
175 _encoder=email.encoders.encode_base64, \
176 *, policy=compat32, **_params)
177
178 Module: :mod:`email.mime.image`
179
180 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
181 :class:`MIMEImage` class is used to create MIME message objects of major type
182 :mimetype:`image`. *_imagedata* contains the bytes for the raw image data. If
183 this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm,
184 rast, xbm, bmp, webp, and exr attempted), then the subtype will be
185 automatically included in the :mailheader:`Content-Type` header. Otherwise
186 you can explicitly specify the image subtype via the *_subtype* argument.
187 If the minor type could not be guessed and *_subtype* was not given, then
188 :exc:`TypeError` is raised.
189
190 Optional *_encoder* is a callable (i.e. function) which will perform the actual
191 encoding of the image data for transport. This callable takes one argument,
192 which is the :class:`MIMEImage` instance. It should use
193 :meth:`~email.message.Message.get_payload` and
194 :meth:`~email.message.Message.set_payload` to change the payload to encoded
195 form. It should also add
196 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
197 object as necessary. The default encoding is base64. See the
198 :mod:`email.encoders` module for a list of the built-in encoders.
199
200 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
201
202 *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
203 constructor.
204
205 .. versionchanged:: 3.6
206 Added *policy* keyword-only parameter.
207
208 .. module:: email.mime.message
209
210 .. class:: MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)
211
212 Module: :mod:`email.mime.message`
213
214 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
215 :class:`MIMEMessage` class is used to create MIME objects of main type
216 :mimetype:`message`. *_msg* is used as the payload, and must be an instance
217 of class :class:`~email.message.Message` (or a subclass thereof), otherwise
218 a :exc:`TypeError` is raised.
219
220 Optional *_subtype* sets the subtype of the message; it defaults to
221 :mimetype:`rfc822`.
222
223 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
224
225 .. versionchanged:: 3.6
226 Added *policy* keyword-only parameter.
227
228 .. module:: email.mime.text
229
230 .. class:: MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)
231
232 Module: :mod:`email.mime.text`
233
234 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
235 :class:`MIMEText` class is used to create MIME objects of major type
236 :mimetype:`text`. *_text* is the string for the payload. *_subtype* is the
237 minor type and defaults to :mimetype:`plain`. *_charset* is the character
238 set of the text and is passed as an argument to the
239 :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
240 to ``us-ascii`` if the string contains only ``ascii`` code points, and
241 ``utf-8`` otherwise. The *_charset* parameter accepts either a string or a
242 :class:`~email.charset.Charset` instance.
243
244 Unless the *_charset* argument is explicitly set to ``None``, the
245 MIMEText object created will have both a :mailheader:`Content-Type` header
246 with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding`
247 header. This means that a subsequent ``set_payload`` call will not result
248 in an encoded payload, even if a charset is passed in the ``set_payload``
249 command. You can "reset" this behavior by deleting the
250 ``Content-Transfer-Encoding`` header, after which a ``set_payload`` call
251 will automatically encode the new payload (and add a new
252 :mailheader:`Content-Transfer-Encoding` header).
253
254 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
255
256 .. versionchanged:: 3.5
257 *_charset* also accepts :class:`~email.charset.Charset` instances.
258
259 .. versionchanged:: 3.6
260 Added *policy* keyword-only parameter.