Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-email.Header.html" /> | |
13 | <link rel="prev" href="module-email.Generator.html" /> | |
14 | <link rel="parent" href="module-email.html" /> | |
15 | <link rel="next" href="module-email.Header.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>12.2.4 Creating email and MIME objects from scratch</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="12.2.3.1 Deprecated methods" | |
25 | href="node587.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="12.2 email " | |
28 | href="module-email.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="12.2.5 Internationalized headers" | |
31 | href="module-email.Header.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="node587.html">12.2.3.1 Deprecated methods</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="module-email.html">12.2 email </A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="module-email.Header.html">12.2.5 Internationalized headers</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION0014240000000000000000"> | |
56 | 12.2.4 Creating email and MIME objects from scratch</A> | |
57 | </H2> | |
58 | Ordinarily, you get a message object structure by passing a file or | |
59 | some text to a parser, which parses the text and returns the root | |
60 | message object. However you can also build a complete message | |
61 | structure from scratch, or even individual <tt class="class">Message</tt> objects by | |
62 | hand. In fact, you can also take an existing structure and add new | |
63 | <tt class="class">Message</tt> objects, move them around, etc. This makes a very | |
64 | convenient interface for slicing-and-dicing MIME messages. | |
65 | ||
66 | <P> | |
67 | You can create a new object structure by creating <tt class="class">Message</tt> | |
68 | instances, adding attachments and all the appropriate headers manually. | |
69 | For MIME messages though, the <tt class="module">email</tt> package provides some | |
70 | convenient subclasses to make things easier. Each of these classes | |
71 | should be imported from a module with the same name as the class, from | |
72 | within the <tt class="module">email</tt> package. E.g.: | |
73 | ||
74 | <P> | |
75 | <div class="verbatim"><pre> | |
76 | import email.MIMEImage.MIMEImage | |
77 | </pre></div> | |
78 | ||
79 | <P> | |
80 | or | |
81 | ||
82 | <P> | |
83 | <div class="verbatim"><pre> | |
84 | from email.MIMEText import MIMEText | |
85 | </pre></div> | |
86 | ||
87 | <P> | |
88 | Here are the classes: | |
89 | ||
90 | <P> | |
91 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
92 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3891' xml:id='l2h-3891' class="class">MIMEBase</tt></b>(</nobr></td> | |
93 | <td><var>_maintype, _subtype, **_params</var>)</td></tr></table></dt> | |
94 | <dd> | |
95 | This is the base class for all the MIME-specific subclasses of | |
96 | <tt class="class">Message</tt>. Ordinarily you won't create instances specifically | |
97 | of <tt class="class">MIMEBase</tt>, although you could. <tt class="class">MIMEBase</tt> is provided | |
98 | primarily as a convenient base class for more specific MIME-aware | |
99 | subclasses. | |
100 | ||
101 | <P> | |
102 | <var>_maintype</var> is the <span class="mailheader">Content-Type:</span> major type | |
103 | (e.g. <span class="mimetype">text</span> or <span class="mimetype">image</span>), and <var>_subtype</var> is the | |
104 | <span class="mailheader">Content-Type:</span> minor type | |
105 | (e.g. <span class="mimetype">plain</span> or <span class="mimetype">gif</span>). <var>_params</var> is a parameter | |
106 | key/value dictionary and is passed directly to | |
107 | <tt class="method">Message.add_header()</tt>. | |
108 | ||
109 | <P> | |
110 | The <tt class="class">MIMEBase</tt> class always adds a <span class="mailheader">Content-Type:</span> header | |
111 | (based on <var>_maintype</var>, <var>_subtype</var>, and <var>_params</var>), and a | |
112 | <span class="mailheader">MIME-Version:</span> header (always set to <code>1.0</code>). | |
113 | </dl> | |
114 | ||
115 | <P> | |
116 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
117 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3892' xml:id='l2h-3892' class="class">MIMENonMultipart</tt></b>(</nobr></td> | |
118 | <td><var></var>)</td></tr></table></dt> | |
119 | <dd> | |
120 | A subclass of <tt class="class">MIMEBase</tt>, this is an intermediate base class for | |
121 | MIME messages that are not <span class="mimetype">multipart</span>. The primary purpose | |
122 | of this class is to prevent the use of the <tt class="method">attach()</tt> method, | |
123 | which only makes sense for <span class="mimetype">multipart</span> messages. If | |
124 | <tt class="method">attach()</tt> is called, a <tt class="exception">MultipartConversionError</tt> | |
125 | exception is raised. | |
126 | ||
127 | <P> | |
128 | ||
129 | <span class="versionnote">New in version 2.2.2.</span> | |
130 | ||
131 | </dl> | |
132 | ||
133 | <P> | |
134 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
135 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3893' xml:id='l2h-3893' class="class">MIMEMultipart</tt></b>(</nobr></td> | |
136 | <td><var></var><big>[</big><var>subtype</var><big>[</big><var>, | |
137 | boundary</var><big>[</big><var>, _subparts</var><big>[</big><var>, _params</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
138 | <dd> | |
139 | ||
140 | <P> | |
141 | A subclass of <tt class="class">MIMEBase</tt>, this is an intermediate base class for | |
142 | MIME messages that are <span class="mimetype">multipart</span>. Optional <var>_subtype</var> | |
143 | defaults to <span class="mimetype">mixed</span>, but can be used to specify the subtype | |
144 | of the message. A <span class="mailheader">Content-Type:</span> header of | |
145 | <span class="mimetype">multipart/</span><var>_subtype</var> will be added to the message | |
146 | object. A <span class="mailheader">MIME-Version:</span> header will also be added. | |
147 | ||
148 | <P> | |
149 | Optional <var>boundary</var> is the multipart boundary string. When | |
150 | <code>None</code> (the default), the boundary is calculated when needed. | |
151 | ||
152 | <P> | |
153 | <var>_subparts</var> is a sequence of initial subparts for the payload. It | |
154 | must be possible to convert this sequence to a list. You can always | |
155 | attach new subparts to the message by using the | |
156 | <tt class="method">Message.attach()</tt> method. | |
157 | ||
158 | <P> | |
159 | Additional parameters for the <span class="mailheader">Content-Type:</span> header are | |
160 | taken from the keyword arguments, or passed into the <var>_params</var> | |
161 | argument, which is a keyword dictionary. | |
162 | ||
163 | <P> | |
164 | ||
165 | <span class="versionnote">New in version 2.2.2.</span> | |
166 | ||
167 | </dl> | |
168 | ||
169 | <P> | |
170 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
171 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3894' xml:id='l2h-3894' class="class">MIMEAudio</tt></b>(</nobr></td> | |
172 | <td><var>_audiodata</var><big>[</big><var>, _subtype</var><big>[</big><var>, | |
173 | _encoder</var><big>[</big><var>, **_params</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
174 | <dd> | |
175 | ||
176 | <P> | |
177 | A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEAudio</tt> class | |
178 | is used to create MIME message objects of major type <span class="mimetype">audio</span>. | |
179 | <var>_audiodata</var> is a string containing the raw audio data. If this | |
180 | data can be decoded by the standard Python module <tt class="module"><a href="module-sndhdr.html">sndhdr</a></tt>, | |
181 | then the subtype will be automatically included in the | |
182 | <span class="mailheader">Content-Type:</span> header. Otherwise you can explicitly specify the | |
183 | audio subtype via the <var>_subtype</var> parameter. If the minor type could | |
184 | not be guessed and <var>_subtype</var> was not given, then <tt class="exception">TypeError</tt> | |
185 | is raised. | |
186 | ||
187 | <P> | |
188 | Optional <var>_encoder</var> is a callable (i.e. function) which will | |
189 | perform the actual encoding of the audio data for transport. This | |
190 | callable takes one argument, which is the <tt class="class">MIMEAudio</tt> instance. | |
191 | It should use <tt class="method">get_payload()</tt> and <tt class="method">set_payload()</tt> to | |
192 | change the payload to encoded form. It should also add any | |
193 | <span class="mailheader">Content-Transfer-Encoding:</span> or other headers to the message | |
194 | object as necessary. The default encoding is base64. See the | |
195 | <tt class="module"><a href="module-email.Encoders.html">email.Encoders</a></tt> module for a list of the built-in encoders. | |
196 | ||
197 | <P> | |
198 | <var>_params</var> are passed straight through to the base class constructor. | |
199 | </dl> | |
200 | ||
201 | <P> | |
202 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
203 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3895' xml:id='l2h-3895' class="class">MIMEImage</tt></b>(</nobr></td> | |
204 | <td><var>_imagedata</var><big>[</big><var>, _subtype</var><big>[</big><var>, | |
205 | _encoder</var><big>[</big><var>, **_params</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
206 | <dd> | |
207 | ||
208 | <P> | |
209 | A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEImage</tt> class is | |
210 | used to create MIME message objects of major type <span class="mimetype">image</span>. | |
211 | <var>_imagedata</var> is a string containing the raw image data. If this | |
212 | data can be decoded by the standard Python module <tt class="module"><a href="module-imghdr.html">imghdr</a></tt>, | |
213 | then the subtype will be automatically included in the | |
214 | <span class="mailheader">Content-Type:</span> header. Otherwise you can explicitly specify the | |
215 | image subtype via the <var>_subtype</var> parameter. If the minor type could | |
216 | not be guessed and <var>_subtype</var> was not given, then <tt class="exception">TypeError</tt> | |
217 | is raised. | |
218 | ||
219 | <P> | |
220 | Optional <var>_encoder</var> is a callable (i.e. function) which will | |
221 | perform the actual encoding of the image data for transport. This | |
222 | callable takes one argument, which is the <tt class="class">MIMEImage</tt> instance. | |
223 | It should use <tt class="method">get_payload()</tt> and <tt class="method">set_payload()</tt> to | |
224 | change the payload to encoded form. It should also add any | |
225 | <span class="mailheader">Content-Transfer-Encoding:</span> or other headers to the message | |
226 | object as necessary. The default encoding is base64. See the | |
227 | <tt class="module"><a href="module-email.Encoders.html">email.Encoders</a></tt> module for a list of the built-in encoders. | |
228 | ||
229 | <P> | |
230 | <var>_params</var> are passed straight through to the <tt class="class">MIMEBase</tt> | |
231 | constructor. | |
232 | </dl> | |
233 | ||
234 | <P> | |
235 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
236 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3896' xml:id='l2h-3896' class="class">MIMEMessage</tt></b>(</nobr></td> | |
237 | <td><var>_msg</var><big>[</big><var>, _subtype</var><big>]</big><var></var>)</td></tr></table></dt> | |
238 | <dd> | |
239 | A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEMessage</tt> class | |
240 | is used to create MIME objects of main type <span class="mimetype">message</span>. | |
241 | <var>_msg</var> is used as the payload, and must be an instance of class | |
242 | <tt class="class">Message</tt> (or a subclass thereof), otherwise a | |
243 | <tt class="exception">TypeError</tt> is raised. | |
244 | ||
245 | <P> | |
246 | Optional <var>_subtype</var> sets the subtype of the message; it defaults | |
247 | to <span class="mimetype">rfc822</span>. | |
248 | </dl> | |
249 | ||
250 | <P> | |
251 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
252 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3897' xml:id='l2h-3897' class="class">MIMEText</tt></b>(</nobr></td> | |
253 | <td><var>_text</var><big>[</big><var>, _subtype</var><big>[</big><var>, _charset</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
254 | <dd> | |
255 | A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEText</tt> class is | |
256 | used to create MIME objects of major type <span class="mimetype">text</span>. | |
257 | <var>_text</var> is the string for the payload. <var>_subtype</var> is the | |
258 | minor type and defaults to <span class="mimetype">plain</span>. <var>_charset</var> is the | |
259 | character set of the text and is passed as a parameter to the | |
260 | <tt class="class">MIMENonMultipart</tt> constructor; it defaults to <code>us-ascii</code>. No | |
261 | guessing or encoding is performed on the text data. | |
262 | ||
263 | <P> | |
264 | ||
265 | <span class="versionnote">Changed in version 2.4: | |
266 | The previously deprecated <var>_encoding</var> argument has | |
267 | been removed. Encoding happens implicitly based on the <var>_charset</var> | |
268 | argument.</span> | |
269 | ||
270 | </dl> | |
271 | ||
272 | <P> | |
273 | ||
274 | <DIV CLASS="navigation"> | |
275 | <div class='online-navigation'> | |
276 | <p></p><hr /> | |
277 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
278 | <tr> | |
279 | <td class='online-navigation'><a rel="prev" title="12.2.3.1 Deprecated methods" | |
280 | href="node587.html"><img src='../icons/previous.png' | |
281 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
282 | <td class='online-navigation'><a rel="parent" title="12.2 email " | |
283 | href="module-email.html"><img src='../icons/up.png' | |
284 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
285 | <td class='online-navigation'><a rel="next" title="12.2.5 Internationalized headers" | |
286 | href="module-email.Header.html"><img src='../icons/next.png' | |
287 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
288 | <td align="center" width="100%">Python Library Reference</td> | |
289 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
290 | href="contents.html"><img src='../icons/contents.png' | |
291 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
292 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
293 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
294 | <td class='online-navigation'><a rel="index" title="Index" | |
295 | href="genindex.html"><img src='../icons/index.png' | |
296 | border='0' height='32' alt='Index' width='32' /></A></td> | |
297 | </tr></table> | |
298 | <div class='online-navigation'> | |
299 | <b class="navlabel">Previous:</b> | |
300 | <a class="sectref" rel="prev" href="node587.html">12.2.3.1 Deprecated methods</A> | |
301 | <b class="navlabel">Up:</b> | |
302 | <a class="sectref" rel="parent" href="module-email.html">12.2 email </A> | |
303 | <b class="navlabel">Next:</b> | |
304 | <a class="sectref" rel="next" href="module-email.Header.html">12.2.5 Internationalized headers</A> | |
305 | </div> | |
306 | </div> | |
307 | <hr /> | |
308 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
309 | </DIV> | |
310 | <!--End of Navigation Panel--> | |
311 | <ADDRESS> | |
312 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
313 | </ADDRESS> | |
314 | </BODY> | |
315 | </HTML> |