1.. _compat32_message: 2 3:mod:`email.message.Message`: Representing an email message using the :data:`~email.policy.compat32` API 4-------------------------------------------------------------------------------------------------------- 5 6.. module:: email.message 7 :synopsis: The base class representing email messages in a fashion 8 backward compatible with python3.2 9 10 11The :class:`Message` class is very similar to the 12:class:`~email.message.EmailMessage` class, without the methods added by that 13class, and with the default behavior of certain other methods being slightly 14different. We also document here some methods that, while supported by the 15:class:`~email.message.EmailMessage` class, are not recommended unless you are 16dealing with legacy code. 17 18The philosophy and structure of the two classes is otherwise the same. 19 20This document describes the behavior under the default (for :class:`Message`) 21policy :attr:`~email.policy.Compat32`. If you are going to use another policy, 22you should be using the :class:`~email.message.EmailMessage` class instead. 23 24An email message consists of *headers* and a *payload*. Headers must be 25:rfc:`5233` style names and values, where the field name and value are 26separated by a colon. The colon is not part of either the field name or the 27field value. The payload may be a simple text message, or a binary object, or 28a structured sequence of sub-messages each with their own set of headers and 29their own payload. The latter type of payload is indicated by the message 30having a MIME type such as :mimetype:`multipart/\*` or 31:mimetype:`message/rfc822`. 32 33The conceptual model provided by a :class:`Message` object is that of an 34ordered dictionary of headers with additional methods for accessing both 35specialized information from the headers, for accessing the payload, for 36generating a serialized version of the message, and for recursively walking 37over the object tree. Note that duplicate headers are supported but special 38methods must be used to access them. 39 40The :class:`Message` pseudo-dictionary is indexed by the header names, which 41must be ASCII values. The values of the dictionary are strings that are 42supposed to contain only ASCII characters; there is some special handling for 43non-ASCII input, but it doesn't always produce the correct results. Headers 44are stored and returned in case-preserving form, but field names are matched 45case-insensitively. There may also be a single envelope header, also known as 46the *Unix-From* header or the ``From_`` header. The *payload* is either a 47string or bytes, in the case of simple message objects, or a list of 48:class:`Message` objects, for MIME container documents (e.g. 49:mimetype:`multipart/\*` and :mimetype:`message/rfc822`). 50 51Here are the methods of the :class:`Message` class: 52 53 54.. class:: Message(policy=compat32) 55 56 If *policy* is specified (it must be an instance of a :mod:`~email.policy` 57 class) use the rules it specifies to update and serialize the representation 58 of the message. If *policy* is not set, use the :class:`compat32 59 <email.policy.Compat32>` policy, which maintains backward compatibility with 60 the Python 3.2 version of the email package. For more information see the 61 :mod:`~email.policy` documentation. 62 63 .. versionchanged:: 3.3 The *policy* keyword argument was added. 64 65 66 .. method:: as_string(unixfrom=False, maxheaderlen=0, policy=None) 67 68 Return the entire message flattened as a string. When optional *unixfrom* 69 is true, the envelope header is included in the returned string. 70 *unixfrom* defaults to ``False``. For backward compabitility reasons, 71 *maxheaderlen* defaults to ``0``, so if you want a different value you 72 must override it explicitly (the value specified for *max_line_length* in 73 the policy will be ignored by this method). The *policy* argument may be 74 used to override the default policy obtained from the message instance. 75 This can be used to control some of the formatting produced by the 76 method, since the specified *policy* will be passed to the ``Generator``. 77 78 Flattening the message may trigger changes to the :class:`Message` if 79 defaults need to be filled in to complete the transformation to a string 80 (for example, MIME boundaries may be generated or modified). 81 82 Note that this method is provided as a convenience and may not always 83 format the message the way you want. For example, by default it does 84 not do the mangling of lines that begin with ``From`` that is 85 required by the unix mbox format. For more flexibility, instantiate a 86 :class:`~email.generator.Generator` instance and use its 87 :meth:`~email.generator.Generator.flatten` method directly. For example:: 88 89 from io import StringIO 90 from email.generator import Generator 91 fp = StringIO() 92 g = Generator(fp, mangle_from_=True, maxheaderlen=60) 93 g.flatten(msg) 94 text = fp.getvalue() 95 96 If the message object contains binary data that is not encoded according 97 to RFC standards, the non-compliant data will be replaced by unicode 98 "unknown character" code points. (See also :meth:`.as_bytes` and 99 :class:`~email.generator.BytesGenerator`.) 100 101 .. versionchanged:: 3.4 the *policy* keyword argument was added. 102 103 104 .. method:: __str__() 105 106 Equivalent to :meth:`.as_string()`. Allows ``str(msg)`` to produce a 107 string containing the formatted message. 108 109 110 .. method:: as_bytes(unixfrom=False, policy=None) 111 112 Return the entire message flattened as a bytes object. When optional 113 *unixfrom* is true, the envelope header is included in the returned 114 string. *unixfrom* defaults to ``False``. The *policy* argument may be 115 used to override the default policy obtained from the message instance. 116 This can be used to control some of the formatting produced by the 117 method, since the specified *policy* will be passed to the 118 ``BytesGenerator``. 119 120 Flattening the message may trigger changes to the :class:`Message` if 121 defaults need to be filled in to complete the transformation to a string 122 (for example, MIME boundaries may be generated or modified). 123 124 Note that this method is provided as a convenience and may not always 125 format the message the way you want. For example, by default it does 126 not do the mangling of lines that begin with ``From`` that is 127 required by the unix mbox format. For more flexibility, instantiate a 128 :class:`~email.generator.BytesGenerator` instance and use its 129 :meth:`~email.generator.BytesGenerator.flatten` method directly. 130 For example:: 131 132 from io import BytesIO 133 from email.generator import BytesGenerator 134 fp = BytesIO() 135 g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60) 136 g.flatten(msg) 137 text = fp.getvalue() 138 139 .. versionadded:: 3.4 140 141 142 .. method:: __bytes__() 143 144 Equivalent to :meth:`.as_bytes()`. Allows ``bytes(msg)`` to produce a 145 bytes object containing the formatted message. 146 147 .. versionadded:: 3.4 148 149 150 .. method:: is_multipart() 151 152 Return ``True`` if the message's payload is a list of sub-\ 153 :class:`Message` objects, otherwise return ``False``. When 154 :meth:`is_multipart` returns ``False``, the payload should be a string 155 object (which might be a CTE encoded binary payload. (Note that 156 :meth:`is_multipart` returning ``True`` does not necessarily mean that 157 "msg.get_content_maintype() == 'multipart'" will return the ``True``. 158 For example, ``is_multipart`` will return ``True`` when the 159 :class:`Message` is of type ``message/rfc822``.) 160 161 162 .. method:: set_unixfrom(unixfrom) 163 164 Set the message's envelope header to *unixfrom*, which should be a string. 165 166 167 .. method:: get_unixfrom() 168 169 Return the message's envelope header. Defaults to ``None`` if the 170 envelope header was never set. 171 172 173 .. method:: attach(payload) 174 175 Add the given *payload* to the current payload, which must be ``None`` or 176 a list of :class:`Message` objects before the call. After the call, the 177 payload will always be a list of :class:`Message` objects. If you want to 178 set the payload to a scalar object (e.g. a string), use 179 :meth:`set_payload` instead. 180 181 This is a legacy method. On the 182 :class:`~email.emailmessage.EmailMessage` class its functionality is 183 replaced by :meth:`~email.message.EmailMessage.set_content` and the 184 related ``make`` and ``add`` methods. 185 186 187 .. method:: get_payload(i=None, decode=False) 188 189 Return the current payload, which will be a list of 190 :class:`Message` objects when :meth:`is_multipart` is ``True``, or a 191 string when :meth:`is_multipart` is ``False``. If the payload is a list 192 and you mutate the list object, you modify the message's payload in place. 193 194 With optional argument *i*, :meth:`get_payload` will return the *i*-th 195 element of the payload, counting from zero, if :meth:`is_multipart` is 196 ``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or 197 greater than or equal to the number of items in the payload. If the 198 payload is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is 199 given, a :exc:`TypeError` is raised. 200 201 Optional *decode* is a flag indicating whether the payload should be 202 decoded or not, according to the :mailheader:`Content-Transfer-Encoding` 203 header. When ``True`` and the message is not a multipart, the payload will 204 be decoded if this header's value is ``quoted-printable`` or ``base64``. 205 If some other encoding is used, or :mailheader:`Content-Transfer-Encoding` 206 header is missing, the payload is 207 returned as-is (undecoded). In all cases the returned value is binary 208 data. If the message is a multipart and the *decode* flag is ``True``, 209 then ``None`` is returned. If the payload is base64 and it was not 210 perfectly formed (missing padding, characters outside the base64 211 alphabet), then an appropriate defect will be added to the message's 212 defect property (:class:`~email.errors.InvalidBase64PaddingDefect` or 213 :class:`~email.errors.InvalidBase64CharactersDefect`, respectively). 214 215 When *decode* is ``False`` (the default) the body is returned as a string 216 without decoding the :mailheader:`Content-Transfer-Encoding`. However, 217 for a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made 218 to decode the original bytes using the ``charset`` specified by the 219 :mailheader:`Content-Type` header, using the ``replace`` error handler. 220 If no ``charset`` is specified, or if the ``charset`` given is not 221 recognized by the email package, the body is decoded using the default 222 ASCII charset. 223 224 This is a legacy method. On the 225 :class:`~email.emailmessage.EmailMessage` class its functionality is 226 replaced by :meth:`~email.message.EmailMessage.get_content` and 227 :meth:`~email.message.EmailMessage.iter_parts`. 228 229 230 .. method:: set_payload(payload, charset=None) 231 232 Set the entire message object's payload to *payload*. It is the client's 233 responsibility to ensure the payload invariants. Optional *charset* sets 234 the message's default character set; see :meth:`set_charset` for details. 235 236 This is a legacy method. On the 237 :class:`~email.emailmessage.EmailMessage` class its functionality is 238 replaced by :meth:`~email.message.EmailMessage.set_content`. 239 240 241 .. method:: set_charset(charset) 242 243 Set the character set of the payload to *charset*, which can either be a 244 :class:`~email.charset.Charset` instance (see :mod:`email.charset`), a 245 string naming a character set, or ``None``. If it is a string, it will 246 be converted to a :class:`~email.charset.Charset` instance. If *charset* 247 is ``None``, the ``charset`` parameter will be removed from the 248 :mailheader:`Content-Type` header (the message will not be otherwise 249 modified). Anything else will generate a :exc:`TypeError`. 250 251 If there is no existing :mailheader:`MIME-Version` header one will be 252 added. If there is no existing :mailheader:`Content-Type` header, one 253 will be added with a value of :mimetype:`text/plain`. Whether the 254 :mailheader:`Content-Type` header already exists or not, its ``charset`` 255 parameter will be set to *charset.output_charset*. If 256 *charset.input_charset* and *charset.output_charset* differ, the payload 257 will be re-encoded to the *output_charset*. If there is no existing 258 :mailheader:`Content-Transfer-Encoding` header, then the payload will be 259 transfer-encoded, if needed, using the specified 260 :class:`~email.charset.Charset`, and a header with the appropriate value 261 will be added. If a :mailheader:`Content-Transfer-Encoding` header 262 already exists, the payload is assumed to already be correctly encoded 263 using that :mailheader:`Content-Transfer-Encoding` and is not modified. 264 265 This is a legacy method. On the 266 :class:`~email.emailmessage.EmailMessage` class its functionality is 267 replaced by the *charset* parameter of the 268 :meth:`email.emailmessage.EmailMessage.set_content` method. 269 270 271 .. method:: get_charset() 272 273 Return the :class:`~email.charset.Charset` instance associated with the 274 message's payload. 275 276 This is a legacy method. On the 277 :class:`~email.emailmessage.EmailMessage` class it always returns 278 ``None``. 279 280 281 The following methods implement a mapping-like interface for accessing the 282 message's :rfc:`2822` headers. Note that there are some semantic differences 283 between these methods and a normal mapping (i.e. dictionary) interface. For 284 example, in a dictionary there are no duplicate keys, but here there may be 285 duplicate message headers. Also, in dictionaries there is no guaranteed 286 order to the keys returned by :meth:`keys`, but in a :class:`Message` object, 287 headers are always returned in the order they appeared in the original 288 message, or were added to the message later. Any header deleted and then 289 re-added are always appended to the end of the header list. 290 291 These semantic differences are intentional and are biased toward maximal 292 convenience. 293 294 Note that in all cases, any envelope header present in the message is not 295 included in the mapping interface. 296 297 In a model generated from bytes, any header values that (in contravention of 298 the RFCs) contain non-ASCII bytes will, when retrieved through this 299 interface, be represented as :class:`~email.header.Header` objects with 300 a charset of `unknown-8bit`. 301 302 303 .. method:: __len__() 304 305 Return the total number of headers, including duplicates. 306 307 308 .. method:: __contains__(name) 309 310 Return true if the message object has a field named *name*. Matching is 311 done case-insensitively and *name* should not include the trailing colon. 312 Used for the ``in`` operator, e.g.:: 313 314 if 'message-id' in myMessage: 315 print('Message-ID:', myMessage['message-id']) 316 317 318 .. method:: __getitem__(name) 319 320 Return the value of the named header field. *name* should not include the 321 colon field separator. If the header is missing, ``None`` is returned; a 322 :exc:`KeyError` is never raised. 323 324 Note that if the named field appears more than once in the message's 325 headers, exactly which of those field values will be returned is 326 undefined. Use the :meth:`get_all` method to get the values of all the 327 extant named headers. 328 329 330 .. method:: __setitem__(name, val) 331 332 Add a header to the message with field name *name* and value *val*. The 333 field is appended to the end of the message's existing fields. 334 335 Note that this does *not* overwrite or delete any existing header with the same 336 name. If you want to ensure that the new header is the only one present in the 337 message with field name *name*, delete the field first, e.g.:: 338 339 del msg['subject'] 340 msg['subject'] = 'Python roolz!' 341 342 343 .. method:: __delitem__(name) 344 345 Delete all occurrences of the field with name *name* from the message's 346 headers. No exception is raised if the named field isn't present in the 347 headers. 348 349 350 .. method:: keys() 351 352 Return a list of all the message's header field names. 353 354 355 .. method:: values() 356 357 Return a list of all the message's field values. 358 359 360 .. method:: items() 361 362 Return a list of 2-tuples containing all the message's field headers and 363 values. 364 365 366 .. method:: get(name, failobj=None) 367 368 Return the value of the named header field. This is identical to 369 :meth:`__getitem__` except that optional *failobj* is returned if the 370 named header is missing (defaults to ``None``). 371 372 Here are some additional useful methods: 373 374 375 .. method:: get_all(name, failobj=None) 376 377 Return a list of all the values for the field named *name*. If there are 378 no such named headers in the message, *failobj* is returned (defaults to 379 ``None``). 380 381 382 .. method:: add_header(_name, _value, **_params) 383 384 Extended header setting. This method is similar to :meth:`__setitem__` 385 except that additional header parameters can be provided as keyword 386 arguments. *_name* is the header field to add and *_value* is the 387 *primary* value for the header. 388 389 For each item in the keyword argument dictionary *_params*, the key is 390 taken as the parameter name, with underscores converted to dashes (since 391 dashes are illegal in Python identifiers). Normally, the parameter will 392 be added as ``key="value"`` unless the value is ``None``, in which case 393 only the key will be added. If the value contains non-ASCII characters, 394 it can be specified as a three tuple in the format 395 ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the 396 charset to be used to encode the value, ``LANGUAGE`` can usually be set 397 to ``None`` or the empty string (see :rfc:`2231` for other possibilities), 398 and ``VALUE`` is the string value containing non-ASCII code points. If 399 a three tuple is not passed and the value contains non-ASCII characters, 400 it is automatically encoded in :rfc:`2231` format using a ``CHARSET`` 401 of ``utf-8`` and a ``LANGUAGE`` of ``None``. 402 403 Here's an example:: 404 405 msg.add_header('Content-Disposition', 'attachment', filename='bud.gif') 406 407 This will add a header that looks like :: 408 409 Content-Disposition: attachment; filename="bud.gif" 410 411 An example with non-ASCII characters:: 412 413 msg.add_header('Content-Disposition', 'attachment', 414 filename=('iso-8859-1', '', 'Fußballer.ppt')) 415 416 Which produces :: 417 418 Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt" 419 420 421 .. method:: replace_header(_name, _value) 422 423 Replace a header. Replace the first header found in the message that 424 matches *_name*, retaining header order and field name case. If no 425 matching header was found, a :exc:`KeyError` is raised. 426 427 428 .. method:: get_content_type() 429 430 Return the message's content type. The returned string is coerced to 431 lower case of the form :mimetype:`maintype/subtype`. If there was no 432 :mailheader:`Content-Type` header in the message the default type as given 433 by :meth:`get_default_type` will be returned. Since according to 434 :rfc:`2045`, messages always have a default type, :meth:`get_content_type` 435 will always return a value. 436 437 :rfc:`2045` defines a message's default type to be :mimetype:`text/plain` 438 unless it appears inside a :mimetype:`multipart/digest` container, in 439 which case it would be :mimetype:`message/rfc822`. If the 440 :mailheader:`Content-Type` header has an invalid type specification, 441 :rfc:`2045` mandates that the default type be :mimetype:`text/plain`. 442 443 444 .. method:: get_content_maintype() 445 446 Return the message's main content type. This is the :mimetype:`maintype` 447 part of the string returned by :meth:`get_content_type`. 448 449 450 .. method:: get_content_subtype() 451 452 Return the message's sub-content type. This is the :mimetype:`subtype` 453 part of the string returned by :meth:`get_content_type`. 454 455 456 .. method:: get_default_type() 457 458 Return the default content type. Most messages have a default content 459 type of :mimetype:`text/plain`, except for messages that are subparts of 460 :mimetype:`multipart/digest` containers. Such subparts have a default 461 content type of :mimetype:`message/rfc822`. 462 463 464 .. method:: set_default_type(ctype) 465 466 Set the default content type. *ctype* should either be 467 :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not 468 enforced. The default content type is not stored in the 469 :mailheader:`Content-Type` header. 470 471 472 .. method:: get_params(failobj=None, header='content-type', unquote=True) 473 474 Return the message's :mailheader:`Content-Type` parameters, as a list. 475 The elements of the returned list are 2-tuples of key/value pairs, as 476 split on the ``'='`` sign. The left hand side of the ``'='`` is the key, 477 while the right hand side is the value. If there is no ``'='`` sign in 478 the parameter the value is the empty string, otherwise the value is as 479 described in :meth:`get_param` and is unquoted if optional *unquote* is 480 ``True`` (the default). 481 482 Optional *failobj* is the object to return if there is no 483 :mailheader:`Content-Type` header. Optional *header* is the header to 484 search instead of :mailheader:`Content-Type`. 485 486 This is a legacy method. On the 487 :class:`~email.emailmessage.EmailMessage` class its functionality is 488 replaced by the *params* property of the individual header objects 489 returned by the header access methods. 490 491 492 .. method:: get_param(param, failobj=None, header='content-type', unquote=True) 493 494 Return the value of the :mailheader:`Content-Type` header's parameter 495 *param* as a string. If the message has no :mailheader:`Content-Type` 496 header or if there is no such parameter, then *failobj* is returned 497 (defaults to ``None``). 498 499 Optional *header* if given, specifies the message header to use instead of 500 :mailheader:`Content-Type`. 501 502 Parameter keys are always compared case insensitively. The return value 503 can either be a string, or a 3-tuple if the parameter was :rfc:`2231` 504 encoded. When it's a 3-tuple, the elements of the value are of the form 505 ``(CHARSET, LANGUAGE, VALUE)``. Note that both ``CHARSET`` and 506 ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE`` 507 to be encoded in the ``us-ascii`` charset. You can usually ignore 508 ``LANGUAGE``. 509 510 If your application doesn't care whether the parameter was encoded as in 511 :rfc:`2231`, you can collapse the parameter value by calling 512 :func:`email.utils.collapse_rfc2231_value`, passing in the return value 513 from :meth:`get_param`. This will return a suitably decoded Unicode 514 string when the value is a tuple, or the original string unquoted if it 515 isn't. For example:: 516 517 rawparam = msg.get_param('foo') 518 param = email.utils.collapse_rfc2231_value(rawparam) 519 520 In any case, the parameter value (either the returned string, or the 521 ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set 522 to ``False``. 523 524 This is a legacy method. On the 525 :class:`~email.emailmessage.EmailMessage` class its functionality is 526 replaced by the *params* property of the individual header objects 527 returned by the header access methods. 528 529 530 .. method:: set_param(param, value, header='Content-Type', requote=True, \ 531 charset=None, language='', replace=False) 532 533 Set a parameter in the :mailheader:`Content-Type` header. If the 534 parameter already exists in the header, its value will be replaced with 535 *value*. If the :mailheader:`Content-Type` header as not yet been defined 536 for this message, it will be set to :mimetype:`text/plain` and the new 537 parameter value will be appended as per :rfc:`2045`. 538 539 Optional *header* specifies an alternative header to 540 :mailheader:`Content-Type`, and all parameters will be quoted as necessary 541 unless optional *requote* is ``False`` (the default is ``True``). 542 543 If optional *charset* is specified, the parameter will be encoded 544 according to :rfc:`2231`. Optional *language* specifies the RFC 2231 545 language, defaulting to the empty string. Both *charset* and *language* 546 should be strings. 547 548 If *replace* is ``False`` (the default) the header is moved to the 549 end of the list of headers. If *replace* is ``True``, the header 550 will be updated in place. 551 552 .. versionchanged:: 3.4 ``replace`` keyword was added. 553 554 555 .. method:: del_param(param, header='content-type', requote=True) 556 557 Remove the given parameter completely from the :mailheader:`Content-Type` 558 header. The header will be re-written in place without the parameter or 559 its value. All values will be quoted as necessary unless *requote* is 560 ``False`` (the default is ``True``). Optional *header* specifies an 561 alternative to :mailheader:`Content-Type`. 562 563 564 .. method:: set_type(type, header='Content-Type', requote=True) 565 566 Set the main type and subtype for the :mailheader:`Content-Type` 567 header. *type* must be a string in the form :mimetype:`maintype/subtype`, 568 otherwise a :exc:`ValueError` is raised. 569 570 This method replaces the :mailheader:`Content-Type` header, keeping all 571 the parameters in place. If *requote* is ``False``, this leaves the 572 existing header's quoting as is, otherwise the parameters will be quoted 573 (the default). 574 575 An alternative header can be specified in the *header* argument. When the 576 :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` 577 header is also added. 578 579 This is a legacy method. On the 580 :class:`~email.emailmessage.EmailMessage` class its functionality is 581 replaced by the ``make_`` and ``add_`` methods. 582 583 584 .. method:: get_filename(failobj=None) 585 586 Return the value of the ``filename`` parameter of the 587 :mailheader:`Content-Disposition` header of the message. If the header 588 does not have a ``filename`` parameter, this method falls back to looking 589 for the ``name`` parameter on the :mailheader:`Content-Type` header. If 590 neither is found, or the header is missing, then *failobj* is returned. 591 The returned string will always be unquoted as per 592 :func:`email.utils.unquote`. 593 594 595 .. method:: get_boundary(failobj=None) 596 597 Return the value of the ``boundary`` parameter of the 598 :mailheader:`Content-Type` header of the message, or *failobj* if either 599 the header is missing, or has no ``boundary`` parameter. The returned 600 string will always be unquoted as per :func:`email.utils.unquote`. 601 602 603 .. method:: set_boundary(boundary) 604 605 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to 606 *boundary*. :meth:`set_boundary` will always quote *boundary* if 607 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the 608 message object has no :mailheader:`Content-Type` header. 609 610 Note that using this method is subtly different than deleting the old 611 :mailheader:`Content-Type` header and adding a new one with the new 612 boundary via :meth:`add_header`, because :meth:`set_boundary` preserves 613 the order of the :mailheader:`Content-Type` header in the list of 614 headers. However, it does *not* preserve any continuation lines which may 615 have been present in the original :mailheader:`Content-Type` header. 616 617 618 .. method:: get_content_charset(failobj=None) 619 620 Return the ``charset`` parameter of the :mailheader:`Content-Type` header, 621 coerced to lower case. If there is no :mailheader:`Content-Type` header, or if 622 that header has no ``charset`` parameter, *failobj* is returned. 623 624 Note that this method differs from :meth:`get_charset` which returns the 625 :class:`~email.charset.Charset` instance for the default encoding of the message body. 626 627 628 .. method:: get_charsets(failobj=None) 629 630 Return a list containing the character set names in the message. If the 631 message is a :mimetype:`multipart`, then the list will contain one element 632 for each subpart in the payload, otherwise, it will be a list of length 1. 633 634 Each item in the list will be a string which is the value of the 635 ``charset`` parameter in the :mailheader:`Content-Type` header for the 636 represented subpart. However, if the subpart has no 637 :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of 638 the :mimetype:`text` main MIME type, then that item in the returned list 639 will be *failobj*. 640 641 642 .. method:: get_content_disposition() 643 644 Return the lowercased value (without parameters) of the message's 645 :mailheader:`Content-Disposition` header if it has one, or ``None``. The 646 possible values for this method are *inline*, *attachment* or ``None`` 647 if the message follows :rfc:`2183`. 648 649 .. versionadded:: 3.5 650 651 .. method:: walk() 652 653 The :meth:`walk` method is an all-purpose generator which can be used to 654 iterate over all the parts and subparts of a message object tree, in 655 depth-first traversal order. You will typically use :meth:`walk` as the 656 iterator in a ``for`` loop; each iteration returns the next subpart. 657 658 Here's an example that prints the MIME type of every part of a multipart 659 message structure: 660 661 .. testsetup:: 662 663 >>> from email import message_from_binary_file 664 >>> with open('Lib/test/test_email/data/msg_16.txt', 'rb') as f: 665 ... msg = message_from_binary_file(f) 666 >>> from email.iterators import _structure 667 668 .. doctest:: 669 670 >>> for part in msg.walk(): 671 ... print(part.get_content_type()) 672 multipart/report 673 text/plain 674 message/delivery-status 675 text/plain 676 text/plain 677 message/rfc822 678 text/plain 679 680 ``walk`` iterates over the subparts of any part where 681 :meth:`is_multipart` returns ``True``, even though 682 ``msg.get_content_maintype() == 'multipart'`` may return ``False``. We 683 can see this in our example by making use of the ``_structure`` debug 684 helper function: 685 686 .. doctest:: 687 688 >>> for part in msg.walk(): 689 ... print(part.get_content_maintype() == 'multipart'), 690 ... part.is_multipart()) 691 True True 692 False False 693 False True 694 False False 695 False False 696 False True 697 False False 698 >>> _structure(msg) 699 multipart/report 700 text/plain 701 message/delivery-status 702 text/plain 703 text/plain 704 message/rfc822 705 text/plain 706 707 Here the ``message`` parts are not ``multiparts``, but they do contain 708 subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends 709 into the subparts. 710 711 712 :class:`Message` objects can also optionally contain two instance attributes, 713 which can be used when generating the plain text of a MIME message. 714 715 716 .. attribute:: preamble 717 718 The format of a MIME document allows for some text between the blank line 719 following the headers, and the first multipart boundary string. Normally, 720 this text is never visible in a MIME-aware mail reader because it falls 721 outside the standard MIME armor. However, when viewing the raw text of 722 the message, or when viewing the message in a non-MIME aware reader, this 723 text can become visible. 724 725 The *preamble* attribute contains this leading extra-armor text for MIME 726 documents. When the :class:`~email.parser.Parser` discovers some text 727 after the headers but before the first boundary string, it assigns this 728 text to the message's *preamble* attribute. When the 729 :class:`~email.generator.Generator` is writing out the plain text 730 representation of a MIME message, and it finds the 731 message has a *preamble* attribute, it will write this text in the area 732 between the headers and the first boundary. See :mod:`email.parser` and 733 :mod:`email.generator` for details. 734 735 Note that if the message object has no preamble, the *preamble* attribute 736 will be ``None``. 737 738 739 .. attribute:: epilogue 740 741 The *epilogue* attribute acts the same way as the *preamble* attribute, 742 except that it contains text that appears between the last boundary and 743 the end of the message. 744 745 You do not need to set the epilogue to the empty string in order for the 746 :class:`~email.generator.Generator` to print a newline at the end of the 747 file. 748 749 750 .. attribute:: defects 751 752 The *defects* attribute contains a list of all the problems found when 753 parsing this message. See :mod:`email.errors` for a detailed description 754 of the possible parsing defects. 755
