| 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.Parser.html" /> |
| 13 | <link rel="prev" href="module-email.html" /> |
| 14 | <link rel="parent" href="module-email.html" /> |
| 15 | <link rel="next" href="node581.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>12.2.1 Representing an email message</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 email " |
| 25 | href="module-email.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.1.1 Deprecated methods" |
| 31 | href="node581.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="module-email.html">12.2 email </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="node581.html">12.2.1.1 Deprecated methods</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION0014210000000000000000"> |
| 56 | 12.2.1 Representing an email message</A> |
| 57 | </H2> |
| 58 | <A NAME="module-email.Message"></A> |
| 59 | |
| 60 | <P> |
| 61 | The central class in the <tt class="module">email</tt> package is the |
| 62 | <tt class="class">Message</tt> class; it is the base class for the <tt class="module">email</tt> |
| 63 | object model. <tt class="class">Message</tt> provides the core functionality for |
| 64 | setting and querying header fields, and for accessing message bodies. |
| 65 | |
| 66 | <P> |
| 67 | Conceptually, a <tt class="class">Message</tt> object consists of <em>headers</em> and |
| 68 | <em>payloads</em>. Headers are <a class="rfc" id='rfcref-90805' xml:id='rfcref-90805' |
| 69 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> style field names and |
| 70 | values where the field name and value are separated by a colon. The |
| 71 | colon is not part of either the field name or the field value. |
| 72 | |
| 73 | <P> |
| 74 | Headers are stored and returned in case-preserving form but are |
| 75 | matched case-insensitively. There may also be a single envelope |
| 76 | header, also known as the <em>Unix-From</em> header or the |
| 77 | <code>From_</code> header. The payload is either a string in the case of |
| 78 | simple message objects or a list of <tt class="class">Message</tt> objects for |
| 79 | MIME container documents (e.g. <span class="mimetype">multipart/*</span> and |
| 80 | <span class="mimetype">message/rfc822</span>). |
| 81 | |
| 82 | <P> |
| 83 | <tt class="class">Message</tt> objects provide a mapping style interface for |
| 84 | accessing the message headers, and an explicit interface for accessing |
| 85 | both the headers and the payload. It provides convenience methods for |
| 86 | generating a flat text representation of the message object tree, for |
| 87 | accessing commonly used header parameters, and for recursively walking |
| 88 | over the object tree. |
| 89 | |
| 90 | <P> |
| 91 | Here are the methods of the <tt class="class">Message</tt> class: |
| 92 | |
| 93 | <P> |
| 94 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 95 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3829' xml:id='l2h-3829' class="class">Message</tt></b>(</nobr></td> |
| 96 | <td><var></var>)</td></tr></table></dt> |
| 97 | <dd> |
| 98 | The constructor takes no arguments. |
| 99 | </dl> |
| 100 | |
| 101 | <P> |
| 102 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 103 | <td><nobr><b><tt id='l2h-3830' xml:id='l2h-3830' class="method">as_string</tt></b>(</nobr></td> |
| 104 | <td><var></var><big>[</big><var>unixfrom</var><big>]</big><var></var>)</td></tr></table></dt> |
| 105 | <dd> |
| 106 | Return the entire message flatten as a string. When optional |
| 107 | <var>unixfrom</var> is <code>True</code>, the envelope header is included in the |
| 108 | returned string. <var>unixfrom</var> defaults to <code>False</code>. |
| 109 | |
| 110 | <P> |
| 111 | Note that this method is provided as a convenience and may not always format |
| 112 | the message the way you want. For example, by default it mangles lines that |
| 113 | begin with <code>From </code>. For more flexibility, instantiate a |
| 114 | <tt class="class">Generator</tt> instance and use its |
| 115 | <tt class="method">flatten()</tt> method directly. For example: |
| 116 | |
| 117 | <P> |
| 118 | <div class="verbatim"><pre> |
| 119 | from cStringIO import StringIO |
| 120 | from email.Generator import Generator |
| 121 | fp = StringIO() |
| 122 | g = Generator(fp, mangle_from_=False, maxheaderlen=60) |
| 123 | g.flatten(msg) |
| 124 | text = fp.getvalue() |
| 125 | </pre></div> |
| 126 | </dl> |
| 127 | |
| 128 | <P> |
| 129 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 130 | <td><nobr><b><tt id='l2h-3831' xml:id='l2h-3831' class="method">__str__</tt></b>(</nobr></td> |
| 131 | <td><var></var>)</td></tr></table></dt> |
| 132 | <dd> |
| 133 | Equivalent to <tt class="method">as_string(unixfrom=True)</tt>. |
| 134 | </dl> |
| 135 | |
| 136 | <P> |
| 137 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 138 | <td><nobr><b><tt id='l2h-3832' xml:id='l2h-3832' class="method">is_multipart</tt></b>(</nobr></td> |
| 139 | <td><var></var>)</td></tr></table></dt> |
| 140 | <dd> |
| 141 | Return <code>True</code> if the message's payload is a list of |
| 142 | sub-<tt class="class">Message</tt> objects, otherwise return <code>False</code>. When |
| 143 | <tt class="method">is_multipart()</tt> returns False, the payload should be a string |
| 144 | object. |
| 145 | </dl> |
| 146 | |
| 147 | <P> |
| 148 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 149 | <td><nobr><b><tt id='l2h-3833' xml:id='l2h-3833' class="method">set_unixfrom</tt></b>(</nobr></td> |
| 150 | <td><var>unixfrom</var>)</td></tr></table></dt> |
| 151 | <dd> |
| 152 | Set the message's envelope header to <var>unixfrom</var>, which should be a string. |
| 153 | </dl> |
| 154 | |
| 155 | <P> |
| 156 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 157 | <td><nobr><b><tt id='l2h-3834' xml:id='l2h-3834' class="method">get_unixfrom</tt></b>(</nobr></td> |
| 158 | <td><var></var>)</td></tr></table></dt> |
| 159 | <dd> |
| 160 | Return the message's envelope header. Defaults to <code>None</code> if the |
| 161 | envelope header was never set. |
| 162 | </dl> |
| 163 | |
| 164 | <P> |
| 165 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 166 | <td><nobr><b><tt id='l2h-3835' xml:id='l2h-3835' class="method">attach</tt></b>(</nobr></td> |
| 167 | <td><var>payload</var>)</td></tr></table></dt> |
| 168 | <dd> |
| 169 | Add the given <var>payload</var> to the current payload, which must be |
| 170 | <code>None</code> or a list of <tt class="class">Message</tt> objects before the call. |
| 171 | After the call, the payload will always be a list of <tt class="class">Message</tt> |
| 172 | objects. If you want to set the payload to a scalar object (e.g. a |
| 173 | string), use <tt class="method">set_payload()</tt> instead. |
| 174 | </dl> |
| 175 | |
| 176 | <P> |
| 177 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 178 | <td><nobr><b><tt id='l2h-3836' xml:id='l2h-3836' class="method">get_payload</tt></b>(</nobr></td> |
| 179 | <td><var></var><big>[</big><var>i</var><big>[</big><var>, decode</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 180 | <dd> |
| 181 | Return a reference the current payload, which will be a list of |
| 182 | <tt class="class">Message</tt> objects when <tt class="method">is_multipart()</tt> is <code>True</code>, or a |
| 183 | string when <tt class="method">is_multipart()</tt> is <code>False</code>. If the |
| 184 | payload is a list and you mutate the list object, you modify the |
| 185 | message's payload in place. |
| 186 | |
| 187 | <P> |
| 188 | With optional argument <var>i</var>, <tt class="method">get_payload()</tt> will return the |
| 189 | <var>i</var>-th element of the payload, counting from zero, if |
| 190 | <tt class="method">is_multipart()</tt> is <code>True</code>. An <tt class="exception">IndexError</tt> |
| 191 | will be raised if <var>i</var> is less than 0 or greater than or equal to |
| 192 | the number of items in the payload. If the payload is a string |
| 193 | (i.e. <tt class="method">is_multipart()</tt> is <code>False</code>) and <var>i</var> is given, a |
| 194 | <tt class="exception">TypeError</tt> is raised. |
| 195 | |
| 196 | <P> |
| 197 | Optional <var>decode</var> is a flag indicating whether the payload should be |
| 198 | decoded or not, according to the <span class="mailheader">Content-Transfer-Encoding:</span> header. |
| 199 | When <code>True</code> and the message is not a multipart, the payload will be |
| 200 | decoded if this header's value is "<tt class="samp">quoted-printable</tt>" or |
| 201 | "<tt class="samp">base64</tt>". If some other encoding is used, or |
| 202 | <span class="mailheader">Content-Transfer-Encoding:</span> header is |
| 203 | missing, or if the payload has bogus base64 data, the payload is |
| 204 | returned as-is (undecoded). If the message is a multipart and the |
| 205 | <var>decode</var> flag is <code>True</code>, then <code>None</code> is returned. The |
| 206 | default for <var>decode</var> is <code>False</code>. |
| 207 | </dl> |
| 208 | |
| 209 | <P> |
| 210 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 211 | <td><nobr><b><tt id='l2h-3837' xml:id='l2h-3837' class="method">set_payload</tt></b>(</nobr></td> |
| 212 | <td><var>payload</var><big>[</big><var>, charset</var><big>]</big><var></var>)</td></tr></table></dt> |
| 213 | <dd> |
| 214 | Set the entire message object's payload to <var>payload</var>. It is the |
| 215 | client's responsibility to ensure the payload invariants. Optional |
| 216 | <var>charset</var> sets the message's default character set; see |
| 217 | <tt class="method">set_charset()</tt> for details. |
| 218 | |
| 219 | <P> |
| 220 | |
| 221 | <span class="versionnote">Changed in version 2.2.2: |
| 222 | <var>charset</var> argument added.</span> |
| 223 | |
| 224 | </dl> |
| 225 | |
| 226 | <P> |
| 227 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 228 | <td><nobr><b><tt id='l2h-3838' xml:id='l2h-3838' class="method">set_charset</tt></b>(</nobr></td> |
| 229 | <td><var>charset</var>)</td></tr></table></dt> |
| 230 | <dd> |
| 231 | Set the character set of the payload to <var>charset</var>, which can |
| 232 | either be a <tt class="class">Charset</tt> instance (see <tt class="module"><a href="module-email.Charset.html">email.Charset</a></tt>), a |
| 233 | string naming a character set, |
| 234 | or <code>None</code>. If it is a string, it will be converted to a |
| 235 | <tt class="class">Charset</tt> instance. If <var>charset</var> is <code>None</code>, the |
| 236 | <code>charset</code> parameter will be removed from the |
| 237 | <span class="mailheader">Content-Type:</span> header. Anything else will generate a |
| 238 | <tt class="exception">TypeError</tt>. |
| 239 | |
| 240 | <P> |
| 241 | The message will be assumed to be of type <span class="mimetype">text/*</span> encoded with |
| 242 | <code>charset.input_charset</code>. It will be converted to |
| 243 | <code>charset.output_charset</code> |
| 244 | and encoded properly, if needed, when generating the plain text |
| 245 | representation of the message. MIME headers |
| 246 | (<span class="mailheader">MIME-Version:</span>, <span class="mailheader">Content-Type:</span>, |
| 247 | <span class="mailheader">Content-Transfer-Encoding:</span>) will be added as needed. |
| 248 | |
| 249 | <P> |
| 250 | |
| 251 | <span class="versionnote">New in version 2.2.2.</span> |
| 252 | |
| 253 | </dl> |
| 254 | |
| 255 | <P> |
| 256 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 257 | <td><nobr><b><tt id='l2h-3839' xml:id='l2h-3839' class="method">get_charset</tt></b>(</nobr></td> |
| 258 | <td><var></var>)</td></tr></table></dt> |
| 259 | <dd> |
| 260 | Return the <tt class="class">Charset</tt> instance associated with the message's payload. |
| 261 | |
| 262 | <span class="versionnote">New in version 2.2.2.</span> |
| 263 | |
| 264 | </dl> |
| 265 | |
| 266 | <P> |
| 267 | The following methods implement a mapping-like interface for accessing |
| 268 | the message's <a class="rfc" id='rfcref-90807' xml:id='rfcref-90807' |
| 269 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> headers. Note that there are some |
| 270 | semantic differences between these methods and a normal mapping |
| 271 | (i.e. dictionary) interface. For example, in a dictionary there are |
| 272 | no duplicate keys, but here there may be duplicate message headers. Also, |
| 273 | in dictionaries there is no guaranteed order to the keys returned by |
| 274 | <tt class="method">keys()</tt>, but in a <tt class="class">Message</tt> object, headers are always |
| 275 | returned in the order they appeared in the original message, or were |
| 276 | added to the message later. Any header deleted and then re-added are |
| 277 | always appended to the end of the header list. |
| 278 | |
| 279 | <P> |
| 280 | These semantic differences are intentional and are biased toward |
| 281 | maximal convenience. |
| 282 | |
| 283 | <P> |
| 284 | Note that in all cases, any envelope header present in the message is |
| 285 | not included in the mapping interface. |
| 286 | |
| 287 | <P> |
| 288 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 289 | <td><nobr><b><tt id='l2h-3840' xml:id='l2h-3840' class="method">__len__</tt></b>(</nobr></td> |
| 290 | <td><var></var>)</td></tr></table></dt> |
| 291 | <dd> |
| 292 | Return the total number of headers, including duplicates. |
| 293 | </dl> |
| 294 | |
| 295 | <P> |
| 296 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 297 | <td><nobr><b><tt id='l2h-3841' xml:id='l2h-3841' class="method">__contains__</tt></b>(</nobr></td> |
| 298 | <td><var>name</var>)</td></tr></table></dt> |
| 299 | <dd> |
| 300 | Return true if the message object has a field named <var>name</var>. |
| 301 | Matching is done case-insensitively and <var>name</var> should not include the |
| 302 | trailing colon. Used for the <code>in</code> operator, |
| 303 | e.g.: |
| 304 | |
| 305 | <P> |
| 306 | <div class="verbatim"><pre> |
| 307 | if 'message-id' in myMessage: |
| 308 | print 'Message-ID:', myMessage['message-id'] |
| 309 | </pre></div> |
| 310 | </dl> |
| 311 | |
| 312 | <P> |
| 313 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 314 | <td><nobr><b><tt id='l2h-3842' xml:id='l2h-3842' class="method">__getitem__</tt></b>(</nobr></td> |
| 315 | <td><var>name</var>)</td></tr></table></dt> |
| 316 | <dd> |
| 317 | Return the value of the named header field. <var>name</var> should not |
| 318 | include the colon field separator. If the header is missing, |
| 319 | <code>None</code> is returned; a <tt class="exception">KeyError</tt> is never raised. |
| 320 | |
| 321 | <P> |
| 322 | Note that if the named field appears more than once in the message's |
| 323 | headers, exactly which of those field values will be returned is |
| 324 | undefined. Use the <tt class="method">get_all()</tt> method to get the values of all |
| 325 | the extant named headers. |
| 326 | </dl> |
| 327 | |
| 328 | <P> |
| 329 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 330 | <td><nobr><b><tt id='l2h-3843' xml:id='l2h-3843' class="method">__setitem__</tt></b>(</nobr></td> |
| 331 | <td><var>name, val</var>)</td></tr></table></dt> |
| 332 | <dd> |
| 333 | Add a header to the message with field name <var>name</var> and value |
| 334 | <var>val</var>. The field is appended to the end of the message's existing |
| 335 | fields. |
| 336 | |
| 337 | <P> |
| 338 | Note that this does <em>not</em> overwrite or delete any existing header |
| 339 | with the same name. If you want to ensure that the new header is the |
| 340 | only one present in the message with field name |
| 341 | <var>name</var>, delete the field first, e.g.: |
| 342 | |
| 343 | <P> |
| 344 | <div class="verbatim"><pre> |
| 345 | del msg['subject'] |
| 346 | msg['subject'] = 'Python roolz!' |
| 347 | </pre></div> |
| 348 | </dl> |
| 349 | |
| 350 | <P> |
| 351 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 352 | <td><nobr><b><tt id='l2h-3844' xml:id='l2h-3844' class="method">__delitem__</tt></b>(</nobr></td> |
| 353 | <td><var>name</var>)</td></tr></table></dt> |
| 354 | <dd> |
| 355 | Delete all occurrences of the field with name <var>name</var> from the |
| 356 | message's headers. No exception is raised if the named field isn't |
| 357 | present in the headers. |
| 358 | </dl> |
| 359 | |
| 360 | <P> |
| 361 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 362 | <td><nobr><b><tt id='l2h-3845' xml:id='l2h-3845' class="method">has_key</tt></b>(</nobr></td> |
| 363 | <td><var>name</var>)</td></tr></table></dt> |
| 364 | <dd> |
| 365 | Return true if the message contains a header field named <var>name</var>, |
| 366 | otherwise return false. |
| 367 | </dl> |
| 368 | |
| 369 | <P> |
| 370 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 371 | <td><nobr><b><tt id='l2h-3846' xml:id='l2h-3846' class="method">keys</tt></b>(</nobr></td> |
| 372 | <td><var></var>)</td></tr></table></dt> |
| 373 | <dd> |
| 374 | Return a list of all the message's header field names. |
| 375 | </dl> |
| 376 | |
| 377 | <P> |
| 378 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 379 | <td><nobr><b><tt id='l2h-3847' xml:id='l2h-3847' class="method">values</tt></b>(</nobr></td> |
| 380 | <td><var></var>)</td></tr></table></dt> |
| 381 | <dd> |
| 382 | Return a list of all the message's field values. |
| 383 | </dl> |
| 384 | |
| 385 | <P> |
| 386 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 387 | <td><nobr><b><tt id='l2h-3848' xml:id='l2h-3848' class="method">items</tt></b>(</nobr></td> |
| 388 | <td><var></var>)</td></tr></table></dt> |
| 389 | <dd> |
| 390 | Return a list of 2-tuples containing all the message's field headers |
| 391 | and values. |
| 392 | </dl> |
| 393 | |
| 394 | <P> |
| 395 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 396 | <td><nobr><b><tt id='l2h-3849' xml:id='l2h-3849' class="method">get</tt></b>(</nobr></td> |
| 397 | <td><var>name</var><big>[</big><var>, failobj</var><big>]</big><var></var>)</td></tr></table></dt> |
| 398 | <dd> |
| 399 | Return the value of the named header field. This is identical to |
| 400 | <tt class="method">__getitem__()</tt> except that optional <var>failobj</var> is returned |
| 401 | if the named header is missing (defaults to <code>None</code>). |
| 402 | </dl> |
| 403 | |
| 404 | <P> |
| 405 | Here are some additional useful methods: |
| 406 | |
| 407 | <P> |
| 408 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 409 | <td><nobr><b><tt id='l2h-3850' xml:id='l2h-3850' class="method">get_all</tt></b>(</nobr></td> |
| 410 | <td><var>name</var><big>[</big><var>, failobj</var><big>]</big><var></var>)</td></tr></table></dt> |
| 411 | <dd> |
| 412 | Return a list of all the values for the field named <var>name</var>. |
| 413 | If there are no such named headers in the message, <var>failobj</var> is |
| 414 | returned (defaults to <code>None</code>). |
| 415 | </dl> |
| 416 | |
| 417 | <P> |
| 418 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 419 | <td><nobr><b><tt id='l2h-3851' xml:id='l2h-3851' class="method">add_header</tt></b>(</nobr></td> |
| 420 | <td><var>_name, _value, **_params</var>)</td></tr></table></dt> |
| 421 | <dd> |
| 422 | Extended header setting. This method is similar to |
| 423 | <tt class="method">__setitem__()</tt> except that additional header parameters can be |
| 424 | provided as keyword arguments. <var>_name</var> is the header field to add |
| 425 | and <var>_value</var> is the <em>primary</em> value for the header. |
| 426 | |
| 427 | <P> |
| 428 | For each item in the keyword argument dictionary <var>_params</var>, the |
| 429 | key is taken as the parameter name, with underscores converted to |
| 430 | dashes (since dashes are illegal in Python identifiers). Normally, |
| 431 | the parameter will be added as <code>key="value"</code> unless the value is |
| 432 | <code>None</code>, in which case only the key will be added. |
| 433 | |
| 434 | <P> |
| 435 | Here's an example: |
| 436 | |
| 437 | <P> |
| 438 | <div class="verbatim"><pre> |
| 439 | msg.add_header('Content-Disposition', 'attachment', filename='bud.gif') |
| 440 | </pre></div> |
| 441 | |
| 442 | <P> |
| 443 | This will add a header that looks like |
| 444 | |
| 445 | <P> |
| 446 | <div class="verbatim"><pre> |
| 447 | Content-Disposition: attachment; filename="bud.gif" |
| 448 | </pre></div> |
| 449 | </dl> |
| 450 | |
| 451 | <P> |
| 452 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 453 | <td><nobr><b><tt id='l2h-3852' xml:id='l2h-3852' class="method">replace_header</tt></b>(</nobr></td> |
| 454 | <td><var>_name, _value</var>)</td></tr></table></dt> |
| 455 | <dd> |
| 456 | Replace a header. Replace the first header found in the message that |
| 457 | matches <var>_name</var>, retaining header order and field name case. If |
| 458 | no matching header was found, a <tt class="exception">KeyError</tt> is raised. |
| 459 | |
| 460 | <P> |
| 461 | |
| 462 | <span class="versionnote">New in version 2.2.2.</span> |
| 463 | |
| 464 | </dl> |
| 465 | |
| 466 | <P> |
| 467 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 468 | <td><nobr><b><tt id='l2h-3853' xml:id='l2h-3853' class="method">get_content_type</tt></b>(</nobr></td> |
| 469 | <td><var></var>)</td></tr></table></dt> |
| 470 | <dd> |
| 471 | Return the message's content type. The returned string is coerced to |
| 472 | lower case of the form <span class="mimetype">maintype/subtype</span>. If there was no |
| 473 | <span class="mailheader">Content-Type:</span> header in the message the default type as |
| 474 | given by <tt class="method">get_default_type()</tt> will be returned. Since |
| 475 | according to <a class="rfc" id='rfcref-90809' xml:id='rfcref-90809' |
| 476 | href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, messages always have a default type, |
| 477 | <tt class="method">get_content_type()</tt> will always return a value. |
| 478 | |
| 479 | <P> |
| 480 | <a class="rfc" id='rfcref-90811' xml:id='rfcref-90811' |
| 481 | href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a> defines a message's default type to be |
| 482 | <span class="mimetype">text/plain</span> unless it appears inside a |
| 483 | <span class="mimetype">multipart/digest</span> container, in which case it would be |
| 484 | <span class="mimetype">message/rfc822</span>. If the <span class="mailheader">Content-Type:</span> header |
| 485 | has an invalid type specification, <a class="rfc" id='rfcref-90813' xml:id='rfcref-90813' |
| 486 | href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a> mandates that the |
| 487 | default type be <span class="mimetype">text/plain</span>. |
| 488 | |
| 489 | <P> |
| 490 | |
| 491 | <span class="versionnote">New in version 2.2.2.</span> |
| 492 | |
| 493 | </dl> |
| 494 | |
| 495 | <P> |
| 496 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 497 | <td><nobr><b><tt id='l2h-3854' xml:id='l2h-3854' class="method">get_content_maintype</tt></b>(</nobr></td> |
| 498 | <td><var></var>)</td></tr></table></dt> |
| 499 | <dd> |
| 500 | Return the message's main content type. This is the |
| 501 | <span class="mimetype">maintype</span> part of the string returned by |
| 502 | <tt class="method">get_content_type()</tt>. |
| 503 | |
| 504 | <P> |
| 505 | |
| 506 | <span class="versionnote">New in version 2.2.2.</span> |
| 507 | |
| 508 | </dl> |
| 509 | |
| 510 | <P> |
| 511 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 512 | <td><nobr><b><tt id='l2h-3855' xml:id='l2h-3855' class="method">get_content_subtype</tt></b>(</nobr></td> |
| 513 | <td><var></var>)</td></tr></table></dt> |
| 514 | <dd> |
| 515 | Return the message's sub-content type. This is the <span class="mimetype">subtype</span> |
| 516 | part of the string returned by <tt class="method">get_content_type()</tt>. |
| 517 | |
| 518 | <P> |
| 519 | |
| 520 | <span class="versionnote">New in version 2.2.2.</span> |
| 521 | |
| 522 | </dl> |
| 523 | |
| 524 | <P> |
| 525 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 526 | <td><nobr><b><tt id='l2h-3856' xml:id='l2h-3856' class="method">get_default_type</tt></b>(</nobr></td> |
| 527 | <td><var></var>)</td></tr></table></dt> |
| 528 | <dd> |
| 529 | Return the default content type. Most messages have a default content |
| 530 | type of <span class="mimetype">text/plain</span>, except for messages that are subparts |
| 531 | of <span class="mimetype">multipart/digest</span> containers. Such subparts have a |
| 532 | default content type of <span class="mimetype">message/rfc822</span>. |
| 533 | |
| 534 | <P> |
| 535 | |
| 536 | <span class="versionnote">New in version 2.2.2.</span> |
| 537 | |
| 538 | </dl> |
| 539 | |
| 540 | <P> |
| 541 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 542 | <td><nobr><b><tt id='l2h-3857' xml:id='l2h-3857' class="method">set_default_type</tt></b>(</nobr></td> |
| 543 | <td><var>ctype</var>)</td></tr></table></dt> |
| 544 | <dd> |
| 545 | Set the default content type. <var>ctype</var> should either be |
| 546 | <span class="mimetype">text/plain</span> or <span class="mimetype">message/rfc822</span>, although this is |
| 547 | not enforced. The default content type is not stored in the |
| 548 | <span class="mailheader">Content-Type:</span> header. |
| 549 | |
| 550 | <P> |
| 551 | |
| 552 | <span class="versionnote">New in version 2.2.2.</span> |
| 553 | |
| 554 | </dl> |
| 555 | |
| 556 | <P> |
| 557 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 558 | <td><nobr><b><tt id='l2h-3858' xml:id='l2h-3858' class="method">get_params</tt></b>(</nobr></td> |
| 559 | <td><var></var><big>[</big><var>failobj</var><big>[</big><var>, |
| 560 | header</var><big>[</big><var>, unquote</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 561 | <dd> |
| 562 | Return the message's <span class="mailheader">Content-Type:</span> parameters, as a list. The |
| 563 | elements of the returned list are 2-tuples of key/value pairs, as |
| 564 | split on the "<tt class="character">=</tt>" sign. The left hand side of the |
| 565 | "<tt class="character">=</tt>" is the key, while the right hand side is the value. If |
| 566 | there is no "<tt class="character">=</tt>" sign in the parameter the value is the empty |
| 567 | string, otherwise the value is as described in <tt class="method">get_param()</tt> and is |
| 568 | unquoted if optional <var>unquote</var> is <code>True</code> (the default). |
| 569 | |
| 570 | <P> |
| 571 | Optional <var>failobj</var> is the object to return if there is no |
| 572 | <span class="mailheader">Content-Type:</span> header. Optional <var>header</var> is the header to |
| 573 | search instead of <span class="mailheader">Content-Type:</span>. |
| 574 | |
| 575 | <P> |
| 576 | |
| 577 | <span class="versionnote">Changed in version 2.2.2: |
| 578 | <var>unquote</var> argument added.</span> |
| 579 | |
| 580 | </dl> |
| 581 | |
| 582 | <P> |
| 583 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 584 | <td><nobr><b><tt id='l2h-3859' xml:id='l2h-3859' class="method">get_param</tt></b>(</nobr></td> |
| 585 | <td><var>param</var><big>[</big><var>, |
| 586 | failobj</var><big>[</big><var>, header</var><big>[</big><var>, unquote</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 587 | <dd> |
| 588 | Return the value of the <span class="mailheader">Content-Type:</span> header's parameter |
| 589 | <var>param</var> as a string. If the message has no <span class="mailheader">Content-Type:</span> |
| 590 | header or if there is no such parameter, then <var>failobj</var> is |
| 591 | returned (defaults to <code>None</code>). |
| 592 | |
| 593 | <P> |
| 594 | Optional <var>header</var> if given, specifies the message header to use |
| 595 | instead of <span class="mailheader">Content-Type:</span>. |
| 596 | |
| 597 | <P> |
| 598 | Parameter keys are always compared case insensitively. The return |
| 599 | value can either be a string, or a 3-tuple if the parameter was |
| 600 | <a class="rfc" id='rfcref-90815' xml:id='rfcref-90815' |
| 601 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a> encoded. When it's a 3-tuple, the elements of the value are of |
| 602 | the form <code>(CHARSET, LANGUAGE, VALUE)</code>. Note that both <code>CHARSET</code> and |
| 603 | <code>LANGUAGE</code> can be <code>None</code>, in which case you should consider |
| 604 | <code>VALUE</code> to be encoded in the <code>us-ascii</code> charset. You can |
| 605 | usually ignore <code>LANGUAGE</code>. |
| 606 | |
| 607 | <P> |
| 608 | If your application doesn't care whether the parameter was encoded as in |
| 609 | <a class="rfc" id='rfcref-90817' xml:id='rfcref-90817' |
| 610 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>, you can collapse the parameter value by calling |
| 611 | <tt class="function">email.Utils.collapse_rfc2231_value()</tt>, passing in the return value |
| 612 | from <tt class="method">get_param()</tt>. This will return a suitably decoded Unicode string |
| 613 | whn the value is a tuple, or the original string unquoted if it isn't. For |
| 614 | example: |
| 615 | |
| 616 | <P> |
| 617 | <div class="verbatim"><pre> |
| 618 | rawparam = msg.get_param('foo') |
| 619 | param = email.Utils.collapse_rfc2231_value(rawparam) |
| 620 | </pre></div> |
| 621 | |
| 622 | <P> |
| 623 | In any case, the parameter value (either the returned string, or the |
| 624 | <code>VALUE</code> item in the 3-tuple) is always unquoted, unless |
| 625 | <var>unquote</var> is set to <code>False</code>. |
| 626 | |
| 627 | <P> |
| 628 | |
| 629 | <span class="versionnote">Changed in version 2.2.2: |
| 630 | <var>unquote</var> argument added, and 3-tuple return value |
| 631 | possible.</span> |
| 632 | |
| 633 | </dl> |
| 634 | |
| 635 | <P> |
| 636 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 637 | <td><nobr><b><tt id='l2h-3860' xml:id='l2h-3860' class="method">set_param</tt></b>(</nobr></td> |
| 638 | <td><var>param, value</var><big>[</big><var>, |
| 639 | header</var><big>[</big><var>, requote</var><big>[</big><var>, charset</var><big>[</big><var>, language</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 640 | <dd> |
| 641 | |
| 642 | <P> |
| 643 | Set a parameter in the <span class="mailheader">Content-Type:</span> header. If the |
| 644 | parameter already exists in the header, its value will be replaced |
| 645 | with <var>value</var>. If the <span class="mailheader">Content-Type:</span> header as not yet |
| 646 | been defined for this message, it will be set to <span class="mimetype">text/plain</span> |
| 647 | and the new parameter value will be appended as per <a class="rfc" id='rfcref-90819' xml:id='rfcref-90819' |
| 648 | href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>. |
| 649 | |
| 650 | <P> |
| 651 | Optional <var>header</var> specifies an alternative header to |
| 652 | <span class="mailheader">Content-Type:</span>, and all parameters will be quoted as |
| 653 | necessary unless optional <var>requote</var> is <code>False</code> (the default |
| 654 | is <code>True</code>). |
| 655 | |
| 656 | <P> |
| 657 | If optional <var>charset</var> is specified, the parameter will be encoded |
| 658 | according to <a class="rfc" id='rfcref-90821' xml:id='rfcref-90821' |
| 659 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. Optional <var>language</var> specifies the RFC |
| 660 | 2231 language, defaulting to the empty string. Both <var>charset</var> and |
| 661 | <var>language</var> should be strings. |
| 662 | |
| 663 | <P> |
| 664 | |
| 665 | <span class="versionnote">New in version 2.2.2.</span> |
| 666 | |
| 667 | </dl> |
| 668 | |
| 669 | <P> |
| 670 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 671 | <td><nobr><b><tt id='l2h-3861' xml:id='l2h-3861' class="method">del_param</tt></b>(</nobr></td> |
| 672 | <td><var>param</var><big>[</big><var>, header</var><big>[</big><var>, |
| 673 | requote</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 674 | <dd> |
| 675 | Remove the given parameter completely from the |
| 676 | <span class="mailheader">Content-Type:</span> header. The header will be re-written in |
| 677 | place without the parameter or its value. All values will be quoted |
| 678 | as necessary unless <var>requote</var> is <code>False</code> (the default is |
| 679 | <code>True</code>). Optional <var>header</var> specifies an alternative to |
| 680 | <span class="mailheader">Content-Type:</span>. |
| 681 | |
| 682 | <P> |
| 683 | |
| 684 | <span class="versionnote">New in version 2.2.2.</span> |
| 685 | |
| 686 | </dl> |
| 687 | |
| 688 | <P> |
| 689 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 690 | <td><nobr><b><tt id='l2h-3862' xml:id='l2h-3862' class="method">set_type</tt></b>(</nobr></td> |
| 691 | <td><var>type</var><big>[</big><var>, header</var><big>]</big><var></var><big>[</big><var>, |
| 692 | requote</var><big>]</big><var></var>)</td></tr></table></dt> |
| 693 | <dd> |
| 694 | Set the main type and subtype for the <span class="mailheader">Content-Type:</span> |
| 695 | header. <var>type</var> must be a string in the form |
| 696 | <span class="mimetype">maintype/subtype</span>, otherwise a <tt class="exception">ValueError</tt> is |
| 697 | raised. |
| 698 | |
| 699 | <P> |
| 700 | This method replaces the <span class="mailheader">Content-Type:</span> header, keeping all |
| 701 | the parameters in place. If <var>requote</var> is <code>False</code>, this |
| 702 | leaves the existing header's quoting as is, otherwise the parameters |
| 703 | will be quoted (the default). |
| 704 | |
| 705 | <P> |
| 706 | An alternative header can be specified in the <var>header</var> argument. |
| 707 | When the <span class="mailheader">Content-Type:</span> header is set a |
| 708 | <span class="mailheader">MIME-Version:</span> header is also added. |
| 709 | |
| 710 | <P> |
| 711 | |
| 712 | <span class="versionnote">New in version 2.2.2.</span> |
| 713 | |
| 714 | </dl> |
| 715 | |
| 716 | <P> |
| 717 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 718 | <td><nobr><b><tt id='l2h-3863' xml:id='l2h-3863' class="method">get_filename</tt></b>(</nobr></td> |
| 719 | <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt> |
| 720 | <dd> |
| 721 | Return the value of the <code>filename</code> parameter of the |
| 722 | <span class="mailheader">Content-Disposition:</span> header of the message, or <var>failobj</var> if |
| 723 | either the header is missing, or has no <code>filename</code> parameter. |
| 724 | The returned string will always be unquoted as per |
| 725 | <tt class="method">Utils.unquote()</tt>. |
| 726 | </dl> |
| 727 | |
| 728 | <P> |
| 729 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 730 | <td><nobr><b><tt id='l2h-3864' xml:id='l2h-3864' class="method">get_boundary</tt></b>(</nobr></td> |
| 731 | <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt> |
| 732 | <dd> |
| 733 | Return the value of the <code>boundary</code> parameter of the |
| 734 | <span class="mailheader">Content-Type:</span> header of the message, or <var>failobj</var> if either |
| 735 | the header is missing, or has no <code>boundary</code> parameter. The |
| 736 | returned string will always be unquoted as per |
| 737 | <tt class="method">Utils.unquote()</tt>. |
| 738 | </dl> |
| 739 | |
| 740 | <P> |
| 741 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 742 | <td><nobr><b><tt id='l2h-3865' xml:id='l2h-3865' class="method">set_boundary</tt></b>(</nobr></td> |
| 743 | <td><var>boundary</var>)</td></tr></table></dt> |
| 744 | <dd> |
| 745 | Set the <code>boundary</code> parameter of the <span class="mailheader">Content-Type:</span> |
| 746 | header to <var>boundary</var>. <tt class="method">set_boundary()</tt> will always quote |
| 747 | <var>boundary</var> if necessary. A <tt class="exception">HeaderParseError</tt> is raised |
| 748 | if the message object has no <span class="mailheader">Content-Type:</span> header. |
| 749 | |
| 750 | <P> |
| 751 | Note that using this method is subtly different than deleting the old |
| 752 | <span class="mailheader">Content-Type:</span> header and adding a new one with the new boundary |
| 753 | via <tt class="method">add_header()</tt>, because <tt class="method">set_boundary()</tt> preserves the |
| 754 | order of the <span class="mailheader">Content-Type:</span> header in the list of headers. |
| 755 | However, it does <em>not</em> preserve any continuation lines which may |
| 756 | have been present in the original <span class="mailheader">Content-Type:</span> header. |
| 757 | </dl> |
| 758 | |
| 759 | <P> |
| 760 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 761 | <td><nobr><b><tt id='l2h-3866' xml:id='l2h-3866' class="method">get_content_charset</tt></b>(</nobr></td> |
| 762 | <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt> |
| 763 | <dd> |
| 764 | Return the <code>charset</code> parameter of the <span class="mailheader">Content-Type:</span> |
| 765 | header, coerced to lower case. If there is no |
| 766 | <span class="mailheader">Content-Type:</span> header, or if that header has no |
| 767 | <code>charset</code> parameter, <var>failobj</var> is returned. |
| 768 | |
| 769 | <P> |
| 770 | Note that this method differs from <tt class="method">get_charset()</tt> which |
| 771 | returns the <tt class="class">Charset</tt> instance for the default encoding of the |
| 772 | message body. |
| 773 | |
| 774 | <P> |
| 775 | |
| 776 | <span class="versionnote">New in version 2.2.2.</span> |
| 777 | |
| 778 | </dl> |
| 779 | |
| 780 | <P> |
| 781 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 782 | <td><nobr><b><tt id='l2h-3867' xml:id='l2h-3867' class="method">get_charsets</tt></b>(</nobr></td> |
| 783 | <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt> |
| 784 | <dd> |
| 785 | Return a list containing the character set names in the message. If |
| 786 | the message is a <span class="mimetype">multipart</span>, then the list will contain one |
| 787 | element for each subpart in the payload, otherwise, it will be a list |
| 788 | of length 1. |
| 789 | |
| 790 | <P> |
| 791 | Each item in the list will be a string which is the value of the |
| 792 | <code>charset</code> parameter in the <span class="mailheader">Content-Type:</span> header for the |
| 793 | represented subpart. However, if the subpart has no |
| 794 | <span class="mailheader">Content-Type:</span> header, no <code>charset</code> parameter, or is not of |
| 795 | the <span class="mimetype">text</span> main MIME type, then that item in the returned list |
| 796 | will be <var>failobj</var>. |
| 797 | </dl> |
| 798 | |
| 799 | <P> |
| 800 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 801 | <td><nobr><b><tt id='l2h-3868' xml:id='l2h-3868' class="method">walk</tt></b>(</nobr></td> |
| 802 | <td><var></var>)</td></tr></table></dt> |
| 803 | <dd> |
| 804 | The <tt class="method">walk()</tt> method is an all-purpose generator which can be |
| 805 | used to iterate over all the parts and subparts of a message object |
| 806 | tree, in depth-first traversal order. You will typically use |
| 807 | <tt class="method">walk()</tt> as the iterator in a <code>for</code> loop; each |
| 808 | iteration returns the next subpart. |
| 809 | |
| 810 | <P> |
| 811 | Here's an example that prints the MIME type of every part of a |
| 812 | multipart message structure: |
| 813 | |
| 814 | <P> |
| 815 | <div class="verbatim"><pre> |
| 816 | >>> for part in msg.walk(): |
| 817 | ... print part.get_content_type() |
| 818 | multipart/report |
| 819 | text/plain |
| 820 | message/delivery-status |
| 821 | text/plain |
| 822 | text/plain |
| 823 | message/rfc822 |
| 824 | </pre></div> |
| 825 | </dl> |
| 826 | |
| 827 | <P> |
| 828 | <tt class="class">Message</tt> objects can also optionally contain two instance |
| 829 | attributes, which can be used when generating the plain text of a MIME |
| 830 | message. |
| 831 | |
| 832 | <P> |
| 833 | <dl><dt><b><tt id='l2h-3869' xml:id='l2h-3869'>preamble</tt></b></dt> |
| 834 | <dd> |
| 835 | The format of a MIME document allows for some text between the blank |
| 836 | line following the headers, and the first multipart boundary string. |
| 837 | Normally, this text is never visible in a MIME-aware mail reader |
| 838 | because it falls outside the standard MIME armor. However, when |
| 839 | viewing the raw text of the message, or when viewing the message in a |
| 840 | non-MIME aware reader, this text can become visible. |
| 841 | |
| 842 | <P> |
| 843 | The <var>preamble</var> attribute contains this leading extra-armor text |
| 844 | for MIME documents. When the <tt class="class">Parser</tt> discovers some text after |
| 845 | the headers but before the first boundary string, it assigns this text |
| 846 | to the message's <var>preamble</var> attribute. When the <tt class="class">Generator</tt> |
| 847 | is writing out the plain text representation of a MIME message, and it |
| 848 | finds the message has a <var>preamble</var> attribute, it will write this |
| 849 | text in the area between the headers and the first boundary. See |
| 850 | <tt class="module"><a href="module-email.Parser.html">email.Parser</a></tt> and <tt class="module"><a href="module-email.Generator.html">email.Generator</a></tt> for details. |
| 851 | |
| 852 | <P> |
| 853 | Note that if the message object has no preamble, the |
| 854 | <var>preamble</var> attribute will be <code>None</code>. |
| 855 | </dd></dl> |
| 856 | |
| 857 | <P> |
| 858 | <dl><dt><b><tt id='l2h-3870' xml:id='l2h-3870'>epilogue</tt></b></dt> |
| 859 | <dd> |
| 860 | The <var>epilogue</var> attribute acts the same way as the <var>preamble</var> |
| 861 | attribute, except that it contains text that appears between the last |
| 862 | boundary and the end of the message. |
| 863 | |
| 864 | <P> |
| 865 | One note: when generating the flat text for a <span class="mimetype">multipart</span> |
| 866 | message that has no <var>epilogue</var> (using the standard |
| 867 | <tt class="class">Generator</tt> class), no newline is added after the closing |
| 868 | boundary line. If the message object has an <var>epilogue</var> and its |
| 869 | value does not start with a newline, a newline is printed after the |
| 870 | closing boundary. This seems a little clumsy, but it makes the most |
| 871 | practical sense. The upshot is that if you want to ensure that a |
| 872 | newline get printed after your closing <span class="mimetype">multipart</span> boundary, |
| 873 | set the <var>epilogue</var> to the empty string. |
| 874 | </dd></dl> |
| 875 | |
| 876 | <P> |
| 877 | <dl><dt><b><tt id='l2h-3871' xml:id='l2h-3871'>defects</tt></b></dt> |
| 878 | <dd> |
| 879 | The <var>defects</var> attribute contains a list of all the problems found when |
| 880 | parsing this message. See <tt class="module"><a href="module-email.Errors.html">email.Errors</a></tt> for a detailed description |
| 881 | of the possible parsing defects. |
| 882 | |
| 883 | <P> |
| 884 | |
| 885 | <span class="versionnote">New in version 2.4.</span> |
| 886 | |
| 887 | </dd></dl> |
| 888 | |
| 889 | <P> |
| 890 | |
| 891 | <p><br /></p><hr class='online-navigation' /> |
| 892 | <div class='online-navigation'> |
| 893 | <!--Table of Child-Links--> |
| 894 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> |
| 895 | |
| 896 | <UL CLASS="ChildLinks"> |
| 897 | <LI><A href="node581.html">12.2.1.1 Deprecated methods</a> |
| 898 | </ul> |
| 899 | <!--End of Table of Child-Links--> |
| 900 | </div> |
| 901 | |
| 902 | <DIV CLASS="navigation"> |
| 903 | <div class='online-navigation'> |
| 904 | <p></p><hr /> |
| 905 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 906 | <tr> |
| 907 | <td class='online-navigation'><a rel="prev" title="12.2 email " |
| 908 | href="module-email.html"><img src='../icons/previous.png' |
| 909 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 910 | <td class='online-navigation'><a rel="parent" title="12.2 email " |
| 911 | href="module-email.html"><img src='../icons/up.png' |
| 912 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 913 | <td class='online-navigation'><a rel="next" title="12.2.1.1 Deprecated methods" |
| 914 | href="node581.html"><img src='../icons/next.png' |
| 915 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 916 | <td align="center" width="100%">Python Library Reference</td> |
| 917 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 918 | href="contents.html"><img src='../icons/contents.png' |
| 919 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 920 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 921 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 922 | <td class='online-navigation'><a rel="index" title="Index" |
| 923 | href="genindex.html"><img src='../icons/index.png' |
| 924 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 925 | </tr></table> |
| 926 | <div class='online-navigation'> |
| 927 | <b class="navlabel">Previous:</b> |
| 928 | <a class="sectref" rel="prev" href="module-email.html">12.2 email </A> |
| 929 | <b class="navlabel">Up:</b> |
| 930 | <a class="sectref" rel="parent" href="module-email.html">12.2 email </A> |
| 931 | <b class="navlabel">Next:</b> |
| 932 | <a class="sectref" rel="next" href="node581.html">12.2.1.1 Deprecated methods</A> |
| 933 | </div> |
| 934 | </div> |
| 935 | <hr /> |
| 936 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 937 | </DIV> |
| 938 | <!--End of Navigation Panel--> |
| 939 | <ADDRESS> |
| 940 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 941 | </ADDRESS> |
| 942 | </BODY> |
| 943 | </HTML> |