Lines Matching +full:is +full:- +full:plain +full:- +full:object
2 ---------------------------------------------------
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
13 Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
15 value are separated by a colon. The colon is not part of either the field name
18 Headers are stored and returned in case-preserving form but are matched
19 case-insensitively. There may also be a single envelope header, also known as
20 the *Unix-From* header or the ``From_`` header. The payload is either a string
28 representation of the message object tree, for accessing commonly used header
29 parameters, and for recursively walking over the object tree.
42 is ``True``, the envelope header is included in the returned string.
48 Note that this method is provided as a convenience and may not always
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.
90 set the payload to a scalar object (e.g. a string), use
97 :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
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
103 ``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or
105 payload is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is
106 given, a :exc:`TypeError` is raised.
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
111 be decoded if this header's value is ``quoted-printable`` or ``base64``.
112 If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
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
115 *decode* flag is ``True``, then ``None`` is returned. The default for
116 *decode* is ``False``.
121 Set the entire message object's payload to *payload*. It is the client's
133 string naming a character set, or ``None``. If it is a string, it will
135 is ``None``, the ``charset`` parameter will be removed from the
136 :mailheader:`Content-Type` header (the message will not be otherwise
139 If there is no existing :mailheader:`MIME-Version` header one will be
140 added. If there is no existing :mailheader:`Content-Type` header, one
141 will be added with a value of :mimetype:`text/plain`. Whether the
142 :mailheader:`Content-Type` header already exists or not, its ``charset``
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
149 will be added. If a :mailheader:`Content-Transfer-Encoding` header
150 already exists, the payload is assumed to already be correctly encoded
151 using that :mailheader:`Content-Transfer-Encoding` and is not modified.
156 and transfer encoded properly, if needed, when generating the plain text
157 representation of the message. MIME headers (:mailheader:`MIME-Version`,
158 :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will
171 The following methods implement a mapping-like interface for accessing the
175 duplicate message headers. Also, in dictionaries there is no guaranteed
176 order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
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
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.
199 if 'message-id' in myMessage:
200 print 'Message-ID:', myMessage['message-id']
206 colon field separator. If the header is missing, ``None`` is returned; a
207 :exc:`KeyError` is never raised.
210 headers, exactly which of those field values will be returned is
218 field is appended to the end of the message's existing fields.
221 name. If you want to ensure that the new header is the only one present in the
231 headers. No exception is raised if the named field isn't present in the headers.
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
260 named header is missing (defaults to ``None``).
268 no such named headers in the message, *failobj* is returned (defaults to
274 Extended header setting. This method is similar to :meth:`__setitem__`
276 arguments. *_name* is the header field to add and *_value* is the
279 For each item in the keyword argument dictionary *_params*, the key is
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,
285 ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
288 and ``VALUE`` is the string value containing non-ASCII code points.
292 msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
296 Content-Disposition: attachment; filename="bud.gif"
298 An example with non-ASCII characters::
300 msg.add_header('Content-Disposition', 'attachment',
301 filename=('iso-8859-1', '', 'Fußballer.ppt'))
305 Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
312 matching header was found, a :exc:`KeyError` is raised.
319 Return the message's content type. The returned string is coerced to
321 :mailheader:`Content-Type` header in the message the default type as given
326 :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
329 :mailheader:`Content-Type` header has an invalid type specification,
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`
345 Return the message's sub-content type. This is the :mimetype:`subtype`
354 type of :mimetype:`text/plain`, except for messages that are subparts of
364 :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
365 enforced. The default content type is not stored in the
366 :mailheader:`Content-Type` header.
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
378 described in :meth:`get_param` and is unquoted if optional *unquote* is
381 Optional *failobj* is the object to return if there is no
382 :mailheader:`Content-Type` header. Optional *header* is the header to
383 search instead of :mailheader:`Content-Type`.
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`
393 header or if there is no such parameter, then *failobj* is returned
397 :mailheader:`Content-Type`.
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
411 string when the value is a tuple, or the original string unquoted if it
418 ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
422 *unquote* argument added, and 3-tuple return value possible.
427 Set a parameter in the :mailheader:`Content-Type` header. If the
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
434 :mailheader:`Content-Type`, and all parameters will be quoted as necessary
435 unless optional *requote* is ``False`` (the default is ``True``).
437 If optional *charset* is specified, the parameter will be encoded
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
449 its value. All values will be quoted as necessary unless *requote* is
450 ``False`` (the default is ``True``). Optional *header* specifies an
451 alternative to :mailheader:`Content-Type`.
458 Set the main type and subtype for the :mailheader:`Content-Type`
460 otherwise a :exc:`ValueError` is raised.
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
468 :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
469 header is also added.
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.
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
498 message object has no :mailheader:`Content-Type` header.
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,
511 coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
512 that header has no ``charset`` parameter, *failobj* is returned.
523 message is a :mimetype:`multipart`, then the list will contain one element
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
529 :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
536 The :meth:`walk` method is an all-purpose generator which can be used to
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
547 text/plain
548 message/delivery-status
549 text/plain
550 text/plain
558 which can be used when generating the plain text of a MIME message.
565 this text is never visible in a MIME-aware mail reader because it falls
567 the message, or when viewing the message in a non-MIME aware reader, this
570 The *preamble* attribute contains this leading extra-armor text for MIME
574 :class:`~email.generator.Generator` is writing out the plain text
580 Note that if the message object has no preamble, the *preamble* attribute