R David Murray | 79cf3ba | 2012-05-27 17:10:36 -0400 | [diff] [blame] | 1 | :mod:`email.message`: Representing an email message |
| 2 | --------------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: email.message |
| 5 | :synopsis: The base class representing email messages. |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 6 | .. moduleauthor:: R. David Murray <rdmurray@bitdance.com> |
| 7 | .. sectionauthor:: R. David Murray <rdmurray@bitdance.com>, |
| 8 | Barry A. Warsaw <barry@python.org> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | **Source code:** :source:`Lib/email/message.py` |
| 11 | |
| 12 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
R David Murray | 7f730cf | 2016-09-08 18:28:43 -0400 | [diff] [blame] | 14 | .. versionadded:: 3.6 [1]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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 |
| 19 | functionality for setting and querying header fields, for accessing message |
| 20 | bodies, and for creating or modifying structured messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 22 | An email message consists of *headers* and a *payload* (which is also referred |
| 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 |
| 26 | simple text message, or a binary object, or a structured sequence of |
| 27 | sub-messages each with their own set of headers and their own payload. The |
| 28 | latter type of payload is indicated by the message having a MIME type such as |
| 29 | :mimetype:`multipart/\*` or :mimetype:`message/rfc822`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 31 | The conceptual model provided by an :class:`EmailMessage` object is that of an |
| 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 |
| 35 | names and values, there are methods for accessing specialized information from |
| 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. |
| 39 | |
| 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 |
| 42 | with some extra methods. Headers are stored and returned in case-preserving |
| 43 | form, but field names are matched case-insensitively. Unlike a real dict, |
| 44 | there is an ordering to the keys, and there can be duplicate keys. Additional |
| 45 | methods are provided for working with headers that have duplicate keys. |
| 46 | |
| 47 | The *payload* is either a string or bytes object, in the case of simple message |
| 48 | objects, or a list of :class:`EmailMessage` objects, for MIME container |
| 49 | documents such as :mimetype:`multipart/\*` and :mimetype:`message/rfc822` |
| 50 | message objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | |
| 52 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 53 | .. class:: EmailMessage(policy=default) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 55 | If *policy* is specified use the rules it specifies to udpate 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 |
R David Murray | bb17d2b | 2013-08-09 16:15:28 -0400 | [diff] [blame] | 60 | :mod:`~email.policy` documentation. |
| 61 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 62 | .. method:: as_string(unixfrom=False, maxheaderlen=None, policy=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 64 | Return the entire message flattened as a string. When optional |
| 65 | *unixfrom* is true, the envelope header is included in the returned |
| 66 | string. *unixfrom* defaults to ``False``. For backward compabitility |
| 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`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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 |
| 78 | string (for example, MIME boundaries may be generated or modified). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 80 | Note that this method is provided as a convenience and may not be the |
| 81 | most useful way to serialize messages in your application, especially if |
| 82 | you are dealing with multiple messages. See |
| 83 | :class:`email.generator.Generator` for a more flexible API for |
| 84 | serializing messages. Note also that this method is restricted to |
| 85 | producing messages serialized as "7 bit clean" when |
| 86 | :attr:`~email.policy.EmailPolicy.utf8` is ``False``, which is the default. |
R David Murray | bb17d2b | 2013-08-09 16:15:28 -0400 | [diff] [blame] | 87 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 88 | .. versionchanged:: 3.6 the default behavior when *maxheaderlen* |
| 89 | is not specified was changed from defaulting to 0 to defaulting |
| 90 | to the value of *max_line_length* from the policy. |
R David Murray | bb17d2b | 2013-08-09 16:15:28 -0400 | [diff] [blame] | 91 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 93 | .. method:: __str__() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 95 | Equivalent to `as_string(policy=self.policy.clone(utf8=True)`. Allows |
| 96 | ``str(msg)`` to produce a string containing the serialized message in a |
| 97 | readable format. |
| 98 | |
| 99 | .. versionchanged:: 3.4 the method was changed to use ``utf8=True``, |
| 100 | thus producing an :rfc:`6531`-like message representation, instead of |
| 101 | being a direct alias for :meth:`as_string`. |
R David Murray | bb17d2b | 2013-08-09 16:15:28 -0400 | [diff] [blame] | 102 | |
| 103 | |
| 104 | .. method:: as_bytes(unixfrom=False, policy=None) |
| 105 | |
| 106 | Return the entire message flattened as a bytes object. When optional |
| 107 | *unixfrom* is true, the envelope header is included in the returned |
| 108 | string. *unixfrom* defaults to ``False``. The *policy* argument may be |
| 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 |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 112 | :class:`~email.generator.BytesGenerator`. |
R David Murray | bb17d2b | 2013-08-09 16:15:28 -0400 | [diff] [blame] | 113 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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 |
| 116 | string (for example, MIME boundaries may be generated or modified). |
R David Murray | bb17d2b | 2013-08-09 16:15:28 -0400 | [diff] [blame] | 117 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 118 | Note that this method is provided as a convenience and may not be the |
| 119 | most useful way to serialize messages in your application, especially if |
| 120 | you are dealing with multiple messages. See |
| 121 | :class:`email.generator.BytesGenerator` for a more flexible API for |
| 122 | serializing messages. |
R David Murray | bb17d2b | 2013-08-09 16:15:28 -0400 | [diff] [blame] | 123 | |
| 124 | |
| 125 | .. method:: __bytes__() |
| 126 | |
| 127 | Equivalent to :meth:`.as_bytes()`. Allows ``bytes(msg)`` to produce a |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 128 | bytes object containing the serialized message. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | |
| 130 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 131 | .. method:: is_multipart() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 133 | Return ``True`` if the message's payload is a list of sub-\ |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 134 | :class:`EmailMessage` objects, otherwise return ``False``. When |
R David Murray | 9cc5fd7 | 2014-09-27 15:37:40 -0400 | [diff] [blame] | 135 | :meth:`is_multipart` returns ``False``, the payload should be a string |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 136 | object (which might be a CTE encoded binary payload). Note that |
| 137 | :meth:`is_multipart` returning ``True`` does not necessarily mean that |
| 138 | "msg.get_content_maintype() == 'multipart'" will return the ``True``. |
| 139 | For example, ``is_multipart`` will return ``True`` when the |
| 140 | :class:`EmailMessage` is of type ``message/rfc822``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
| 142 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 143 | .. method:: set_unixfrom(unixfrom) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 145 | Set the message's envelope header to *unixfrom*, which should be a |
| 146 | string. (See :class:`~mailbox.mboxMessage` for a brief description of |
| 147 | this header.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
| 149 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 150 | .. method:: get_unixfrom() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 152 | Return the message's envelope header. Defaults to ``None`` if the |
| 153 | envelope header was never set. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | |
| 155 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 156 | The following methods implement the mapping-like interface for accessing the |
| 157 | message's headers. Note that there are some semantic differences |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 158 | between these methods and a normal mapping (i.e. dictionary) interface. For |
| 159 | example, in a dictionary there are no duplicate keys, but here there may be |
| 160 | duplicate message headers. Also, in dictionaries there is no guaranteed |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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 |
| 165 | header list. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 167 | These semantic differences are intentional and are biased toward |
| 168 | convenience in the most common use cases. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 170 | Note that in all cases, any envelope header present in the message is not |
| 171 | included in the mapping interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | |
| 173 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 174 | .. method:: __len__() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 175 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 176 | Return the total number of headers, including duplicates. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 177 | |
| 178 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 179 | .. method:: __contains__(name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 181 | Return true if the message object has a field named *name*. Matching is |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 182 | done without regard to case and *name* does not include the trailing |
| 183 | colon. Used for the ``in`` operator. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 184 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 185 | if 'message-id' in myMessage: |
| 186 | print('Message-ID:', myMessage['message-id']) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | |
| 188 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 189 | .. method:: __getitem__(name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 190 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 191 | Return the value of the named header field. *name* does not include the |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 192 | colon field separator. If the header is missing, ``None`` is returned; a |
| 193 | :exc:`KeyError` is never raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 195 | Note that if the named field appears more than once in the message's |
| 196 | headers, exactly which of those field values will be returned is |
| 197 | undefined. Use the :meth:`get_all` method to get the values of all the |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 198 | extant headers named *name*. |
| 199 | |
| 200 | Using the standard (non-``compat32``) policies, the returned value is an |
| 201 | instance of a subclass of :class:`email.headerregistry.BaseHeader`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 202 | |
| 203 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 204 | .. method:: __setitem__(name, val) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 206 | Add a header to the message with field name *name* and value *val*. The |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 207 | field is appended to the end of the message's existing headers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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.:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 212 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 213 | del msg['subject'] |
| 214 | msg['subject'] = 'Python roolz!' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 216 | If the :mod:`policy` defines certain haders to be unique (as the standard |
| 217 | policies do), this method may raise a :exc:`ValueError` when an attempt |
| 218 | is made to assign a value to such a header when one already exists. This |
| 219 | behavior is intentional for consistency's sake, but do not depend on it |
| 220 | as we may choose to make such assignments do an automatic deletion of the |
| 221 | existing header in the future. |
| 222 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 223 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 224 | .. method:: __delitem__(name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 225 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 226 | 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] | 227 | headers. No exception is raised if the named field isn't present in the |
| 228 | headers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | |
| 230 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 231 | .. method:: keys() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 233 | Return a list of all the message's header field names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | |
| 235 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 236 | .. method:: values() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 238 | Return a list of all the message's field values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 239 | |
| 240 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 241 | .. method:: items() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 242 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 243 | Return a list of 2-tuples containing all the message's field headers and |
| 244 | values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 245 | |
| 246 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 247 | .. method:: get(name, failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 248 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 249 | Return the value of the named header field. This is identical to |
| 250 | :meth:`__getitem__` except that optional *failobj* is returned if the |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 251 | named header is missing (*failobj* defaults to ``None``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 252 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 253 | |
| 254 | Here are some additional useful header related methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 255 | |
| 256 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 257 | .. method:: get_all(name, failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 258 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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 |
| 261 | ``None``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 262 | |
| 263 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 264 | .. method:: add_header(_name, _value, **_params) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 265 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 266 | Extended header setting. This method is similar to :meth:`__setitem__` |
| 267 | except that additional header parameters can be provided as keyword |
| 268 | arguments. *_name* is the header field to add and *_value* is the |
| 269 | *primary* value for the header. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 270 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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 |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 275 | only the key will be added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 276 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 277 | If the value contains non-ASCII characters, the charset and language may |
Martin Panter | cf01441 | 2016-11-20 08:37:21 +0000 | [diff] [blame] | 278 | be explicitly controlled by specifying the value as a three tuple in the |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 279 | format ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string |
| 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 |
| 284 | non-ASCII characters, it is automatically encoded in :rfc:`2231` format |
| 285 | using a ``CHARSET`` of ``utf-8`` and a ``LANGUAGE`` of ``None``. |
| 286 | |
| 287 | Here is an example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 288 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 289 | msg.add_header('Content-Disposition', 'attachment', filename='bud.gif') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 290 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 291 | This will add a header that looks like :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 292 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 293 | Content-Disposition: attachment; filename="bud.gif" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 294 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 295 | An example of the extended interface with non-ASCII characters:: |
R. David Murray | 7ec754b | 2010-12-13 23:51:19 +0000 | [diff] [blame] | 296 | |
| 297 | msg.add_header('Content-Disposition', 'attachment', |
| 298 | filename=('iso-8859-1', '', 'Fußballer.ppt')) |
| 299 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 300 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 301 | .. method:: replace_header(_name, _value) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 302 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 303 | Replace a header. Replace the first header found in the message that |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 304 | matches *_name*, retaining header order and field name case of the |
| 305 | original header. If no matching header is found, raise a |
| 306 | :exc:`KeyError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 307 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 308 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 309 | .. method:: get_content_type() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 310 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 311 | Return the message's content type, coerced to lower case of the form |
| 312 | :mimetype:`maintype/subtype`. If there is no :mailheader:`Content-Type` |
| 313 | header in the message return the value returned by |
| 314 | :meth:`get_default_type`. If the :mailheader:`Content-Type` header is |
| 315 | invalid, return ``text/plain``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 316 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 317 | (According to :rfc:`2045`, messages always have a default type, |
| 318 | :meth:`get_content_type` will always return a value. :rfc:`2045` defines |
| 319 | a message's default type to be :mimetype:`text/plain` unless it appears |
| 320 | inside a :mimetype:`multipart/digest` container, in which case it would |
| 321 | be :mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header |
| 322 | has an invalid type specification, :rfc:`2045` mandates that the default |
| 323 | type be :mimetype:`text/plain`.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 324 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 326 | .. method:: get_content_maintype() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 327 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 328 | Return the message's main content type. This is the :mimetype:`maintype` |
| 329 | part of the string returned by :meth:`get_content_type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 330 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 331 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 332 | .. method:: get_content_subtype() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 333 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 334 | Return the message's sub-content type. This is the :mimetype:`subtype` |
| 335 | part of the string returned by :meth:`get_content_type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 336 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 337 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 338 | .. method:: get_default_type() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 339 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 340 | Return the default content type. Most messages have a default content |
| 341 | type of :mimetype:`text/plain`, except for messages that are subparts of |
| 342 | :mimetype:`multipart/digest` containers. Such subparts have a default |
| 343 | content type of :mimetype:`message/rfc822`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 344 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 345 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 346 | .. method:: set_default_type(ctype) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 347 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 348 | Set the default content type. *ctype* should either be |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 349 | :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is |
| 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 354 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 355 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 356 | .. method:: set_param(param, value, header='Content-Type', requote=True, \ |
R David Murray | 3da240f | 2013-10-16 22:48:40 -0400 | [diff] [blame] | 357 | charset=None, language='', replace=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 358 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 359 | Set a parameter in the :mailheader:`Content-Type` header. If the |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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 |
| 364 | *header* specifies an alternative header to :mailheader:`Content-Type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 365 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 366 | If the value contains non-ASCII characters, the charset and language may |
Mariatta | 1b93ed4 | 2017-02-28 21:08:13 -0800 | [diff] [blame] | 367 | be explicitly specified using the optional *charset* and *language* |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 372 | |
R David Murray | 3da240f | 2013-10-16 22:48:40 -0400 | [diff] [blame] | 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 |
| 375 | will be updated in place. |
| 376 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 377 | Use of the *requote* parameter with :class:`EmailMessage` objects is |
| 378 | deprecated. |
| 379 | |
| 380 | Note that existing parameter values of headers may be accessed through |
| 381 | the :attr:`~email.headerregistry.BaseHeader.params` attribute of the |
| 382 | header value (for example, ``msg['Content-Type'].params['charset']``. |
| 383 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 384 | .. versionchanged:: 3.4 ``replace`` keyword was added. |
R David Murray | 3da240f | 2013-10-16 22:48:40 -0400 | [diff] [blame] | 385 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 386 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 387 | .. method:: del_param(param, header='content-type', requote=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 388 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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 |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 391 | its value. Optional *header* specifies an alternative to |
| 392 | :mailheader:`Content-Type`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 393 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 394 | Use of the *requote* parameter with :class:`EmailMessage` objects is |
| 395 | deprecated. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 396 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 397 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 398 | .. method:: get_filename(failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 399 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 400 | Return the value of the ``filename`` parameter of the |
| 401 | :mailheader:`Content-Disposition` header of the message. If the header |
| 402 | 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] | 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. |
| 405 | The returned string will always be unquoted as per |
| 406 | :func:`email.utils.unquote`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 407 | |
| 408 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 409 | .. method:: get_boundary(failobj=None) |
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 | 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 |
Georg Brandl | 540b45c | 2009-04-27 16:45:26 +0000 | [diff] [blame] | 414 | string will always be unquoted as per :func:`email.utils.unquote`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 415 | |
| 416 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 417 | .. method:: set_boundary(boundary) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 418 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 419 | Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to |
| 420 | *boundary*. :meth:`set_boundary` will always quote *boundary* if |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 421 | necessary. A :exc:`~email.errors.HeaderParseError` is raised if the |
| 422 | message object has no :mailheader:`Content-Type` header. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 423 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 424 | Note that using this method is subtly different from deleting the old |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 425 | :mailheader:`Content-Type` header and adding a new one with the new |
| 426 | boundary via :meth:`add_header`, because :meth:`set_boundary` preserves |
| 427 | the order of the :mailheader:`Content-Type` header in the list of |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 428 | headers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 429 | |
| 430 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 431 | .. method:: get_content_charset(failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 432 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 433 | Return the ``charset`` parameter of the :mailheader:`Content-Type` header, |
| 434 | coerced to lower case. If there is no :mailheader:`Content-Type` header, or if |
| 435 | that header has no ``charset`` parameter, *failobj* is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 436 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 437 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 438 | .. method:: get_charsets(failobj=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 439 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 443 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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 |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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*. |
| 449 | |
| 450 | |
| 451 | .. method:: is_attachment |
| 452 | |
| 453 | Return ``True`` if there is a :mailheader:`Content-Disposition` header |
| 454 | and its (case insensitive) value is ``attachment``, ``False`` otherwise. |
| 455 | |
| 456 | .. versionchanged:: 3.4.2 |
| 457 | is_attachment is now a method instead of a property, for consistency |
| 458 | with :meth:`~email.message.Message.is_multipart`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 459 | |
| 460 | |
R David Murray | b744f3a | 2015-05-16 15:41:07 -0400 | [diff] [blame] | 461 | .. method:: get_content_disposition() |
| 462 | |
| 463 | Return the lowercased value (without parameters) of the message's |
| 464 | :mailheader:`Content-Disposition` header if it has one, or ``None``. The |
| 465 | possible values for this method are *inline*, *attachment* or ``None`` |
| 466 | if the message follows :rfc:`2183`. |
| 467 | |
| 468 | .. versionadded:: 3.5 |
| 469 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 470 | |
| 471 | The following methods relate to interrogating and manipulating the content |
| 472 | (payload) of the message. |
| 473 | |
| 474 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 475 | .. method:: walk() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 476 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 477 | The :meth:`walk` method is an all-purpose generator which can be used to |
| 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. |
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 | Here's an example that prints the MIME type of every part of a multipart |
R David Murray | fdfb005 | 2013-07-29 15:49:58 -0400 | [diff] [blame] | 483 | message structure: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 484 | |
R David Murray | 9cc5fd7 | 2014-09-27 15:37:40 -0400 | [diff] [blame] | 485 | .. testsetup:: |
R David Murray | fdfb005 | 2013-07-29 15:49:58 -0400 | [diff] [blame] | 486 | |
Zachary Ware | 640b1ca | 2016-08-10 00:39:41 -0500 | [diff] [blame] | 487 | from email import message_from_binary_file |
| 488 | with open('../Lib/test/test_email/data/msg_16.txt', 'rb') as f: |
| 489 | msg = message_from_binary_file(f) |
| 490 | from email.iterators import _structure |
R David Murray | fdfb005 | 2013-07-29 15:49:58 -0400 | [diff] [blame] | 491 | |
R David Murray | 9cc5fd7 | 2014-09-27 15:37:40 -0400 | [diff] [blame] | 492 | .. doctest:: |
R David Murray | fdfb005 | 2013-07-29 15:49:58 -0400 | [diff] [blame] | 493 | |
R David Murray | 9cc5fd7 | 2014-09-27 15:37:40 -0400 | [diff] [blame] | 494 | >>> for part in msg.walk(): |
| 495 | ... print(part.get_content_type()) |
| 496 | multipart/report |
| 497 | text/plain |
| 498 | message/delivery-status |
| 499 | text/plain |
| 500 | text/plain |
| 501 | message/rfc822 |
| 502 | text/plain |
| 503 | |
| 504 | ``walk`` iterates over the subparts of any part where |
| 505 | :meth:`is_multipart` returns ``True``, even though |
| 506 | ``msg.get_content_maintype() == 'multipart'`` may return ``False``. We |
| 507 | can see this in our example by making use of the ``_structure`` debug |
| 508 | helper function: |
| 509 | |
| 510 | .. doctest:: |
| 511 | |
| 512 | >>> for part in msg.walk(): |
Zachary Ware | 640b1ca | 2016-08-10 00:39:41 -0500 | [diff] [blame] | 513 | ... print(part.get_content_maintype() == 'multipart', |
R David Murray | 9cc5fd7 | 2014-09-27 15:37:40 -0400 | [diff] [blame] | 514 | ... part.is_multipart()) |
| 515 | True True |
| 516 | False False |
| 517 | False True |
| 518 | False False |
| 519 | False False |
| 520 | False True |
| 521 | False False |
| 522 | >>> _structure(msg) |
| 523 | multipart/report |
| 524 | text/plain |
Zachary Ware | 640b1ca | 2016-08-10 00:39:41 -0500 | [diff] [blame] | 525 | message/delivery-status |
| 526 | text/plain |
| 527 | text/plain |
| 528 | message/rfc822 |
| 529 | text/plain |
R David Murray | 9cc5fd7 | 2014-09-27 15:37:40 -0400 | [diff] [blame] | 530 | |
| 531 | Here the ``message`` parts are not ``multiparts``, but they do contain |
| 532 | subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends |
| 533 | into the subparts. |
| 534 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 535 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 536 | .. method:: get_body(preferencelist=('related', 'html', 'plain')) |
| 537 | |
| 538 | Return the MIME part that is the best candidate to be the "body" of the |
| 539 | message. |
| 540 | |
| 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. |
| 544 | |
| 545 | Start looking for candidate matches with the object on which the |
| 546 | ``get_body`` method is called. |
| 547 | |
| 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. |
| 551 | |
| 552 | When encountering a ``multipart/related``, check the ``start`` parameter |
| 553 | and if a part with a matching :mailheader:`Content-ID` is found, consider |
| 554 | only it when looking for candidate matches. Otherwise consider only the |
| 555 | first (default root) part of the ``multipart/related``. |
| 556 | |
| 557 | If a part has a :mailheader:`Content-Disposition` header, only consider |
| 558 | the part a candidate match if the value of the header is ``inline``. |
| 559 | |
| 560 | If none of the candidates matches any of the preferences in |
| 561 | *preferneclist*, return ``None``. |
| 562 | |
| 563 | Notes: (1) For most applications the only *preferencelist* combinations |
| 564 | that really make sense are ``('plain',)``, ``('html', 'plain')``, and the |
| 565 | default ``('related', 'html', 'plain')``. (2) Because matching starts |
| 566 | with the object on which ``get_body`` is called, calling ``get_body`` on |
| 567 | a ``multipart/related`` will return the object itself unless |
| 568 | *preferencelist* has a non-default value. (3) Messages (or message parts) |
| 569 | that do not specify a :mailheader:`Content-Type` or whose |
| 570 | :mailheader:`Content-Type` header is invalid will be treated as if they |
| 571 | are of type ``text/plain``, which may occasionally cause ``get_body`` to |
| 572 | return unexpected results. |
| 573 | |
| 574 | |
| 575 | .. method:: iter_attachments() |
| 576 | |
| 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 |
| 579 | of each of ``text/plain``, ``text/html``, ``multipart/related``, or |
| 580 | ``multipart/alternative`` (unless they are explicitly marked as |
| 581 | attachments via :mailheader:`Content-Disposition: attachment`), and |
| 582 | return all remaining parts. When applied directly to a |
| 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 |
| 587 | parts). When applied directly to a ``multipart/alternative`` or a |
| 588 | non-``multipart``, return an empty iterator. |
| 589 | |
| 590 | |
| 591 | .. method:: iter_parts() |
| 592 | |
| 593 | Return an iterator over all of the immediate sub-parts of the message, |
| 594 | which will be empty for a non-``multipart``. (See also |
| 595 | :meth:`~email.message.EmailMessage.walk`.) |
| 596 | |
| 597 | |
| 598 | .. method:: get_content(*args, content_manager=None, **kw) |
| 599 | |
| 600 | Call the :meth:`~email.contentmanager.ContentManager.get_content` method |
| 601 | of the *content_manager*, passing self as the message object, and passing |
| 602 | along any other arguments or keywords as additional arguments. If |
| 603 | *content_manager* is not specified, use the ``content_manager`` specified |
| 604 | by the current :mod:`~email.policy`. |
| 605 | |
| 606 | |
| 607 | .. method:: set_content(*args, content_manager=None, **kw) |
| 608 | |
| 609 | Call the :meth:`~email.contentmanager.ContentManager.set_content` method |
| 610 | of the *content_manager*, passing self as the message object, and passing |
| 611 | along any other arguments or keywords as additional arguments. If |
| 612 | *content_manager* is not specified, use the ``content_manager`` specified |
| 613 | by the current :mod:`~email.policy`. |
| 614 | |
| 615 | |
| 616 | .. method:: make_related(boundary=None) |
| 617 | |
| 618 | Convert a non-``multipart`` message into a ``multipart/related`` message, |
| 619 | moving any existing :mailheader:`Content-` headers and payload into a |
| 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 |
| 623 | message is serialized). |
| 624 | |
| 625 | |
| 626 | .. method:: make_alternative(boundary=None) |
| 627 | |
| 628 | Convert a non-``multipart`` or a ``multipart/related`` into a |
| 629 | ``multipart/alternative``, moving any existing :mailheader:`Content-` |
| 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). |
| 634 | |
| 635 | |
| 636 | .. method:: make_mixed(boundary=None) |
| 637 | |
| 638 | Convert a non-``multipart``, a ``multipart/related``, or a |
| 639 | ``multipart-alternative`` into a ``multipart/mixed``, moving any existing |
| 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). |
| 644 | |
| 645 | |
| 646 | .. method:: add_related(*args, content_manager=None, **kw) |
| 647 | |
| 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``, |
| 653 | raise a :exc:`TypeError`. If *content_manager* is not specified, use |
| 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``. |
| 657 | |
| 658 | |
| 659 | .. method:: add_alternative(*args, content_manager=None, **kw) |
| 660 | |
| 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 |
| 664 | message is a non-``multipart`` or ``multipart/related``, call |
| 665 | :meth:`make_alternative` and then proceed as above. If the message is |
| 666 | any other type of ``multipart``, raise a :exc:`TypeError`. If |
| 667 | *content_manager* is not specified, use the ``content_manager`` specified |
| 668 | by the current :mod:`~email.policy`. |
| 669 | |
| 670 | |
| 671 | .. method:: add_attachment(*args, content_manager=None, **kw) |
| 672 | |
| 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 |
| 676 | message is a non-``multipart``, ``multipart/related``, or |
| 677 | ``multipart/alternative``, call :meth:`make_mixed` and then proceed as |
| 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 |
| 681 | ``attachment``. This method can be used both for explicit attachments |
| 682 | (:mailheader:`Content-Disposition: attachment` and ``inline`` attachments |
| 683 | (:mailheader:`Content-Disposition: inline`), by passing appropriate |
| 684 | options to the ``content_manager``. |
| 685 | |
| 686 | |
| 687 | .. method:: clear() |
| 688 | |
| 689 | Remove the payload and all of the headers. |
| 690 | |
| 691 | |
| 692 | .. method:: clear_content() |
| 693 | |
| 694 | Remove the payload and all of the :exc:`Content-` headers, leaving |
| 695 | all other headers intact and in their original order. |
| 696 | |
| 697 | |
| 698 | :class:`EmailMessage` objects have the following instance attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 699 | |
| 700 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 701 | .. attribute:: preamble |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 702 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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, |
| 705 | this text is never visible in a MIME-aware mail reader because it falls |
| 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 |
| 708 | text can become visible. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 709 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 710 | The *preamble* attribute contains this leading extra-armor text for MIME |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 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 |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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 |
| 718 | :mod:`email.generator` for details. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 719 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 720 | Note that if the message object has no preamble, the *preamble* attribute |
| 721 | will be ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 722 | |
| 723 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 724 | .. attribute:: epilogue |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 725 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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 |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 728 | the end of the message. As with the :attr:`~EmailMessage.preamble`, |
| 729 | if there is no epilog text this attribute will be ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 730 | |
| 731 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 732 | .. attribute:: defects |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 733 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 734 | The *defects* attribute contains a list of all the problems found when |
| 735 | parsing this message. See :mod:`email.errors` for a detailed description |
| 736 | of the possible parsing defects. |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 737 | |
| 738 | |
| 739 | .. class:: MIMEPart(policy=default) |
| 740 | |
| 741 | This class represents a subpart of a MIME message. It is identical to |
| 742 | :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are |
| 743 | added when :meth:`~EmailMessage.set_content` is called, since sub-parts do |
| 744 | not need their own :mailheader:`MIME-Version` headers. |
R David Murray | 7f730cf | 2016-09-08 18:28:43 -0400 | [diff] [blame] | 745 | |
| 746 | |
| 747 | .. rubric:: Footnotes |
| 748 | |
| 749 | .. [1] Oringally added in 3.4 as a :term:`provisional module <provisional |
| 750 | package>`. Docs for legacy message class moved to |
| 751 | :ref:`compat32_message`. |