1 :mod:`email` --- An email and MIME handling package 2 =================================================== 3 4 .. module:: email 5 :synopsis: Package supporting the parsing, manipulating, and generating email messages, 6 including MIME documents. 7 .. moduleauthor:: Barry A. Warsaw <barry (a] python.org> 8 .. sectionauthor:: Barry A. Warsaw <barry (a] python.org> 9 .. Copyright (C) 2001-2007 Python Software Foundation 10 11 12 .. versionadded:: 2.2 13 14 The :mod:`email` package is a library for managing email messages, including 15 MIME and other :rfc:`2822`\ -based message documents. It subsumes most of the 16 functionality in several older standard modules such as :mod:`rfc822`, 17 :mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as 18 :mod:`mimecntl`. It is specifically *not* designed to do any sending of email 19 messages to SMTP (:rfc:`2821`), NNTP, or other servers; those are functions of 20 modules such as :mod:`smtplib` and :mod:`nntplib`. The :mod:`email` package 21 attempts to be as RFC-compliant as possible, supporting in addition to 22 :rfc:`2822`, such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, 23 and :rfc:`2231`. 24 25 The primary distinguishing feature of the :mod:`email` package is that it splits 26 the parsing and generating of email messages from the internal *object model* 27 representation of email. Applications using the :mod:`email` package deal 28 primarily with objects; you can add sub-objects to messages, remove sub-objects 29 from messages, completely re-arrange the contents, etc. There is a separate 30 parser and a separate generator which handles the transformation from flat text 31 to the object model, and then back to flat text again. There are also handy 32 subclasses for some common MIME object types, and a few miscellaneous utilities 33 that help with such common tasks as extracting and parsing message field values, 34 creating RFC-compliant dates, etc. 35 36 The following sections describe the functionality of the :mod:`email` package. 37 The ordering follows a progression that should be common in applications: an 38 email message is read as flat text from a file or other source, the text is 39 parsed to produce the object structure of the email message, this structure is 40 manipulated, and finally, the object tree is rendered back into flat text. 41 42 It is perfectly feasible to create the object structure out of whole cloth --- 43 i.e. completely from scratch. From there, a similar progression can be taken as 44 above. 45 46 Also included are detailed specifications of all the classes and modules that 47 the :mod:`email` package provides, the exception classes you might encounter 48 while using the :mod:`email` package, some auxiliary utilities, and a few 49 examples. For users of the older :mod:`mimelib` package, or previous versions 50 of the :mod:`email` package, a section on differences and porting is provided. 51 52 Contents of the :mod:`email` package documentation: 53 54 .. toctree:: 55 56 email.message.rst 57 email.parser.rst 58 email.generator.rst 59 email.mime.rst 60 email.header.rst 61 email.charset.rst 62 email.encoders.rst 63 email.errors.rst 64 email.util.rst 65 email.iterators.rst 66 email-examples.rst 67 68 69 .. seealso:: 70 71 Module :mod:`smtplib` 72 SMTP protocol client 73 74 Module :mod:`nntplib` 75 NNTP protocol client 76 77 78 .. _email-pkg-history: 79 80 Package History 81 --------------- 82 83 This table describes the release history of the email package, corresponding to 84 the version of Python that the package was released with. For purposes of this 85 document, when you see a note about change or added versions, these refer to the 86 Python version the change was made in, *not* the email package version. This 87 table also describes the Python compatibility of each version of the package. 88 89 +---------------+------------------------------+-----------------------+ 90 | email version | distributed with | compatible with | 91 +===============+==============================+=======================+ 92 | :const:`1.x` | Python 2.2.0 to Python 2.2.1 | *no longer supported* | 93 +---------------+------------------------------+-----------------------+ 94 | :const:`2.5` | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5 | 95 +---------------+------------------------------+-----------------------+ 96 | :const:`3.0` | Python 2.4 | Python 2.3 to 2.5 | 97 +---------------+------------------------------+-----------------------+ 98 | :const:`4.0` | Python 2.5 | Python 2.3 to 2.5 | 99 +---------------+------------------------------+-----------------------+ 100 101 Here are the major differences between :mod:`email` version 4 and version 3: 102 103 * All modules have been renamed according to :pep:`8` standards. For example, 104 the version 3 module :mod:`email.Message` was renamed to :mod:`email.message` in 105 version 4. 106 107 * A new subpackage :mod:`email.mime` was added and all the version 3 108 :mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mime` 109 subpackage. For example, the version 3 module :mod:`email.MIMEText` was renamed 110 to :mod:`email.mime.text`. 111 112 *Note that the version 3 names will continue to work until Python 2.6*. 113 114 * The :mod:`email.mime.application` module was added, which contains the 115 :class:`~email.mime.application.MIMEApplication` class. 116 117 * Methods that were deprecated in version 3 have been removed. These include 118 :meth:`Generator.__call__`, :meth:`Message.get_type`, 119 :meth:`Message.get_main_type`, :meth:`Message.get_subtype`. 120 121 * Fixes have been added for :rfc:`2231` support which can change some of the 122 return types for :func:`Message.get_param <email.message.Message.get_param>` 123 and friends. Under some 124 circumstances, values which used to return a 3-tuple now return simple strings 125 (specifically, if all extended parameter segments were unencoded, there is no 126 language and charset designation expected, so the return type is now a simple 127 string). Also, %-decoding used to be done for both encoded and unencoded 128 segments; this decoding is now done only for encoded segments. 129 130 Here are the major differences between :mod:`email` version 3 and version 2: 131 132 * The :class:`~email.parser.FeedParser` class was introduced, and the 133 :class:`~email.parser.Parser` class was implemented in terms of the 134 :class:`~email.parser.FeedParser`. All parsing therefore is 135 non-strict, and parsing will make a best effort never to raise an exception. 136 Problems found while parsing messages are stored in the message's *defect* 137 attribute. 138 139 * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2 140 have been removed. These include the *_encoder* argument to the 141 :class:`~email.mime.text.MIMEText` constructor, the 142 :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair` 143 function, and the functions :func:`Utils.decode` and :func:`Utils.encode`. 144 145 * New :exc:`DeprecationWarning`\ s have been added to: 146 :meth:`Generator.__call__`, :meth:`Message.get_type`, 147 :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict* 148 argument to the :class:`~email.parser.Parser` class. These are expected to 149 be removed in future versions. 150 151 * Support for Pythons earlier than 2.3 has been removed. 152 153 Here are the differences between :mod:`email` version 2 and version 1: 154 155 * The :mod:`email.Header` and :mod:`email.Charset` modules have been added. 156 157 * The pickle format for :class:`~email.message.Message` instances has changed. 158 Since this was never (and still isn't) formally defined, this isn't 159 considered a backward incompatibility. However if your application pickles 160 and unpickles :class:`~email.message.Message` instances, be aware that in 161 :mod:`email` version 2, :class:`~email.message.Message` instances now have 162 private variables *_charset* and *_default_type*. 163 164 * Several methods in the :class:`~email.message.Message` class have been 165 deprecated, or their signatures changed. Also, many new methods have been 166 added. See the documentation for the :class:`~email.message.Message` class 167 for details. The changes should be completely backward compatible. 168 169 * The object structure has changed in the face of :mimetype:`message/rfc822` 170 content types. In :mod:`email` version 1, such a type would be represented 171 by a scalar payload, i.e. the container message's 172 :meth:`~email.message.Message.is_multipart` returned false, 173 :meth:`~email.message.Message.get_payload` was not a list object, but a 174 single :class:`~email.message.Message` instance. 175 176 This structure was inconsistent with the rest of the package, so the object 177 representation for :mimetype:`message/rfc822` content types was changed. In 178 :mod:`email` version 2, the container *does* return ``True`` from 179 :meth:`~email.message.Message.is_multipart`, and 180 :meth:`~email.message.Message.get_payload` returns a list containing a single 181 :class:`~email.message.Message` item. 182 183 Note that this is one place that backward compatibility could not be 184 completely maintained. However, if you're already testing the return type of 185 :meth:`~email.message.Message.get_payload`, you should be fine. You just need 186 to make sure your code doesn't do a :meth:`~email.message.Message.set_payload` 187 with a :class:`~email.message.Message` instance on a container with a content 188 type of :mimetype:`message/rfc822`. 189 190 * The :class:`~email.parser.Parser` constructor's *strict* argument was added, 191 and its :meth:`~email.parser.Parser.parse` and 192 :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument. 193 The *strict* flag was also added to functions :func:`email.message_from_file` 194 and :func:`email.message_from_string`. 195 196 * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten 197 <email.generator.Generator.flatten>` instead. The 198 :class:`~email.generator.Generator` class has also grown the 199 :meth:`~email.generator.Generator.clone` method. 200 201 * The :class:`~email.generator.DecodedGenerator` class in the 202 :mod:`email.generator` module was added. 203 204 * The intermediate base classes 205 :class:`~email.mime.nonmultipart.MIMENonMultipart` and 206 :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed 207 in the class hierarchy for most of the other MIME-related derived classes. 208 209 * The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor 210 has been deprecated. Encoding now happens implicitly based on the 211 *_charset* argument. 212 213 * The following functions in the :mod:`email.Utils` module have been deprecated: 214 :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following 215 functions have been added to the module: :func:`make_msgid`, 216 :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`. 217 218 * The non-public function :func:`email.Iterators._structure` was added. 219 220 221 Differences from :mod:`mimelib` 222 ------------------------------- 223 224 The :mod:`email` package was originally prototyped as a separate library called 225 `mimelib <http://mimelib.sourceforge.net/>`_. Changes have been made so that method names 226 are more consistent, and some methods or modules have either been added or 227 removed. The semantics of some of the methods have also changed. For the most 228 part, any functionality available in :mod:`mimelib` is still available in the 229 :mod:`email` package, albeit often in a different way. Backward compatibility 230 between the :mod:`mimelib` package and the :mod:`email` package was not a 231 priority. 232 233 Here is a brief description of the differences between the :mod:`mimelib` and 234 the :mod:`email` packages, along with hints on how to port your applications. 235 236 Of course, the most visible difference between the two packages is that the 237 package name has been changed to :mod:`email`. In addition, the top-level 238 package has the following differences: 239 240 * :func:`messageFromString` has been renamed to :func:`message_from_string`. 241 242 * :func:`messageFromFile` has been renamed to :func:`message_from_file`. 243 244 The :class:`~email.message.Message` class has the following differences: 245 246 * The method :meth:`asString` was renamed to 247 :meth:`~email.message.Message.as_string`. 248 249 * The method :meth:`ismultipart` was renamed to 250 :meth:`~email.message.Message.is_multipart`. 251 252 * The :meth:`~email.message.Message.get_payload` method has grown a *decode* 253 optional argument. 254 255 * The method :meth:`getall` was renamed to 256 :meth:`~email.message.Message.get_all`. 257 258 * The method :meth:`addheader` was renamed to 259 :meth:`~email.message.Message.add_header`. 260 261 * The method :meth:`gettype` was renamed to :meth:`get_type`. 262 263 * The method :meth:`getmaintype` was renamed to :meth:`get_main_type`. 264 265 * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`. 266 267 * The method :meth:`getparams` was renamed to 268 :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams` 269 returned a list of strings, :meth:`~email.message.Message.get_params` returns 270 a list of 2-tuples, effectively the key/value pairs of the parameters, split 271 on the ``'='`` sign. 272 273 * The method :meth:`getparam` was renamed to 274 :meth:`~email.message.Message.get_param`. 275 276 * The method :meth:`getcharsets` was renamed to 277 :meth:`~email.message.Message.get_charsets`. 278 279 * The method :meth:`getfilename` was renamed to 280 :meth:`~email.message.Message.get_filename`. 281 282 * The method :meth:`getboundary` was renamed to 283 :meth:`~email.message.Message.get_boundary`. 284 285 * The method :meth:`setboundary` was renamed to 286 :meth:`~email.message.Message.set_boundary`. 287 288 * The method :meth:`getdecodedpayload` was removed. To get similar 289 functionality, pass the value 1 to the *decode* flag of the 290 :meth:`~email.message.Message.get_payload` method. 291 292 * The method :meth:`getpayloadastext` was removed. Similar functionality is 293 supported by the :class:`~email.generator.DecodedGenerator` class in the 294 :mod:`email.generator` module. 295 296 * The method :meth:`getbodyastext` was removed. You can get similar 297 functionality by creating an iterator with 298 :func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators` 299 module. 300 301 The :class:`~email.parser.Parser` class has no differences in its public 302 interface. It does have some additional smarts to recognize 303 :mimetype:`message/delivery-status` type messages, which it represents as a 304 :class:`~email.message.Message` instance containing separate 305 :class:`~email.message.Message` subparts for each header block in the delivery 306 status notification [#]_. 307 308 The :class:`~email.generator.Generator` class has no differences in its public 309 interface. There is a new class in the :mod:`email.generator` module though, 310 called :class:`~email.generator.DecodedGenerator` which provides most of the 311 functionality previously available in the :meth:`Message.getpayloadastext` 312 method. 313 314 The following modules and classes have been changed: 315 316 * The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major* 317 and *_minor* have changed to *_maintype* and *_subtype* respectively. 318 319 * The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor* 320 argument has been renamed to *_subtype*. 321 322 * The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor* 323 argument has been renamed to *_subtype*. 324 325 * The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note 326 that an earlier version of :mod:`mimelib` called this class/module ``RFC822``, 327 but that clashed with the Python standard library module :mod:`rfc822` on some 328 case-insensitive file systems. 329 330 Also, the :class:`~email.mime.message.MIMEMessage` class now represents any 331 kind of MIME message 332 with main type :mimetype:`message`. It takes an optional argument *_subtype* 333 which is used to set the MIME subtype. *_subtype* defaults to 334 :mimetype:`rfc822`. 335 336 :mod:`mimelib` provided some utility functions in its :mod:`address` and 337 :mod:`date` modules. All of these functions have been moved to the 338 :mod:`email.utils` module. 339 340 The ``MsgReader`` class/module has been removed. Its functionality is most 341 closely supported in the :func:`~email.iterators.body_line_iterator` function 342 in the :mod:`email.iterators` module. 343 344 .. rubric:: Footnotes 345 346 .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. 347
