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="node588.html" /> | |
13 | <link rel="prev" href="module-email.Parser.html" /> | |
14 | <link rel="parent" href="module-email.html" /> | |
15 | <link rel="next" href="node587.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>12.2.3 Generating MIME documents</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.2.3 Additional notes" | |
25 | href="node585.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.3.1 Deprecated methods" | |
31 | href="node587.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="node585.html">12.2.2.3 Additional notes</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="node587.html">12.2.3.1 Deprecated methods</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION0014230000000000000000"> | |
56 | 12.2.3 Generating MIME documents</A> | |
57 | </H2> | |
58 | <A NAME="module-email.Generator"></A> | |
59 | ||
60 | <P> | |
61 | One of the most common tasks is to generate the flat text of the email | |
62 | message represented by a message object structure. You will need to do | |
63 | this if you want to send your message via the <tt class="module"><a href="module-smtplib.html">smtplib</a></tt> | |
64 | module or the <tt class="module"><a href="module-nntplib.html">nntplib</a></tt> module, or print the message on the | |
65 | console. Taking a message object structure and producing a flat text | |
66 | document is the job of the <tt class="class">Generator</tt> class. | |
67 | ||
68 | <P> | |
69 | Again, as with the <tt class="module"><a href="module-email.Parser.html">email.Parser</a></tt> module, you aren't limited | |
70 | to the functionality of the bundled generator; you could write one | |
71 | from scratch yourself. However the bundled generator knows how to | |
72 | generate most email in a standards-compliant way, should handle MIME | |
73 | and non-MIME email messages just fine, and is designed so that the | |
74 | transformation from flat text, to a message structure via the | |
75 | <tt class="class">Parser</tt> class, and back to flat text, is idempotent (the input | |
76 | is identical to the output). | |
77 | ||
78 | <P> | |
79 | Here are the public methods of the <tt class="class">Generator</tt> class: | |
80 | ||
81 | <P> | |
82 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
83 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3885' xml:id='l2h-3885' class="class">Generator</tt></b>(</nobr></td> | |
84 | <td><var>outfp</var><big>[</big><var>, mangle_from_</var><big>[</big><var>, | |
85 | maxheaderlen</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
86 | <dd> | |
87 | The constructor for the <tt class="class">Generator</tt> class takes a file-like | |
88 | object called <var>outfp</var> for an argument. <var>outfp</var> must support | |
89 | the <tt class="method">write()</tt> method and be usable as the output file in a | |
90 | Python extended print statement. | |
91 | ||
92 | <P> | |
93 | Optional <var>mangle_from_</var> is a flag that, when <code>True</code>, puts a | |
94 | "<tt class="samp">></tt>" character in front of any line in the body that starts exactly as | |
95 | "<tt class="samp">From </tt>", i.e. <code>From</code> followed by a space at the beginning of the | |
96 | line. This is the only guaranteed portable way to avoid having such | |
97 | lines be mistaken for a Unix mailbox format envelope header separator (see | |
98 | <a class="ulink" href="http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html" | |
99 | >WHY THE CONTENT-LENGTH FORMAT IS BAD</a> | |
100 | for details). <var>mangle_from_</var> defaults to <code>True</code>, but you | |
101 | might want to set this to <code>False</code> if you are not writing Unix | |
102 | mailbox format files. | |
103 | ||
104 | <P> | |
105 | Optional <var>maxheaderlen</var> specifies the longest length for a | |
106 | non-continued header. When a header line is longer than | |
107 | <var>maxheaderlen</var> (in characters, with tabs expanded to 8 spaces), | |
108 | the header will be split as defined in the <tt class="module">email.Header</tt> | |
109 | class. Set to zero to disable header wrapping. The default is 78, as | |
110 | recommended (but not required) by <a class="rfc" id='rfcref-90852' xml:id='rfcref-90852' | |
111 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>. | |
112 | </dl> | |
113 | ||
114 | <P> | |
115 | The other public <tt class="class">Generator</tt> methods are: | |
116 | ||
117 | <P> | |
118 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
119 | <td><nobr><b><tt id='l2h-3886' xml:id='l2h-3886' class="method">flatten</tt></b>(</nobr></td> | |
120 | <td><var>msg</var><big>[</big><var>, unixfrom</var><big>]</big><var></var>)</td></tr></table></dt> | |
121 | <dd> | |
122 | Print the textual representation of the message object structure rooted at | |
123 | <var>msg</var> to the output file specified when the <tt class="class">Generator</tt> | |
124 | instance was created. Subparts are visited depth-first and the | |
125 | resulting text will be properly MIME encoded. | |
126 | ||
127 | <P> | |
128 | Optional <var>unixfrom</var> is a flag that forces the printing of the | |
129 | envelope header delimiter before the first <a class="rfc" id='rfcref-90854' xml:id='rfcref-90854' | |
130 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> header of the | |
131 | root message object. If the root object has no envelope header, a | |
132 | standard one is crafted. By default, this is set to <code>False</code> to | |
133 | inhibit the printing of the envelope delimiter. | |
134 | ||
135 | <P> | |
136 | Note that for subparts, no envelope header is ever printed. | |
137 | ||
138 | <P> | |
139 | ||
140 | <span class="versionnote">New in version 2.2.2.</span> | |
141 | ||
142 | </dl> | |
143 | ||
144 | <P> | |
145 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
146 | <td><nobr><b><tt id='l2h-3887' xml:id='l2h-3887' class="method">clone</tt></b>(</nobr></td> | |
147 | <td><var>fp</var>)</td></tr></table></dt> | |
148 | <dd> | |
149 | Return an independent clone of this <tt class="class">Generator</tt> instance with | |
150 | the exact same options. | |
151 | ||
152 | <P> | |
153 | ||
154 | <span class="versionnote">New in version 2.2.2.</span> | |
155 | ||
156 | </dl> | |
157 | ||
158 | <P> | |
159 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
160 | <td><nobr><b><tt id='l2h-3888' xml:id='l2h-3888' class="method">write</tt></b>(</nobr></td> | |
161 | <td><var>s</var>)</td></tr></table></dt> | |
162 | <dd> | |
163 | Write the string <var>s</var> to the underlying file object, | |
164 | i.e. <var>outfp</var> passed to <tt class="class">Generator</tt>'s constructor. This | |
165 | provides just enough file-like API for <tt class="class">Generator</tt> instances to | |
166 | be used in extended print statements. | |
167 | </dl> | |
168 | ||
169 | <P> | |
170 | As a convenience, see the methods <tt class="method">Message.as_string()</tt> and | |
171 | <code>str(aMessage)</code>, a.k.a. <tt class="method">Message.__str__()</tt>, which | |
172 | simplify the generation of a formatted string representation of a | |
173 | message object. For more detail, see <tt class="module"><a href="module-email.Message.html">email.Message</a></tt>. | |
174 | ||
175 | <P> | |
176 | The <tt class="module">email.Generator</tt> module also provides a derived class, | |
177 | called <tt class="class">DecodedGenerator</tt> which is like the <tt class="class">Generator</tt> | |
178 | base class, except that non-<span class="mimetype">text</span> parts are substituted with | |
179 | a format string representing the part. | |
180 | ||
181 | <P> | |
182 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
183 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3889' xml:id='l2h-3889' class="class">DecodedGenerator</tt></b>(</nobr></td> | |
184 | <td><var>outfp</var><big>[</big><var>, mangle_from_</var><big>[</big><var>, | |
185 | maxheaderlen</var><big>[</big><var>, fmt</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
186 | <dd> | |
187 | ||
188 | <P> | |
189 | This class, derived from <tt class="class">Generator</tt> walks through all the | |
190 | subparts of a message. If the subpart is of main type | |
191 | <span class="mimetype">text</span>, then it prints the decoded payload of the subpart. | |
192 | Optional <var>_mangle_from_</var> and <var>maxheaderlen</var> are as with the | |
193 | <tt class="class">Generator</tt> base class. | |
194 | ||
195 | <P> | |
196 | If the subpart is not of main type <span class="mimetype">text</span>, optional <var>fmt</var> | |
197 | is a format string that is used instead of the message payload. | |
198 | <var>fmt</var> is expanded with the following keywords, "<tt class="samp">%(keyword)s</tt>"format: | |
199 | ||
200 | <P> | |
201 | ||
202 | <UL> | |
203 | <LI><code>type</code> - Full MIME type of the non-<span class="mimetype">text</span> part | |
204 | ||
205 | <P> | |
206 | </LI> | |
207 | <LI><code>maintype</code> - Main MIME type of the non-<span class="mimetype">text</span> part | |
208 | ||
209 | <P> | |
210 | </LI> | |
211 | <LI><code>subtype</code> - Sub-MIME type of the non-<span class="mimetype">text</span> part | |
212 | ||
213 | <P> | |
214 | </LI> | |
215 | <LI><code>filename</code> - Filename of the non-<span class="mimetype">text</span> part | |
216 | ||
217 | <P> | |
218 | </LI> | |
219 | <LI><code>description</code> - Description associated with the | |
220 | non-<span class="mimetype">text</span> part | |
221 | ||
222 | <P> | |
223 | </LI> | |
224 | <LI><code>encoding</code> - Content transfer encoding of the | |
225 | non-<span class="mimetype">text</span> part | |
226 | ||
227 | <P> | |
228 | </LI> | |
229 | </UL> | |
230 | ||
231 | <P> | |
232 | The default value for <var>fmt</var> is <code>None</code>, meaning | |
233 | ||
234 | <P> | |
235 | <div class="verbatim"><pre> | |
236 | [Non-text (%(type)s) part of message omitted, filename %(filename)s] | |
237 | </pre></div> | |
238 | ||
239 | <P> | |
240 | ||
241 | <span class="versionnote">New in version 2.2.2.</span> | |
242 | ||
243 | </dl> | |
244 | ||
245 | <P> | |
246 | ||
247 | <p><br /></p><hr class='online-navigation' /> | |
248 | <div class='online-navigation'> | |
249 | <!--Table of Child-Links--> | |
250 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> | |
251 | ||
252 | <UL CLASS="ChildLinks"> | |
253 | <LI><A href="node587.html">12.2.3.1 Deprecated methods</a> | |
254 | </ul> | |
255 | <!--End of Table of Child-Links--> | |
256 | </div> | |
257 | ||
258 | <DIV CLASS="navigation"> | |
259 | <div class='online-navigation'> | |
260 | <p></p><hr /> | |
261 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
262 | <tr> | |
263 | <td class='online-navigation'><a rel="prev" title="12.2.2.3 Additional notes" | |
264 | href="node585.html"><img src='../icons/previous.png' | |
265 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
266 | <td class='online-navigation'><a rel="parent" title="12.2 email " | |
267 | href="module-email.html"><img src='../icons/up.png' | |
268 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
269 | <td class='online-navigation'><a rel="next" title="12.2.3.1 Deprecated methods" | |
270 | href="node587.html"><img src='../icons/next.png' | |
271 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
272 | <td align="center" width="100%">Python Library Reference</td> | |
273 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
274 | href="contents.html"><img src='../icons/contents.png' | |
275 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
276 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
277 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
278 | <td class='online-navigation'><a rel="index" title="Index" | |
279 | href="genindex.html"><img src='../icons/index.png' | |
280 | border='0' height='32' alt='Index' width='32' /></A></td> | |
281 | </tr></table> | |
282 | <div class='online-navigation'> | |
283 | <b class="navlabel">Previous:</b> | |
284 | <a class="sectref" rel="prev" href="node585.html">12.2.2.3 Additional notes</A> | |
285 | <b class="navlabel">Up:</b> | |
286 | <a class="sectref" rel="parent" href="module-email.html">12.2 email </A> | |
287 | <b class="navlabel">Next:</b> | |
288 | <a class="sectref" rel="next" href="node587.html">12.2.3.1 Deprecated methods</A> | |
289 | </div> | |
290 | </div> | |
291 | <hr /> | |
292 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
293 | </DIV> | |
294 | <!--End of Navigation Panel--> | |
295 | <ADDRESS> | |
296 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
297 | </ADDRESS> | |
298 | </BODY> | |
299 | </HTML> |