Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`email`: Representing an email message |
| 2 | ------------------------------------------- |
| 3 | |
| 4 | .. module:: email.message |
| 5 | :synopsis: The base class representing email messages. |
| 6 | |
| 7 | |
| 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 |
| 11 | setting and querying header fields, and for accessing message bodies. |
| 12 | |
| 13 | Conceptually, a :class:`Message` object consists of *headers* and *payloads*. |
| 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. |
| 17 | |
| 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 |
| 21 | in the case of simple message objects or a list of :class:`Message` objects for |
| 22 | MIME container documents (e.g. :mimetype:`multipart/\*` and |
| 23 | :mimetype:`message/rfc822`). |
| 24 | |
| 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. |
| 30 | |
| 31 | Here are the methods of the :class:`Message` class: |
| 32 | |
| 33 | |
| 34 | .. class:: Message() |
| 35 | |
| 36 | The constructor takes no arguments. |
| 37 | |
| 38 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 39 | .. method:: as_string(unixfrom=False, maxheaderlen=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 41 | Return the entire message flattened as a string. When optional *unixfrom* |
| 42 | is ``True``, the envelope header is included in the returned string. |
R. David Murray | 101f278 | 2010-01-10 19:18:27 +0000 | [diff] [blame] | 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 |
| 46 | be generated or modified). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 48 | Note that this method is provided as a convenience and may not always |
R David Murray | 7dedcb4 | 2011-03-15 14:01:18 -0400 | [diff] [blame] | 49 | format the message the way you want. For example, by default it does |
| 50 | not do the mangling of lines that begin with ``From`` that is |
| 51 | required by the unix mbox format. For more flexibility, instantiate a |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 52 | :class:`~email.generator.Generator` instance and use its :meth:`flatten` |
| 53 | method directly. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
Georg Brandl | 0312494 | 2008-06-10 15:50:56 +0000 | [diff] [blame] | 55 | from io import StringIO |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 56 | from email.generator import Generator |
| 57 | fp = StringIO() |
R David Murray | 7dedcb4 | 2011-03-15 14:01:18 -0400 | [diff] [blame] | 58 | g = Generator(fp, mangle_from_=True, maxheaderlen=60) |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 59 | g.flatten(msg) |
| 60 | text = fp.getvalue() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
| 62 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 63 | .. method:: __str__() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 65 | Equivalent to ``as_string(unixfrom=True)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 66 | |
| 67 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 68 | .. method:: is_multipart() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 70 | Return ``True`` if the message's payload is a list of sub-\ |
| 71 | :class:`Message` objects, otherwise return ``False``. When |
| 72 | :meth:`is_multipart` returns False, the payload should be a string object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
| 74 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 75 | .. method:: set_unixfrom(unixfrom) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 77 | Set the message's envelope header to *unixfrom*, which should be a string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 80 | .. method:: get_unixfrom() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 82 | Return the message's envelope header. Defaults to ``None`` if the |
| 83 | envelope header was never set. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 86 | .. method:: attach(payload) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 88 | Add the given *payload* to the current payload, which must be ``None`` or |
| 89 | a list of :class:`Message` objects before the call. After the call, the |
| 90 | payload will always be a list of :class:`Message` objects. If you want to |
| 91 | set the payload to a scalar object (e.g. a string), use |
| 92 | :meth:`set_payload` instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | |
| 94 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 95 | .. method:: get_payload(i=None, decode=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 97 | Return the current payload, which will be a list of |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 98 | :class:`Message` objects when :meth:`is_multipart` is ``True``, or a |
| 99 | string when :meth:`is_multipart` is ``False``. If the payload is a list |
| 100 | and you mutate the list object, you modify the message's payload in place. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 102 | With optional argument *i*, :meth:`get_payload` will return the *i*-th |
| 103 | element of the payload, counting from zero, if :meth:`is_multipart` is |
| 104 | ``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or |
| 105 | greater than or equal to the number of items in the payload. If the |
| 106 | payload is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is |
| 107 | given, a :exc:`TypeError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 109 | Optional *decode* is a flag indicating whether the payload should be |
| 110 | decoded or not, according to the :mailheader:`Content-Transfer-Encoding` |
| 111 | header. When ``True`` and the message is not a multipart, the payload will |
| 112 | be decoded if this header's value is ``quoted-printable`` or ``base64``. |
| 113 | If some other encoding is used, or :mailheader:`Content-Transfer-Encoding` |
| 114 | header is missing, or if the payload has bogus base64 data, the payload is |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 115 | returned as-is (undecoded). In all cases the returned value is binary |
| 116 | data. If the message is a multipart and the *decode* flag is ``True``, |
| 117 | then ``None`` is returned. |
| 118 | |
| 119 | When *decode* is ``False`` (the default) the body is returned as a string |
| 120 | without decoding the :mailheader:`Content-Transfer-Encoding`. However, |
| 121 | for a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made |
Senthil Kumaran | 8227045 | 2010-10-15 13:29:33 +0000 | [diff] [blame] | 122 | to decode the original bytes using the ``charset`` specified by the |
| 123 | :mailheader:`Content-Type` header, using the ``replace`` error handler. |
| 124 | If no ``charset`` is specified, or if the ``charset`` given is not |
| 125 | recognized by the email package, the body is decoded using the default |
| 126 | ASCII charset. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 129 | .. method:: set_payload(payload, charset=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 131 | Set the entire message object's payload to *payload*. It is the client's |
| 132 | responsibility to ensure the payload invariants. Optional *charset* sets |
| 133 | the message's default character set; see :meth:`set_charset` for details. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 134 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 135 | .. method:: set_charset(charset) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 137 | Set the character set of the payload to *charset*, which can either be a |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 138 | :class:`~email.charset.Charset` instance (see :mod:`email.charset`), a |
| 139 | string naming a character set, or ``None``. If it is a string, it will |
| 140 | be converted to a :class:`~email.charset.Charset` instance. If *charset* |
| 141 | is ``None``, the ``charset`` parameter will be removed from the |
R David Murray | e3d09ff | 2011-03-15 17:41:13 -0400 | [diff] [blame] | 142 | :mailheader:`Content-Type` header (the message will not be otherwise |
| 143 | modified). Anything else will generate a :exc:`TypeError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
R David Murray | e3d09ff | 2011-03-15 17:41:13 -0400 | [diff] [blame] | 145 | If there is no existing :mailheader:`MIME-Version` header one will be |
| 146 | added. If there is no existing :mailheader:`Content-Type` header, one |
| 147 | will be added with a value of :mimetype:`text/plain`. Whether the |
| 148 | :mailheader:`Content-Type` header already exists or not, its ``charset`` |
| 149 | parameter will be set to *charset.output_charset*. If |
| 150 | *charset.input_charset* and *charset.output_charset* differ, the payload |
| 151 | will be re-encoded to the *output_charset*. If there is no existing |
| 152 | :mailheader:`Content-Transfer-Encoding` header, then the payload will be |
| 153 | transfer-encoded, if needed, using the specified |
| 154 | :class:`~email.charset.Charset`, and a header with the appropriate value |
| 155 | will be added. If a :mailheader:`Content-Transfer-Encoding` header |
| 156 | already exists, the payload is assumed to already be correctly encoded |
| 157 | using that :mailheader:`Content-Transfer-Encoding` and is not modified. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 159 | .. method:: get_charset() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 161 | Return the :class:`~email.charset.Charset` instance associated with the |
| 162 | message's payload. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 163 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 164 | The following methods implement a mapping-like interface for accessing the |
| 165 | message's :rfc:`2822` headers. Note that there are some semantic differences |
| 166 | between these methods and a normal mapping (i.e. dictionary) interface. For |
| 167 | example, in a dictionary there are no duplicate keys, but here there may be |
| 168 | duplicate message headers. Also, in dictionaries there is no guaranteed |
| 169 | order to the keys returned by :meth:`keys`, but in a :class:`Message` object, |
| 170 | headers are always returned in the order they appeared in the original |
| 171 | message, or were added to the message later. Any header deleted and then |
| 172 | re-added are always appended to the end of the header list. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 174 | These semantic differences are intentional and are biased toward maximal |
| 175 | convenience. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 176 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 177 | Note that in all cases, any envelope header present in the message is not |
| 178 | included in the mapping interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 179 | |
R. David Murray | 9253214 | 2011-01-07 23:25:30 +0000 | [diff] [blame] | 180 | In a model generated from bytes, any header values that (in contravention of |
| 181 | the RFCs) contain non-ASCII bytes will, when retrieved through this |
| 182 | interface, be represented as :class:`~email.header.Header` objects with |
| 183 | a charset of `unknown-8bit`. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 184 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 185 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 186 | .. method:: __len__() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 188 | Return the total number of headers, including duplicates. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | |
| 190 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 191 | .. method:: __contains__(name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 192 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 193 | Return true if the message object has a field named *name*. Matching is |
| 194 | done case-insensitively and *name* should not include the trailing colon. |
| 195 | Used for the ``in`` operator, e.g.:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 196 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 197 | if 'message-id' in myMessage: |
| 198 | print('Message-ID:', myMessage['message-id']) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 199 | |
| 200 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 201 | .. method:: __getitem__(name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 202 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 203 | Return the value of the named header field. *name* should not include the |
| 204 | colon field separator. If the header is missing, ``None`` is returned; a |
| 205 | :exc:`KeyError` is never raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 206 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 207 | Note that if the named field appears more than once in the message's |
| 208 | headers, exactly which of those field values will be returned is |
| 209 | undefined. Use the :meth:`get_all` method to get the values of all the |
| 210 | extant named headers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 211 | |
| 212 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 213 | .. method:: __setitem__(name, val) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 214 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 215 | Add a header to the message with field name *name* and value *val*. The |
| 216 | field is appended to the end of the message's existing fields. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 217 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 218 | Note that this does *not* overwrite or delete any existing header with the same |
| 219 | name. If you want to ensure that the new header is the only one present in the |
| 220 | message with field name *name*, delete the field first, e.g.:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 221 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 222 | del msg['subject'] |
| 223 | msg['subject'] = 'Python roolz!' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 224 | |
| 225 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 226 | .. method:: __delitem__(name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 227 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 228 | Delete all occurrences of the field with name *name* from the message's |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 229 | headers. No exception is raised if the named field isn't present in the |
| 230 | headers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 231 | |
| 232 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 233 | .. method:: keys() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 235 | Return a list of all the message's header field names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 236 | |
| 237 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 238 | .. method:: values() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 239 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 240 | Return a list of all the message's field values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 241 | |
| 242 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 243 | .. method:: items() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 244 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 245 | Return a list of 2-tuples containing all the message's field headers and |
| 246 | values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
| 248 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 249 | .. method:: get(name, failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 250 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 251 | Return the value of the named header field. This is identical to |
| 252 | :meth:`__getitem__` except that optional *failobj* is returned if the |
| 253 | named header is missing (defaults to ``None``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 254 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 255 | Here are some additional useful methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 256 | |
| 257 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 258 | .. method:: get_all(name, failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 259 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 260 | Return a list of all the values for the field named *name*. If there are |
| 261 | no such named headers in the message, *failobj* is returned (defaults to |
| 262 | ``None``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | |
| 264 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 265 | .. method:: add_header(_name, _value, **_params) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 266 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 267 | Extended header setting. This method is similar to :meth:`__setitem__` |
| 268 | except that additional header parameters can be provided as keyword |
| 269 | arguments. *_name* is the header field to add and *_value* is the |
| 270 | *primary* value for the header. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 271 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 272 | For each item in the keyword argument dictionary *_params*, the key is |
| 273 | taken as the parameter name, with underscores converted to dashes (since |
| 274 | dashes are illegal in Python identifiers). Normally, the parameter will |
| 275 | be added as ``key="value"`` unless the value is ``None``, in which case |
R. David Murray | 7ec754b | 2010-12-13 23:51:19 +0000 | [diff] [blame] | 276 | only the key will be added. If the value contains non-ASCII characters, |
| 277 | it can be specified as a three tuple in the format |
| 278 | ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the |
| 279 | charset to be used to encode the value, ``LANGUAGE`` can usually be set |
Georg Brandl | c884350 | 2010-12-19 10:28:46 +0000 | [diff] [blame] | 280 | to ``None`` or the empty string (see :rfc:`2231` for other possibilities), |
R. David Murray | 7ec754b | 2010-12-13 23:51:19 +0000 | [diff] [blame] | 281 | and ``VALUE`` is the string value containing non-ASCII code points. If |
| 282 | a three tuple is not passed and the value contains non-ASCII characters, |
Georg Brandl | c884350 | 2010-12-19 10:28:46 +0000 | [diff] [blame] | 283 | it is automatically encoded in :rfc:`2231` format using a ``CHARSET`` |
R. David Murray | 7ec754b | 2010-12-13 23:51:19 +0000 | [diff] [blame] | 284 | of ``utf-8`` and a ``LANGUAGE`` of ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 286 | Here's an example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 287 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 288 | msg.add_header('Content-Disposition', 'attachment', filename='bud.gif') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 289 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 290 | This will add a header that looks like :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 291 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 292 | Content-Disposition: attachment; filename="bud.gif" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
Ezio Melotti | e130a52 | 2011-10-19 10:58:56 +0300 | [diff] [blame] | 294 | An example with non-ASCII characters:: |
R. David Murray | 7ec754b | 2010-12-13 23:51:19 +0000 | [diff] [blame] | 295 | |
| 296 | msg.add_header('Content-Disposition', 'attachment', |
| 297 | filename=('iso-8859-1', '', 'Fußballer.ppt')) |
| 298 | |
| 299 | Which produces :: |
| 300 | |
| 301 | Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt" |
| 302 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 303 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 304 | .. method:: replace_header(_name, _value) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 305 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 306 | Replace a header. Replace the first header found in the message that |
| 307 | matches *_name*, retaining header order and field name case. If no |
| 308 | matching header was found, a :exc:`KeyError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 309 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 310 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 311 | .. method:: get_content_type() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 312 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 313 | Return the message's content type. The returned string is coerced to |
| 314 | lower case of the form :mimetype:`maintype/subtype`. If there was no |
| 315 | :mailheader:`Content-Type` header in the message the default type as given |
| 316 | by :meth:`get_default_type` will be returned. Since according to |
| 317 | :rfc:`2045`, messages always have a default type, :meth:`get_content_type` |
| 318 | will always return a value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 319 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 320 | :rfc:`2045` defines a message's default type to be :mimetype:`text/plain` |
| 321 | unless it appears inside a :mimetype:`multipart/digest` container, in |
| 322 | which case it would be :mimetype:`message/rfc822`. If the |
| 323 | :mailheader:`Content-Type` header has an invalid type specification, |
| 324 | :rfc:`2045` mandates that the default type be :mimetype:`text/plain`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 326 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 327 | .. method:: get_content_maintype() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 328 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 329 | Return the message's main content type. This is the :mimetype:`maintype` |
| 330 | part of the string returned by :meth:`get_content_type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 331 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 332 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 333 | .. method:: get_content_subtype() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 334 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 335 | Return the message's sub-content type. This is the :mimetype:`subtype` |
| 336 | part of the string returned by :meth:`get_content_type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 337 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 338 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 339 | .. method:: get_default_type() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 340 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 341 | Return the default content type. Most messages have a default content |
| 342 | type of :mimetype:`text/plain`, except for messages that are subparts of |
| 343 | :mimetype:`multipart/digest` containers. Such subparts have a default |
| 344 | content type of :mimetype:`message/rfc822`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 345 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 346 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 347 | .. method:: set_default_type(ctype) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 348 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 349 | Set the default content type. *ctype* should either be |
| 350 | :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not |
| 351 | enforced. The default content type is not stored in the |
| 352 | :mailheader:`Content-Type` header. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 353 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 354 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 355 | .. method:: get_params(failobj=None, header='content-type', unquote=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 356 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 357 | Return the message's :mailheader:`Content-Type` parameters, as a list. |
| 358 | The elements of the returned list are 2-tuples of key/value pairs, as |
| 359 | split on the ``'='`` sign. The left hand side of the ``'='`` is the key, |
| 360 | while the right hand side is the value. If there is no ``'='`` sign in |
| 361 | the parameter the value is the empty string, otherwise the value is as |
| 362 | described in :meth:`get_param` and is unquoted if optional *unquote* is |
| 363 | ``True`` (the default). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 365 | Optional *failobj* is the object to return if there is no |
| 366 | :mailheader:`Content-Type` header. Optional *header* is the header to |
| 367 | search instead of :mailheader:`Content-Type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 368 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 369 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 370 | .. method:: get_param(param, failobj=None, header='content-type', unquote=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 371 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 372 | Return the value of the :mailheader:`Content-Type` header's parameter |
| 373 | *param* as a string. If the message has no :mailheader:`Content-Type` |
| 374 | header or if there is no such parameter, then *failobj* is returned |
| 375 | (defaults to ``None``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 376 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 377 | Optional *header* if given, specifies the message header to use instead of |
| 378 | :mailheader:`Content-Type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 379 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 380 | Parameter keys are always compared case insensitively. The return value |
| 381 | can either be a string, or a 3-tuple if the parameter was :rfc:`2231` |
| 382 | encoded. When it's a 3-tuple, the elements of the value are of the form |
| 383 | ``(CHARSET, LANGUAGE, VALUE)``. Note that both ``CHARSET`` and |
| 384 | ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE`` |
| 385 | to be encoded in the ``us-ascii`` charset. You can usually ignore |
| 386 | ``LANGUAGE``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 387 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 388 | If your application doesn't care whether the parameter was encoded as in |
| 389 | :rfc:`2231`, you can collapse the parameter value by calling |
Georg Brandl | 540b45c | 2009-04-27 16:45:26 +0000 | [diff] [blame] | 390 | :func:`email.utils.collapse_rfc2231_value`, passing in the return value |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 391 | from :meth:`get_param`. This will return a suitably decoded Unicode |
R. David Murray | 7ec754b | 2010-12-13 23:51:19 +0000 | [diff] [blame] | 392 | string when the value is a tuple, or the original string unquoted if it |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 393 | isn't. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 394 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 395 | rawparam = msg.get_param('foo') |
Georg Brandl | 540b45c | 2009-04-27 16:45:26 +0000 | [diff] [blame] | 396 | param = email.utils.collapse_rfc2231_value(rawparam) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 397 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 398 | In any case, the parameter value (either the returned string, or the |
| 399 | ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set |
| 400 | to ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 401 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 402 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 403 | .. method:: set_param(param, value, header='Content-Type', requote=True, charset=None, language='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 404 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 405 | Set a parameter in the :mailheader:`Content-Type` header. If the |
| 406 | parameter already exists in the header, its value will be replaced with |
| 407 | *value*. If the :mailheader:`Content-Type` header as not yet been defined |
| 408 | for this message, it will be set to :mimetype:`text/plain` and the new |
| 409 | parameter value will be appended as per :rfc:`2045`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 410 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 411 | Optional *header* specifies an alternative header to |
| 412 | :mailheader:`Content-Type`, and all parameters will be quoted as necessary |
| 413 | unless optional *requote* is ``False`` (the default is ``True``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 414 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 415 | If optional *charset* is specified, the parameter will be encoded |
| 416 | according to :rfc:`2231`. Optional *language* specifies the RFC 2231 |
| 417 | language, defaulting to the empty string. Both *charset* and *language* |
| 418 | should be strings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 419 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 420 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 421 | .. method:: del_param(param, header='content-type', requote=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 422 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 423 | Remove the given parameter completely from the :mailheader:`Content-Type` |
| 424 | header. The header will be re-written in place without the parameter or |
| 425 | its value. All values will be quoted as necessary unless *requote* is |
| 426 | ``False`` (the default is ``True``). Optional *header* specifies an |
| 427 | alternative to :mailheader:`Content-Type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 428 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 429 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 430 | .. method:: set_type(type, header='Content-Type', requote=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 431 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 432 | Set the main type and subtype for the :mailheader:`Content-Type` |
| 433 | header. *type* must be a string in the form :mimetype:`maintype/subtype`, |
| 434 | otherwise a :exc:`ValueError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 435 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 436 | This method replaces the :mailheader:`Content-Type` header, keeping all |
| 437 | the parameters in place. If *requote* is ``False``, this leaves the |
| 438 | existing header's quoting as is, otherwise the parameters will be quoted |
| 439 | (the default). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 440 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 441 | An alternative header can be specified in the *header* argument. When the |
| 442 | :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` |
| 443 | header is also added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 444 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 445 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 446 | .. method:: get_filename(failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 447 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 448 | Return the value of the ``filename`` parameter of the |
| 449 | :mailheader:`Content-Disposition` header of the message. If the header |
| 450 | does not have a ``filename`` parameter, this method falls back to looking |
R. David Murray | 9ed34be | 2010-03-04 17:38:18 +0000 | [diff] [blame] | 451 | for the ``name`` parameter on the :mailheader:`Content-Type` header. If |
| 452 | neither is found, or the header is missing, then *failobj* is returned. |
| 453 | The returned string will always be unquoted as per |
| 454 | :func:`email.utils.unquote`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 455 | |
| 456 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 457 | .. method:: get_boundary(failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 458 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 459 | Return the value of the ``boundary`` parameter of the |
| 460 | :mailheader:`Content-Type` header of the message, or *failobj* if either |
| 461 | the header is missing, or has no ``boundary`` parameter. The returned |
Georg Brandl | 540b45c | 2009-04-27 16:45:26 +0000 | [diff] [blame] | 462 | string will always be unquoted as per :func:`email.utils.unquote`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 463 | |
| 464 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 465 | .. method:: set_boundary(boundary) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 466 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 467 | Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to |
| 468 | *boundary*. :meth:`set_boundary` will always quote *boundary* if |
| 469 | necessary. A :exc:`HeaderParseError` is raised if the message object has |
| 470 | no :mailheader:`Content-Type` header. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 471 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 472 | Note that using this method is subtly different than deleting the old |
| 473 | :mailheader:`Content-Type` header and adding a new one with the new |
| 474 | boundary via :meth:`add_header`, because :meth:`set_boundary` preserves |
| 475 | the order of the :mailheader:`Content-Type` header in the list of |
| 476 | headers. However, it does *not* preserve any continuation lines which may |
| 477 | have been present in the original :mailheader:`Content-Type` header. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 478 | |
| 479 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 480 | .. method:: get_content_charset(failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 481 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 482 | Return the ``charset`` parameter of the :mailheader:`Content-Type` header, |
| 483 | coerced to lower case. If there is no :mailheader:`Content-Type` header, or if |
| 484 | that header has no ``charset`` parameter, *failobj* is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 485 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 486 | Note that this method differs from :meth:`get_charset` which returns the |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 487 | :class:`~email.charset.Charset` instance for the default encoding of the message body. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 488 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 489 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 490 | .. method:: get_charsets(failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 491 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 492 | Return a list containing the character set names in the message. If the |
| 493 | message is a :mimetype:`multipart`, then the list will contain one element |
| 494 | for each subpart in the payload, otherwise, it will be a list of length 1. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 495 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 496 | Each item in the list will be a string which is the value of the |
| 497 | ``charset`` parameter in the :mailheader:`Content-Type` header for the |
| 498 | represented subpart. However, if the subpart has no |
| 499 | :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of |
| 500 | the :mimetype:`text` main MIME type, then that item in the returned list |
| 501 | will be *failobj*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 502 | |
| 503 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 504 | .. method:: walk() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 505 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 506 | The :meth:`walk` method is an all-purpose generator which can be used to |
| 507 | iterate over all the parts and subparts of a message object tree, in |
| 508 | depth-first traversal order. You will typically use :meth:`walk` as the |
| 509 | iterator in a ``for`` loop; each iteration returns the next subpart. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 510 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 511 | Here's an example that prints the MIME type of every part of a multipart |
| 512 | message structure:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 513 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 514 | >>> for part in msg.walk(): |
| 515 | ... print(part.get_content_type()) |
| 516 | multipart/report |
| 517 | text/plain |
| 518 | message/delivery-status |
| 519 | text/plain |
| 520 | text/plain |
| 521 | message/rfc822 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 522 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 523 | :class:`Message` objects can also optionally contain two instance attributes, |
| 524 | which can be used when generating the plain text of a MIME message. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 525 | |
| 526 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 527 | .. attribute:: preamble |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 528 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 529 | The format of a MIME document allows for some text between the blank line |
| 530 | following the headers, and the first multipart boundary string. Normally, |
| 531 | this text is never visible in a MIME-aware mail reader because it falls |
| 532 | outside the standard MIME armor. However, when viewing the raw text of |
| 533 | the message, or when viewing the message in a non-MIME aware reader, this |
| 534 | text can become visible. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 535 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 536 | The *preamble* attribute contains this leading extra-armor text for MIME |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 537 | documents. When the :class:`~email.parser.Parser` discovers some text |
| 538 | after the headers but before the first boundary string, it assigns this |
| 539 | text to the message's *preamble* attribute. When the |
| 540 | :class:`~email.generator.Generator` is writing out the plain text |
| 541 | representation of a MIME message, and it finds the |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 542 | message has a *preamble* attribute, it will write this text in the area |
| 543 | between the headers and the first boundary. See :mod:`email.parser` and |
| 544 | :mod:`email.generator` for details. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 545 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 546 | Note that if the message object has no preamble, the *preamble* attribute |
| 547 | will be ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 548 | |
| 549 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 550 | .. attribute:: epilogue |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 551 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 552 | The *epilogue* attribute acts the same way as the *preamble* attribute, |
| 553 | except that it contains text that appears between the last boundary and |
| 554 | the end of the message. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 555 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 556 | You do not need to set the epilogue to the empty string in order for the |
| 557 | :class:`Generator` to print a newline at the end of the file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 558 | |
| 559 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 560 | .. attribute:: defects |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 561 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 562 | The *defects* attribute contains a list of all the problems found when |
| 563 | parsing this message. See :mod:`email.errors` for a detailed description |
| 564 | of the possible parsing defects. |