Lines Matching +full:is +full:- +full:plain +full:- +full:object
4 ---------------------------------------------------------------------------------------------------…
12 The :class:`Message` class is very similar to the
19 The philosophy and structure of the two classes is otherwise the same.
27 separated by a colon. The colon is not part of either the field name or the
28 field value. The payload may be a simple text message, or a binary object, or
29 a structured sequence of sub-messages each with their own set of headers and
30 their own payload. The latter type of payload is indicated by the message
34 The conceptual model provided by a :class:`Message` object is that of an
38 over the object tree. Note that duplicate headers are supported but special
41 The :class:`Message` pseudo-dictionary is indexed by the header names, which
43 supposed to contain only ASCII characters; there is some special handling for
44 non-ASCII input, but it doesn't always produce the correct results. Headers
45 are stored and returned in case-preserving form, but field names are matched
46 case-insensitively. There may also be a single envelope header, also known as
47 the *Unix-From* header or the ``From_`` header. The *payload* is either a
57 If *policy* is specified (it must be an instance of a :mod:`~email.policy`
59 of the message. If *policy* is not set, use the :class:`compat32
70 is true, the envelope header is included in the returned string.
83 Note that this method is provided as a convenience and may not always
85 not do the mangling of lines that begin with ``From`` that is
97 If the message object contains binary data that is not encoded according
98 to RFC standards, the non-compliant data will be replaced by unicode
113 Return the entire message flattened as a bytes object. When optional
114 *unixfrom* is true, the envelope header is included in the returned
125 Note that this method is provided as a convenience and may not always
127 not do the mangling of lines that begin with ``From`` that is
146 bytes object containing the formatted message.
153 Return ``True`` if the message's payload is a list of
154 sub-\ :class:`Message` objects, otherwise return ``False``. When
156 object (which might be a CTE encoded binary payload). (Note that
160 :class:`Message` is of type ``message/rfc822``.)
179 set the payload to a scalar object (e.g. a string), use
182 This is a legacy method. On the
183 :class:`~email.emailmessage.EmailMessage` class its functionality is
191 :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
192 string when :meth:`is_multipart` is ``False``. If the payload is a list
193 and you mutate the list object, you modify the message's payload in place.
195 With optional argument *i*, :meth:`get_payload` will return the *i*-th
196 element of the payload, counting from zero, if :meth:`is_multipart` is
197 ``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or
199 payload is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is
200 given, a :exc:`TypeError` is raised.
202 Optional *decode* is a flag indicating whether the payload should be
203 decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
204 header. When ``True`` and the message is not a multipart, the payload will
205 be decoded if this header's value is ``quoted-printable`` or ``base64``.
206 If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
207 header is missing, the payload is
208 returned as-is (undecoded). In all cases the returned value is binary
209 data. If the message is a multipart and the *decode* flag is ``True``,
210 then ``None`` is returned. If the payload is base64 and it was not
216 When *decode* is ``False`` (the default) the body is returned as a string
217 without decoding the :mailheader:`Content-Transfer-Encoding`. However,
218 for a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made
220 :mailheader:`Content-Type` header, using the ``replace`` error handler.
221 If no ``charset`` is specified, or if the ``charset`` given is not
222 recognized by the email package, the body is decoded using the default
225 This is a legacy method. On the
226 :class:`~email.emailmessage.EmailMessage` class its functionality is
233 Set the entire message object's payload to *payload*. It is the client's
237 This is a legacy method. On the
238 :class:`~email.emailmessage.EmailMessage` class its functionality is
246 string naming a character set, or ``None``. If it is a string, it will
248 is ``None``, the ``charset`` parameter will be removed from the
249 :mailheader:`Content-Type` header (the message will not be otherwise
252 If there is no existing :mailheader:`MIME-Version` header one will be
253 added. If there is no existing :mailheader:`Content-Type` header, one
254 will be added with a value of :mimetype:`text/plain`. Whether the
255 :mailheader:`Content-Type` header already exists or not, its ``charset``
258 will be re-encoded to the *output_charset*. If there is no existing
259 :mailheader:`Content-Transfer-Encoding` header, then the payload will be
260 transfer-encoded, if needed, using the specified
262 will be added. If a :mailheader:`Content-Transfer-Encoding` header
263 already exists, the payload is assumed to already be correctly encoded
264 using that :mailheader:`Content-Transfer-Encoding` and is not modified.
266 This is a legacy method. On the
267 :class:`~email.emailmessage.EmailMessage` class its functionality is
277 This is a legacy method. On the
282 The following methods implement a mapping-like interface for accessing the
286 duplicate message headers. Also, in dictionaries there is no guaranteed
287 order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
290 re-added are always appended to the end of the header list.
295 Note that in all cases, any envelope header present in the message is not
299 the RFCs) contain non-ASCII bytes will, when retrieved through this
301 a charset of ``unknown-8bit``.
311 Return ``True`` if the message object has a field named *name*. Matching is
312 done case-insensitively and *name* should not include the trailing colon.
315 if 'message-id' in myMessage:
316 print('Message-ID:', myMessage['message-id'])
322 colon field separator. If the header is missing, ``None`` is returned; a
323 :exc:`KeyError` is never raised.
326 headers, exactly which of those field values will be returned is
334 field is appended to the end of the message's existing fields.
337 name. If you want to ensure that the new header is the only one present in the
347 headers. No exception is raised if the named field isn't present in the
363 Return a list of 2-tuples containing all the message's field headers and
369 Return the value of the named header field. This is identical to
370 :meth:`__getitem__` except that optional *failobj* is returned if the
371 named header is missing (defaults to ``None``).
379 no such named headers in the message, *failobj* is returned (defaults to
385 Extended header setting. This method is similar to :meth:`__setitem__`
387 arguments. *_name* is the header field to add and *_value* is the
390 For each item in the keyword argument dictionary *_params*, the key is
393 be added as ``key="value"`` unless the value is ``None``, in which case
394 only the key will be added. If the value contains non-ASCII characters,
396 ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
399 and ``VALUE`` is the string value containing non-ASCII code points. If
400 a three tuple is not passed and the value contains non-ASCII characters,
401 it is automatically encoded in :rfc:`2231` format using a ``CHARSET``
402 of ``utf-8`` and a ``LANGUAGE`` of ``None``.
406 msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
410 Content-Disposition: attachment; filename="bud.gif"
412 An example with non-ASCII characters::
414 msg.add_header('Content-Disposition', 'attachment',
415 filename=('iso-8859-1', '', 'Fußballer.ppt'))
419 Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
426 matching header was found, a :exc:`KeyError` is raised.
431 Return the message's content type. The returned string is coerced to
433 :mailheader:`Content-Type` header in the message the default type as given
438 :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
441 :mailheader:`Content-Type` header has an invalid type specification,
442 :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
447 Return the message's main content type. This is the :mimetype:`maintype`
453 Return the message's sub-content type. This is the :mimetype:`subtype`
460 type of :mimetype:`text/plain`, except for messages that are subparts of
468 :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
469 enforced. The default content type is not stored in the
470 :mailheader:`Content-Type` header.
473 .. method:: get_params(failobj=None, header='content-type', unquote=True)
475 Return the message's :mailheader:`Content-Type` parameters, as a list.
476 The elements of the returned list are 2-tuples of key/value pairs, as
477 split on the ``'='`` sign. The left hand side of the ``'='`` is the key,
478 while the right hand side is the value. If there is no ``'='`` sign in
479 the parameter the value is the empty string, otherwise the value is as
480 described in :meth:`get_param` and is unquoted if optional *unquote* is
483 Optional *failobj* is the object to return if there is no
484 :mailheader:`Content-Type` header. Optional *header* is the header to
485 search instead of :mailheader:`Content-Type`.
487 This is a legacy method. On the
488 :class:`~email.emailmessage.EmailMessage` class its functionality is
493 .. method:: get_param(param, failobj=None, header='content-type', unquote=True)
495 Return the value of the :mailheader:`Content-Type` header's parameter
496 *param* as a string. If the message has no :mailheader:`Content-Type`
497 header or if there is no such parameter, then *failobj* is returned
501 :mailheader:`Content-Type`.
504 can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
505 encoded. When it's a 3-tuple, the elements of the value are of the form
508 to be encoded in the ``us-ascii`` charset. You can usually ignore
515 string when the value is a tuple, or the original string unquoted if it
522 ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
525 This is a legacy method. On the
526 :class:`~email.emailmessage.EmailMessage` class its functionality is
531 .. method:: set_param(param, value, header='Content-Type', requote=True, \
534 Set a parameter in the :mailheader:`Content-Type` header. If the
536 *value*. If the :mailheader:`Content-Type` header as not yet been defined
537 for this message, it will be set to :mimetype:`text/plain` and the new
541 :mailheader:`Content-Type`, and all parameters will be quoted as necessary
542 unless optional *requote* is ``False`` (the default is ``True``).
544 If optional *charset* is specified, the parameter will be encoded
549 If *replace* is ``False`` (the default) the header is moved to the
550 end of the list of headers. If *replace* is ``True``, the header
556 .. method:: del_param(param, header='content-type', requote=True)
558 Remove the given parameter completely from the :mailheader:`Content-Type`
559 header. The header will be re-written in place without the parameter or
560 its value. All values will be quoted as necessary unless *requote* is
561 ``False`` (the default is ``True``). Optional *header* specifies an
562 alternative to :mailheader:`Content-Type`.
565 .. method:: set_type(type, header='Content-Type', requote=True)
567 Set the main type and subtype for the :mailheader:`Content-Type`
569 otherwise a :exc:`ValueError` is raised.
571 This method replaces the :mailheader:`Content-Type` header, keeping all
572 the parameters in place. If *requote* is ``False``, this leaves the
573 existing header's quoting as is, otherwise the parameters will be quoted
577 :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
578 header is also added.
580 This is a legacy method. On the
581 :class:`~email.emailmessage.EmailMessage` class its functionality is
588 :mailheader:`Content-Disposition` header of the message. If the header
590 for the ``name`` parameter on the :mailheader:`Content-Type` header. If
591 neither is found, or the header is missing, then *failobj* is returned.
599 :mailheader:`Content-Type` header of the message, or *failobj* if either
600 the header is missing, or has no ``boundary`` parameter. The returned
606 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
608 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
609 message object has no :mailheader:`Content-Type` header.
611 Note that using this method is subtly different than deleting the old
612 :mailheader:`Content-Type` header and adding a new one with the new
614 the order of the :mailheader:`Content-Type` header in the list of
616 have been present in the original :mailheader:`Content-Type` header.
621 Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
622 coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
623 that header has no ``charset`` parameter, *failobj* is returned.
632 message is a :mimetype:`multipart`, then the list will contain one element
635 Each item in the list will be a string which is the value of the
636 ``charset`` parameter in the :mailheader:`Content-Type` header for the
638 :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
646 :mailheader:`Content-Disposition` header if it has one, or ``None``. The
654 The :meth:`walk` method is an all-purpose generator which can be used to
655 iterate over all the parts and subparts of a message object tree, in
656 depth-first traversal order. You will typically use :meth:`walk` as the
678 text/plain
679 message/delivery-status
680 text/plain
681 text/plain
683 text/plain
705 text/plain
706 message/delivery-status
707 text/plain
708 text/plain
710 text/plain
718 which can be used when generating the plain text of a MIME message.
725 this text is never visible in a MIME-aware mail reader because it falls
727 the message, or when viewing the message in a non-MIME aware reader, this
730 The *preamble* attribute contains this leading extra-armor text for MIME
734 :class:`~email.generator.Generator` is writing out the plain text
740 Note that if the message object has no preamble, the *preamble* attribute