Lines Matching refs:the
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
23 to as the *content*). Headers are :rfc:`5322` or :rfc:`6532` style field names
24 and values, where the field name and value are separated by a colon. The colon
25 is not part of either the field name or the field value. The payload may be a
28 latter type of payload is indicated by the message having a MIME type such as
32 ordered dictionary of headers coupled with a *payload* that represents the
33 :rfc:`5322` body of the message, which might be a list of sub-``EmailMessage``
34 objects. In addition to the normal dictionary methods for accessing the header
36 the headers (for example the MIME content type), for operating on the payload,
37 for generating a serialized version of the message, and for recursively walking
38 over the object tree.
40 The :class:`EmailMessage` dictionary-like interface is indexed by the header
41 names, which must be ASCII values. The values of the dictionary are strings
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
57 :class:`~email.policy.default` policy, which follows the rules of the email
58 RFCs except for line endings (instead of the RFC mandated ``\r\n``, it uses
59 the Python standard ``\n`` line endings). For more information see the
64 Return the entire message flattened as a string. When optional
65 *unixfrom* is true, the envelope header is included in the returned
67 with the base :class:`~email.message.Message` class *maxheaderlen* is
68 accepted, but defaults to ``None``, which means that by default the line
69 length is controlled by the
70 :attr:`~email.policy.EmailPolicy.max_line_length` of the policy. The
71 *policy* argument may be used to override the default policy obtained
72 from the message instance. This can be used to control some of the
73 formatting produced by the method, since the specified *policy* will be
74 passed to the :class:`~email.generator.Generator`.
76 Flattening the message may trigger changes to the :class:`EmailMessage`
77 if defaults need to be filled in to complete the transformation to a
80 Note that this method is provided as a convenience and may not be the
86 :attr:`~email.policy.EmailPolicy.utf8` is ``False``, which is the default.
88 .. versionchanged:: 3.6 the default behavior when *maxheaderlen*
90 to the value of *max_line_length* from the policy.
96 ``str(msg)`` to produce a string containing the serialized message in a
99 .. versionchanged:: 3.4 the method was changed to use ``utf8=True``,
106 Return the entire message flattened as a bytes object. When optional
107 *unixfrom* is true, the envelope header is included in the returned
109 used to override the default policy obtained from the message instance.
110 This can be used to control some of the formatting produced by the
111 method, since the specified *policy* will be passed to the
114 Flattening the message may trigger changes to the :class:`EmailMessage`
115 if defaults need to be filled in to complete the transformation to a
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
135 :meth:`is_multipart` returns ``False``, the payload should be a string
138 "msg.get_content_maintype() == 'multipart'" will return the ``True``.
139 For example, ``is_multipart`` will return ``True`` when the
145 Set the message's envelope header to *unixfrom*, which should be a
152 Return the message's envelope header. Defaults to ``None`` if the
156 The following methods implement the mapping-like interface for accessing the
161 order to the keys returned by :meth:`keys`, but in an :class:`EmailMessage`
162 object, headers are always returned in the order they appeared in the
163 original message, or in which they were added to the message later. Any
164 header deleted and then re-added is always appended to the end of the
168 convenience in the most common use cases.
170 Note that in all cases, any envelope header present in the message is not
171 included in the mapping interface.
176 Return the total number of headers, including duplicates.
181 Return true if the message object has a field named *name*. Matching is
182 done without regard to case and *name* does not include the trailing
183 colon. Used for the ``in`` operator. For example::
191 Return the value of the named header field. *name* does not include the
192 colon field separator. If the header is missing, ``None`` is returned; a
195 Note that if the named field appears more than once in the message's
197 undefined. Use the :meth:`get_all` method to get the values of all the
200 Using the standard (non-``compat32``) policies, the returned value is an
206 Add a header to the message with field name *name* and value *val*. The
207 field is appended to the end of the message's existing headers.
209 Note that this does *not* overwrite or delete any existing header with the same
210 name. If you want to ensure that the new header is the only one present in the
211 message with field name *name*, delete the field first, e.g.::
216 If the :mod:`policy` defines certain headers to be unique (as the standard
220 as we may choose to make such assignments do an automatic deletion of the
221 existing header in the future.
226 Delete all occurrences of the field with name *name* from the message's
227 headers. No exception is raised if the named field isn't present in the
233 Return a list of all the message's header field names.
238 Return a list of all the message's field values.
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
259 Return a list of all the values for the field named *name*. If there are
260 no such named headers in the message, *failobj* is returned (defaults to
268 arguments. *_name* is the header field to add and *_value* is the
269 *primary* value for the header.
271 For each item in the keyword argument dictionary *_params*, the key is
272 taken as the parameter name, with underscores converted to dashes (since
273 dashes are illegal in Python identifiers). Normally, the parameter will
274 be added as ``key="value"`` unless the value is ``None``, in which case
275 only the key will be added.
277 If the value contains non-ASCII characters, the charset and language may
278 be explicitly controlled by specifying the value as a three tuple in the
280 naming the charset to be used to encode the value, ``LANGUAGE`` can
281 usually be set to ``None`` or the empty string (see :rfc:`2231` for other
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
295 An example of the extended interface with non-ASCII characters::
303 Replace a header. Replace the first header found in the message that
304 matches *_name*, retaining header order and field name case of the
311 Return the message's content type, coerced to lower case of the form
313 header in the message return the value returned by
314 :meth:`get_default_type`. If the :mailheader:`Content-Type` header is
321 be :mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header
322 has an invalid type specification, :rfc:`2045` mandates that the default
328 Return the message's main content type. This is the :mimetype:`maintype`
329 part of the string returned by :meth:`get_content_type`.
334 Return the message's sub-content type. This is the :mimetype:`subtype`
335 part of the string returned by :meth:`get_content_type`.
340 Return the default content type. Most messages have a default content
348 Set the default content type. *ctype* should either be
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.
359 Set a parameter in the :mailheader:`Content-Type` header. If the
360 parameter already exists in the header, replace its value with *value*.
361 When *header* is ``Content-Type`` (the default) and the header does not
362 yet exist in the message, add it, set its value to
363 :mimetype:`text/plain`, and append the new parameter value. Optional
366 If the value contains non-ASCII characters, the charset and language may
367 be explicitly specified using the optional *charset* and *language*
368 parameters. Optional *language* specifies the :rfc:`2231` language,
369 defaulting to the empty string. Both *charset* and *language* should be
370 strings. The default is to use the ``utf8`` *charset* and ``None`` for
371 the *language*.
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
381 the :attr:`~email.headerregistry.BaseHeader.params` attribute of the
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
394 Use of the *requote* parameter with :class:`EmailMessage` objects is
400 Return the value of the ``filename`` parameter of the
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.
411 Return the value of the ``boundary`` parameter of the
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
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,
440 Return a list containing the character set names in the message. If the
441 message is a :mimetype:`multipart`, then the list will contain one element
442 for each subpart in the payload, otherwise, it will be a list of length 1.
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
448 MIME type, then that item in the returned list will be *failobj*.
463 Return the lowercased value (without parameters) of the message's
466 if the message follows :rfc:`2183`.
471 The following methods relate to interrogating and manipulating the content
472 (payload) of the message.
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
480 iterator in a ``for`` loop; each iteration returns the next subpart.
482 Here's an example that prints the MIME type of every part of a multipart
504 ``walk`` iterates over the subparts of any part where
507 can see this in our example by making use of the ``_structure`` debug
531 Here the ``message`` parts are not ``multiparts``, but they do contain
533 into the subparts.
538 Return the MIME part that is the best candidate to be the "body" of the
541 *preferencelist* must be a sequence of strings from the set ``related``,
542 ``html``, and ``plain``, and indicates the order of preference for the
543 content type of the part returned.
545 Start looking for candidate matches with the object on which the
548 If ``related`` is not included in *preferencelist*, consider the root
549 part (or subpart of the root part) of any related encountered as a
550 candidate if the (sub-)part matches a preference.
552 When encountering a ``multipart/related``, check the ``start`` parameter
554 only it when looking for candidate matches. Otherwise consider only the
555 first (default root) part of the ``multipart/related``.
558 the part a candidate match if the value of the header is ``inline``.
560 If none of the candidates matches any of the preferences in
563 Notes: (1) For most applications the only *preferencelist* combinations
564 that really make sense are ``('plain',)``, ``('html', 'plain')``, and the
566 with the object on which ``get_body`` is called, calling ``get_body`` on
567 a ``multipart/related`` will return the object itself unless
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
583 ``multipart/related``, return an iterator over the all the related parts
584 except the root part (ie: the part pointed to by the ``start`` parameter,
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
593 Return an iterator over all of the immediate sub-parts of the message,
600 Call the :meth:`~email.contentmanager.ContentManager.get_content` method
601 of the *content_manager*, passing self as the message object, and passing
603 *content_manager* is not specified, use the ``content_manager`` specified
604 by the current :mod:`~email.policy`.
609 Call the :meth:`~email.contentmanager.ContentManager.set_content` method
610 of the *content_manager*, passing self as the message object, and passing
612 *content_manager* is not specified, use the ``content_manager`` specified
613 by the current :mod:`~email.policy`.
620 (new) first part of the ``multipart``. If *boundary* is specified, use
621 it as the boundary string in the multipart, otherwise leave the boundary
622 to be automatically created when it is needed (for example, when the
630 headers and payload into a (new) first part of the ``multipart``. If
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).
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
642 in the multipart, otherwise leave the boundary to be automatically
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,
650 and :meth:`~email.message.Message.attach` it to the ``multipart``. If
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``,
654 the ``content_manager`` specified by the current :mod:`~email.policy`.
655 If the added part has no :mailheader:`Content-Disposition` header,
656 add one with the value ``inline``.
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
663 :meth:`~email.message.Message.attach` it to the ``multipart``. If the
665 :meth:`make_alternative` and then proceed as above. If the message is
667 *content_manager* is not specified, use the ``content_manager`` specified
668 by the current :mod:`~email.policy`.
673 If the message is a ``multipart/mixed``, create a new message object,
674 pass all of the arguments to its :meth:`set_content` method, and
675 :meth:`~email.message.Message.attach` it to the ``multipart``. If the
678 above. If *content_manager* is not specified, use the ``content_manager``
679 specified by the current :mod:`~email.policy`. If the added part
680 has no :mailheader:`Content-Disposition` header, add one with the value
684 options to the ``content_manager``.
689 Remove the payload and all of the headers.
694 Remove the payload and all of the :exc:`Content-` headers, leaving
698 :class:`EmailMessage` objects have the following instance attributes:
703 The format of a MIME document allows for some text between the blank line
704 following the headers, and the first multipart boundary string. Normally,
706 outside the standard MIME armor. However, when viewing the raw text of
707 the message, or when viewing the message in a non-MIME aware reader, this
711 documents. When the :class:`~email.parser.Parser` discovers some text
712 after the headers but before the first boundary string, it assigns this
713 text to the message's *preamble* attribute. When the
714 :class:`~email.generator.Generator` is writing out the plain text
715 representation of a MIME message, and it finds the
716 message has a *preamble* attribute, it will write this text in the area
717 between the headers and the first boundary. See :mod:`email.parser` and
720 Note that if the message object has no preamble, the *preamble* attribute
726 The *epilogue* attribute acts the same way as the *preamble* attribute,
727 except that it contains text that appears between the last boundary and
728 the end of the message. As with the :attr:`~EmailMessage.preamble`,
734 The *defects* attribute contains a list of all the problems found when
736 of the possible parsing defects.