Lines Matching refs:the
8 The central class in the :mod:`email` package is the :class:`Message` class,
9 imported from the :mod:`email.message` module. It is the base class for the
10 :mod:`email` object model. :class:`Message` provides the core functionality for
14 Headers are :rfc:`2822` style field names and values where the field name and
15 value are separated by a colon. The colon is not part of either the field name
16 or the field value.
20 the *Unix-From* header or the ``From_`` header. The payload is either a string
21 in the case of simple message objects or a list of :class:`Message` objects for
25 :class:`Message` objects provide a mapping style interface for accessing the
26 message headers, and an explicit interface for accessing both the headers and
27 the payload. It provides convenience methods for generating a flat text
28 representation of the message object tree, for accessing commonly used header
29 parameters, and for recursively walking over the object tree.
31 Here are the methods of the :class:`Message` class:
41 Return the entire message flattened as a string. When optional *unixfrom*
42 is ``True``, the envelope header is included in the returned string.
43 *unixfrom* defaults to ``False``. Flattening the message may trigger
44 changes to the :class:`Message` if defaults need to be filled in to
45 complete the transformation to a string (for example, MIME boundaries may
49 format the message the way you want. For example, by default it mangles
69 Return ``True`` if the message's payload is a list of sub-\
71 :meth:`is_multipart` returns ``False``, the payload should be a string object.
76 Set the message's envelope header to *unixfrom*, which should be a string.
81 Return the message's envelope header. Defaults to ``None`` if the
87 Add the given *payload* to the current payload, which must be ``None`` or
88 a list of :class:`Message` objects before the call. After the call, the
90 set the payload to a scalar object (e.g. a string), use
96 Return the current payload, which will be a list of
98 string when :meth:`is_multipart` is ``False``. If the payload is a list
99 and you mutate the list object, you modify the message's payload in place.
101 With optional argument *i*, :meth:`get_payload` will return the *i*-th
102 element of the payload, counting from zero, if :meth:`is_multipart` is
104 greater than or equal to the number of items in the payload. If the
108 Optional *decode* is a flag indicating whether the payload should be
109 decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
110 header. When ``True`` and the message is not a multipart, the payload will
113 header is missing, or if the payload has bogus base64 data, the payload is
114 returned as-is (undecoded). If the message is a multipart and the
121 Set the entire message object's payload to *payload*. It is the client's
122 responsibility to ensure the payload invariants. Optional *charset* sets
123 the message's default character set; see :meth:`set_charset` for details.
131 Set the character set of the payload to *charset*, which can either be a
135 is ``None``, the ``charset`` parameter will be removed from the
136 :mailheader:`Content-Type` header (the message will not be otherwise
141 will be added with a value of :mimetype:`text/plain`. Whether the
144 *charset.input_charset* and *charset.output_charset* differ, the payload
145 will be re-encoded to the *output_charset*. If there is no existing
146 :mailheader:`Content-Transfer-Encoding` header, then the payload will be
147 transfer-encoded, if needed, using the specified
148 :class:`~email.charset.Charset`, and a header with the appropriate value
150 already exists, the payload is assumed to already be correctly encoded
153 The message will be assumed to be of type :mimetype:`text/\*`, with the
156 and transfer encoded properly, if needed, when generating the plain text
157 representation of the message. MIME headers (:mailheader:`MIME-Version`,
166 Return the :class:`~email.charset.Charset` instance associated with the
171 The following methods implement a mapping-like interface for accessing the
176 order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
177 headers are always returned in the order they appeared in the original
178 message, or were added to the message later. Any header deleted and then
179 re-added are always appended to the end of the header list.
184 Note that in all cases, any envelope header present in the message is not
185 included in the mapping interface.
190 Return the total number of headers, including duplicates.
195 Return true if the message object has a field named *name*. Matching is
196 done case-insensitively and *name* should not include the trailing colon.
197 Used for the ``in`` operator, e.g.::
205 Return the value of the named header field. *name* should not include the
206 colon field separator. If the header is missing, ``None`` is returned; a
209 Note that if the named field appears more than once in the message's
211 undefined. Use the :meth:`get_all` method to get the values of all the
217 Add a header to the message with field name *name* and value *val*. The
218 field is appended to the end of the message's existing fields.
220 Note that this does *not* overwrite or delete any existing header with the same
221 name. If you want to ensure that the new header is the only one present in the
222 message with field name *name*, delete the field first, e.g.::
230 Delete all occurrences of the field with name *name* from the message's
231 headers. No exception is raised if the named field isn't present in the headers.
236 Return true if the message contains a header field named *name*, otherwise
242 Return a list of all the message's header field names.
247 Return a list of all the message's field values.
252 Return a list of 2-tuples containing all the message's field headers and
258 Return the value of the named header field. This is identical to
259 :meth:`__getitem__` except that optional *failobj* is returned if the
267 Return a list of all the values for the field named *name*. If there are
268 no such named headers in the message, *failobj* is returned (defaults to
276 arguments. *_name* is the header field to add and *_value* is the
277 *primary* value for the header.
279 For each item in the keyword argument dictionary *_params*, the key is
280 taken as the parameter name, with underscores converted to dashes (since
281 dashes are illegal in Python identifiers). Normally, the parameter will
282 be added as ``key="value"`` unless the value is ``None``, in which case
283 only the key will be added. If the value contains non-ASCII characters,
284 it must be specified as a three tuple in the format
285 ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
286 charset to be used to encode the value, ``LANGUAGE`` can usually be set
287 to ``None`` or the empty string (see :RFC:`2231` for other possibilities),
288 and ``VALUE`` is the string value containing non-ASCII code points.
310 Replace a header. Replace the first header found in the message that
319 Return the message's content type. The returned string is coerced to
320 lower case of the form :mimetype:`maintype/subtype`. If there was no
321 :mailheader:`Content-Type` header in the message the default type as given
328 which case it would be :mimetype:`message/rfc822`. If the
330 :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
337 Return the message's main content type. This is the :mimetype:`maintype`
338 part of the string returned by :meth:`get_content_type`.
345 Return the message's sub-content type. This is the :mimetype:`subtype`
346 part of the string returned by :meth:`get_content_type`.
353 Return the default content type. Most messages have a default content
363 Set the default content type. *ctype* should either be
365 enforced. The default content type is not stored in the
373 Return the message's :mailheader:`Content-Type` parameters, as a list.
374 The elements of the returned list are 2-tuples of key/value pairs, as
375 split on the ``'='`` sign. The left hand side of the ``'='`` is the key,
376 while the right hand side is the value. If there is no ``'='`` sign in
377 the parameter the value is the empty string, otherwise the value is as
379 ``True`` (the default).
381 Optional *failobj* is the object to return if there is no
382 :mailheader:`Content-Type` header. Optional *header* is the header to
391 Return the value of the :mailheader:`Content-Type` header's parameter
392 *param* as a string. If the message has no :mailheader:`Content-Type`
396 Optional *header* if given, specifies the message header to use instead of
400 can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
401 encoded. When it's a 3-tuple, the elements of the value are of the form
404 to be encoded in the ``us-ascii`` charset. You can usually ignore
407 If your application doesn't care whether the parameter was encoded as in
408 :rfc:`2231`, you can collapse the parameter value by calling
409 :func:`email.utils.collapse_rfc2231_value`, passing in the return value
411 string when the value is a tuple, or the original string unquoted if it
417 In any case, the parameter value (either the returned string, or the
418 ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
427 Set a parameter in the :mailheader:`Content-Type` header. If the
428 parameter already exists in the header, its value will be replaced with
429 *value*. If the :mailheader:`Content-Type` header as not yet been defined
430 for this message, it will be set to :mimetype:`text/plain` and the new
435 unless optional *requote* is ``False`` (the default is ``True``).
437 If optional *charset* is specified, the parameter will be encoded
438 according to :rfc:`2231`. Optional *language* specifies the RFC 2231
439 language, defaulting to the empty string. Both *charset* and *language*
447 Remove the given parameter completely from the :mailheader:`Content-Type`
448 header. The header will be re-written in place without the parameter or
450 ``False`` (the default is ``True``). Optional *header* specifies an
458 Set the main type and subtype for the :mailheader:`Content-Type`
459 header. *type* must be a string in the form :mimetype:`maintype/subtype`,
462 This method replaces the :mailheader:`Content-Type` header, keeping all
463 the parameters in place. If *requote* is ``False``, this leaves the
464 existing header's quoting as is, otherwise the parameters will be quoted
465 (the default).
467 An alternative header can be specified in the *header* argument. When the
476 Return the value of the ``filename`` parameter of the
477 :mailheader:`Content-Disposition` header of the message. If the header
479 for the ``name`` parameter on the :mailheader:`Content-Type` header. If
480 neither is found, or the header is missing, then *failobj* is returned.
487 Return the value of the ``boundary`` parameter of the
488 :mailheader:`Content-Type` header of the message, or *failobj* if either
489 the header is missing, or has no ``boundary`` parameter. The returned
495 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
497 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
500 Note that using this method is subtly different than deleting the old
501 :mailheader:`Content-Type` header and adding a new one with the new
503 the order of the :mailheader:`Content-Type` header in the list of
505 have been present in the original :mailheader:`Content-Type` header.
510 Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
514 Note that this method differs from :meth:`get_charset` which returns the
515 :class:`~email.charset.Charset` instance for the default encoding of the message body.
522 Return a list containing the character set names in the message. If the
523 message is a :mimetype:`multipart`, then the list will contain one element
524 for each subpart in the payload, otherwise, it will be a list of length 1.
526 Each item in the list will be a string which is the value of the
527 ``charset`` parameter in the :mailheader:`Content-Type` header for the
528 represented subpart. However, if the subpart has no
530 the :mimetype:`text` main MIME type, then that item in the returned list
537 iterate over all the parts and subparts of a message object tree, in
538 depth-first traversal order. You will typically use :meth:`walk` as the
539 iterator in a ``for`` loop; each iteration returns the next subpart.
541 Here's an example that prints the MIME type of every part of a multipart
558 which can be used when generating the plain text of a MIME message.
563 The format of a MIME document allows for some text between the blank line
564 following the headers, and the first multipart boundary string. Normally,
566 outside the standard MIME armor. However, when viewing the raw text of
567 the message, or when viewing the message in a non-MIME aware reader, this
571 documents. When the :class:`~email.parser.Parser` discovers some text
572 after the headers but before the first boundary string, it assigns this
573 text to the message's *preamble* attribute. When the
574 :class:`~email.generator.Generator` is writing out the plain text
575 representation of a MIME message, and it finds the
576 message has a *preamble* attribute, it will write this text in the area
577 between the headers and the first boundary. See :mod:`email.parser` and
580 Note that if the message object has no preamble, the *preamble* attribute
586 The *epilogue* attribute acts the same way as the *preamble* attribute,
587 except that it contains text that appears between the last boundary and
588 the end of the message.
591 You do not need to set the epilogue to the empty string in order for the
592 :class:`~email.generator.Generator` to print a newline at the end of the
598 The *defects* attribute contains a list of all the problems found when
600 of the possible parsing defects.