Lines Matching +full:is +full:- +full:plain +full:- +full:object
2 ---------------------------------------------------
12 --------------
16 The central class in the :mod:`email` package is the :class:`EmailMessage`
17 class, imported from the :mod:`email.message` module. It is the base class for
18 the :mod:`email` object model. :class:`EmailMessage` provides the core
22 An email message consists of *headers* and a *payload* (which is also referred
25 is not part of either the field name or the field value. The payload may be a
26 simple text message, or a binary object, or a structured sequence of
27 sub-messages each with their own set of headers and their own payload. The
28 latter type of payload is indicated by the message having a MIME type such as
31 The conceptual model provided by an :class:`EmailMessage` object is that of an
33 :rfc:`5322` body of the message, which might be a list of sub-``EmailMessage``
38 over the object tree.
40 The :class:`EmailMessage` dictionary-like interface is indexed by the header
42 with some extra methods. Headers are stored and returned in case-preserving
43 form, but field names are matched case-insensitively. Unlike a real dict,
44 there is an ordering to the keys, and there can be duplicate keys. Additional
47 The *payload* is either a string or bytes object, in the case of simple message
55 If *policy* is specified use the rules it specifies to update and serialize
56 the representation of the message. If *policy* is not set, use the
65 *unixfrom* is true, the envelope header is included in the returned
67 with the base :class:`~email.message.Message` class *maxheaderlen* is
69 length is controlled by the
80 Note that this method is provided as a convenience and may not be the
84 serializing messages. Note also that this method is restricted to
86 :attr:`~email.policy.EmailPolicy.utf8` is ``False``, which is the default.
89 is not specified was changed from defaulting to 0 to defaulting
100 thus producing an :rfc:`6531`-like message representation, instead of
106 Return the entire message flattened as a bytes object. When optional
107 *unixfrom* is true, the envelope header is included in the returned
118 Note that this method is provided as a convenience and may not be the
128 bytes object containing the serialized message.
133 Return ``True`` if the message's payload is a list of
134 sub-\ :class:`EmailMessage` objects, otherwise return ``False``. When
136 object (which might be a CTE encoded binary payload). Note that
140 :class:`EmailMessage` is of type ``message/rfc822``.
156 The following methods implement the mapping-like interface for accessing the
160 duplicate message headers. Also, in dictionaries there is no guaranteed
162 object, headers are always returned in the order they appeared in the
164 header deleted and then re-added is always appended to the end of the
170 Note that in all cases, any envelope header present in the message is not
181 Return ``True`` if the message object has a field named *name*. Matching is
185 if 'message-id' in myMessage:
186 print('Message-ID:', myMessage['message-id'])
192 colon field separator. If the header is missing, ``None`` is returned; a
193 :exc:`KeyError` is never raised.
196 headers, exactly which of those field values will be returned is
200 Using the standard (non-``compat32``) policies, the returned value is an
207 field is appended to the end of the message's existing headers.
210 name. If you want to ensure that the new header is the only one present in the
218 is made to assign a value to such a header when one already exists. This
219 behavior is intentional for consistency's sake, but do not depend on it
227 headers. No exception is raised if the named field isn't present in the
243 Return a list of 2-tuples containing all the message's field headers and
249 Return the value of the named header field. This is identical to
250 :meth:`__getitem__` except that optional *failobj* is returned if the
251 named header is missing (*failobj* defaults to ``None``).
260 no such named headers in the message, *failobj* is returned (defaults to
266 Extended header setting. This method is similar to :meth:`__setitem__`
268 arguments. *_name* is the header field to add and *_value* is the
271 For each item in the keyword argument dictionary *_params*, the key is
274 be added as ``key="value"`` unless the value is ``None``, in which case
277 If the value contains non-ASCII characters, the charset and language may
279 format ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string
282 possibilities), and ``VALUE`` is the string value containing non-ASCII
283 code points. If a three tuple is not passed and the value contains
284 non-ASCII characters, it is automatically encoded in :rfc:`2231` format
285 using a ``CHARSET`` of ``utf-8`` and a ``LANGUAGE`` of ``None``.
287 Here is an example::
289 msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
293 Content-Disposition: attachment; filename="bud.gif"
295 An example of the extended interface with non-ASCII characters::
297 msg.add_header('Content-Disposition', 'attachment',
298 filename=('iso-8859-1', '', 'Fußballer.ppt'))
305 original header. If no matching header is found, raise a
312 :mimetype:`maintype/subtype`. If there is no :mailheader:`Content-Type`
314 :meth:`get_default_type`. If the :mailheader:`Content-Type` header is
315 invalid, return ``text/plain``.
319 a message's default type to be :mimetype:`text/plain` unless it appears
321 be :mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header
323 type be :mimetype:`text/plain`.)
328 Return the message's main content type. This is the :mimetype:`maintype`
334 Return the message's sub-content type. This is the :mimetype:`subtype`
341 type of :mimetype:`text/plain`, except for messages that are subparts of
349 :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is
350 not enforced. The default content type is not stored in the
351 :mailheader:`Content-Type` header, so it only affects the return value of
352 the ``get_content_type`` methods when no :mailheader:`Content-Type`
353 header is present in the message.
356 .. method:: set_param(param, value, header='Content-Type', requote=True, \
359 Set a parameter in the :mailheader:`Content-Type` header. If the
361 When *header* is ``Content-Type`` (the default) and the header does not
363 :mimetype:`text/plain`, and append the new parameter value. Optional
364 *header* specifies an alternative header to :mailheader:`Content-Type`.
366 If the value contains non-ASCII characters, the charset and language may
370 strings. The default is to use the ``utf8`` *charset* and ``None`` for
373 If *replace* is ``False`` (the default) the header is moved to the
374 end of the list of headers. If *replace* is ``True``, the header
377 Use of the *requote* parameter with :class:`EmailMessage` objects is
382 header value (for example, ``msg['Content-Type'].params['charset']``).
387 .. method:: del_param(param, header='content-type', requote=True)
389 Remove the given parameter completely from the :mailheader:`Content-Type`
390 header. The header will be re-written in place without the parameter or
392 :mailheader:`Content-Type`.
394 Use of the *requote* parameter with :class:`EmailMessage` objects is
401 :mailheader:`Content-Disposition` header of the message. If the header
403 for the ``name`` parameter on the :mailheader:`Content-Type` header. If
404 neither is found, or the header is missing, then *failobj* is returned.
412 :mailheader:`Content-Type` header of the message, or *failobj* if either
413 the header is missing, or has no ``boundary`` parameter. The returned
419 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
421 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
422 message object has no :mailheader:`Content-Type` header.
424 Note that using this method is subtly different from deleting the old
425 :mailheader:`Content-Type` header and adding a new one with the new
427 the order of the :mailheader:`Content-Type` header in the list of
433 Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
434 coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
435 that header has no ``charset`` parameter, *failobj* is returned.
441 message is a :mimetype:`multipart`, then the list will contain one element
444 Each item in the list will be a string which is the value of the
445 ``charset`` parameter in the :mailheader:`Content-Type` header for the
446 represented subpart. If the subpart has no :mailheader:`Content-Type`
447 header, no ``charset`` parameter, or is not of the :mimetype:`text` main
453 Return ``True`` if there is a :mailheader:`Content-Disposition` header
454 and its (case insensitive) value is ``attachment``, ``False`` otherwise.
457 is_attachment is now a method instead of a property, for consistency
464 :mailheader:`Content-Disposition` header if it has one, or ``None``. The
477 The :meth:`walk` method is an all-purpose generator which can be used to
478 iterate over all the parts and subparts of a message object tree, in
479 depth-first traversal order. You will typically use :meth:`walk` as the
496 text/plain
497 message/delivery-status
498 text/plain
499 text/plain
501 text/plain
524 text/plain
525 message/delivery-status
526 text/plain
527 text/plain
529 text/plain
536 .. method:: get_body(preferencelist=('related', 'html', 'plain'))
538 Return the MIME part that is the best candidate to be the "body" of the
542 ``html``, and ``plain``, and indicates the order of preference for the
545 Start looking for candidate matches with the object on which the
546 ``get_body`` method is called.
548 If ``related`` is not included in *preferencelist*, consider the root
550 candidate if the (sub-)part matches a preference.
553 and if a part with a matching :mailheader:`Content-ID` is found, consider
557 If a part has a :mailheader:`Content-Disposition` header, only consider
558 the part a candidate match if the value of the header is ``inline``.
564 that really make sense are ``('plain',)``, ``('html', 'plain')``, and the
565 default ``('related', 'html', 'plain')``. (2) Because matching starts
566 with the object on which ``get_body`` is called, calling ``get_body`` on
567 a ``multipart/related`` will return the object itself unless
568 *preferencelist* has a non-default value. (3) Messages (or message parts)
569 that do not specify a :mailheader:`Content-Type` or whose
570 :mailheader:`Content-Type` header is invalid will be treated as if they
571 are of type ``text/plain``, which may occasionally cause ``get_body`` to
577 Return an iterator over all of the immediate sub-parts of the message
578 that are not candidate "body" parts. That is, skip the first occurrence
579 of each of ``text/plain``, ``text/html``, ``multipart/related``, or
581 attachments via :mailheader:`Content-Disposition: attachment`), and
585 or the first part if there is no ``start`` parameter or the ``start``
586 parameter doesn't match the :mailheader:`Content-ID` of any of the
588 non-``multipart``, return an empty iterator.
593 Return an iterator over all of the immediate sub-parts of the message,
594 which will be empty for a non-``multipart``. (See also
601 of the *content_manager*, passing self as the message object, and passing
603 *content_manager* is not specified, use the ``content_manager`` specified
610 of the *content_manager*, passing self as the message object, and passing
612 *content_manager* is not specified, use the ``content_manager`` specified
618 Convert a non-``multipart`` message into a ``multipart/related`` message,
619 moving any existing :mailheader:`Content-` headers and payload into a
620 (new) first part of the ``multipart``. If *boundary* is specified, use
622 to be automatically created when it is needed (for example, when the
623 message is serialized).
628 Convert a non-``multipart`` or a ``multipart/related`` into a
629 ``multipart/alternative``, moving any existing :mailheader:`Content-`
631 *boundary* is specified, use it as the boundary string in the multipart,
632 otherwise leave the boundary to be automatically created when it is
633 needed (for example, when the message is serialized).
638 Convert a non-``multipart``, a ``multipart/related``, or a
639 ``multipart-alternative`` into a ``multipart/mixed``, moving any existing
640 :mailheader:`Content-` headers and payload into a (new) first part of the
641 ``multipart``. If *boundary* is specified, use it as the boundary string
643 created when it is needed (for example, when the message is serialized).
648 If the message is a ``multipart/related``, create a new message
649 object, pass all of the arguments to its :meth:`set_content` method,
651 the message is a non-``multipart``, call :meth:`make_related` and then
652 proceed as above. If the message is any other type of ``multipart``,
653 raise a :exc:`TypeError`. If *content_manager* is not specified, use
655 If the added part has no :mailheader:`Content-Disposition` header,
661 If the message is a ``multipart/alternative``, create a new message
662 object, pass all of the arguments to its :meth:`set_content` method, and
664 message is a non-``multipart`` or ``multipart/related``, call
665 :meth:`make_alternative` and then proceed as above. If the message is
667 *content_manager* is not specified, use the ``content_manager`` specified
673 If the message is a ``multipart/mixed``, create a new message object,
676 message is a non-``multipart``, ``multipart/related``, or
678 above. If *content_manager* is not specified, use the ``content_manager``
680 has no :mailheader:`Content-Disposition` header, add one with the value
682 (:mailheader:`Content-Disposition: attachment`) and ``inline`` attachments
683 (:mailheader:`Content-Disposition: inline`), by passing appropriate
694 Remove the payload and all of the :exc:`Content-` headers, leaving
705 this text is never visible in a MIME-aware mail reader because it falls
707 the message, or when viewing the message in a non-MIME aware reader, this
710 The *preamble* attribute contains this leading extra-armor text for MIME
714 :class:`~email.generator.Generator` is writing out the plain text
720 Note that if the message object has no preamble, the *preamble* attribute
729 if there is no epilog text this attribute will be ``None``.
741 This class represents a subpart of a MIME message. It is identical to
742 :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
743 added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
744 not need their own :mailheader:`MIME-Version` headers.