| :mod:`email` --- An email and MIME handling package |
| =================================================== |
| |
| .. module:: email |
| :synopsis: Package supporting the parsing, manipulating, and generating |
| email messages, including MIME documents. |
| .. moduleauthor:: Barry A. Warsaw <barry@python.org> |
| .. sectionauthor:: Barry A. Warsaw <barry@python.org> |
| .. Copyright (C) 2001-2010 Python Software Foundation |
| |
| |
| The :mod:`email` package is a library for managing email messages, including |
| MIME and other :rfc:`2822`\ -based message documents. It is specifically *not* |
| designed to do any sending of email messages to SMTP (:rfc:`2821`), NNTP, or |
| other servers; those are functions of modules such as :mod:`smtplib` and |
| :mod:`nntplib`. The :mod:`email` package attempts to be as RFC-compliant as |
| possible, supporting in addition to :rfc:`2822`, such MIME-related RFCs as |
| :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, and :rfc:`2231`. |
| |
| The primary distinguishing feature of the :mod:`email` package is that it splits |
| the parsing and generating of email messages from the internal *object model* |
| representation of email. Applications using the :mod:`email` package deal |
| primarily with objects; you can add sub-objects to messages, remove sub-objects |
| from messages, completely re-arrange the contents, etc. There is a separate |
| parser and a separate generator which handles the transformation from flat text |
| to the object model, and then back to flat text again. There are also handy |
| subclasses for some common MIME object types, and a few miscellaneous utilities |
| that help with such common tasks as extracting and parsing message field values, |
| creating RFC-compliant dates, etc. |
| |
| The following sections describe the functionality of the :mod:`email` package. |
| The ordering follows a progression that should be common in applications: an |
| email message is read as flat text from a file or other source, the text is |
| parsed to produce the object structure of the email message, this structure is |
| manipulated, and finally, the object tree is rendered back into flat text. |
| |
| It is perfectly feasible to create the object structure out of whole cloth --- |
| i.e. completely from scratch. From there, a similar progression can be taken as |
| above. |
| |
| Also included are detailed specifications of all the classes and modules that |
| the :mod:`email` package provides, the exception classes you might encounter |
| while using the :mod:`email` package, some auxiliary utilities, and a few |
| examples. For users of the older :mod:`mimelib` package, or previous versions |
| of the :mod:`email` package, a section on differences and porting is provided. |
| |
| Contents of the :mod:`email` package documentation: |
| |
| .. toctree:: |
| |
| email.message.rst |
| email.parser.rst |
| email.generator.rst |
| email.policy.rst |
| email.headerregistry.rst |
| email.mime.rst |
| email.header.rst |
| email.charset.rst |
| email.encoders.rst |
| email.errors.rst |
| email.util.rst |
| email.iterators.rst |
| email-examples.rst |
| |
| |
| .. seealso:: |
| |
| Module :mod:`smtplib` |
| SMTP protocol client |
| |
| Module :mod:`nntplib` |
| NNTP protocol client |
| |
| |
| .. _email-pkg-history: |
| |
| Package History |
| --------------- |
| |
| This table describes the release history of the email package, corresponding to |
| the version of Python that the package was released with. For purposes of this |
| document, when you see a note about change or added versions, these refer to the |
| Python version the change was made in, *not* the email package version. This |
| table also describes the Python compatibility of each version of the package. |
| |
| +---------------+------------------------------+-----------------------+ |
| | email version | distributed with | compatible with | |
| +===============+==============================+=======================+ |
| | :const:`1.x` | Python 2.2.0 to Python 2.2.1 | *no longer supported* | |
| +---------------+------------------------------+-----------------------+ |
| | :const:`2.5` | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5 | |
| +---------------+------------------------------+-----------------------+ |
| | :const:`3.0` | Python 2.4 | Python 2.3 to 2.5 | |
| +---------------+------------------------------+-----------------------+ |
| | :const:`4.0` | Python 2.5 | Python 2.3 to 2.5 | |
| +---------------+------------------------------+-----------------------+ |
| | :const:`5.0` | Python 3.0 and Python 3.1 | Python 3.0 to 3.2 | |
| +---------------+------------------------------+-----------------------+ |
| | :const:`5.1` | Python 3.2 | Python 3.0 to 3.2 | |
| +---------------+------------------------------+-----------------------+ |
| |
| Here are the major differences between :mod:`email` version 5.1 and |
| version 5.0: |
| |
| * It is once again possible to parse messages containing non-ASCII bytes, |
| and to reproduce such messages if the data containing the non-ASCII |
| bytes is not modified. |
| |
| * New functions :func:`message_from_bytes` and :func:`message_from_binary_file`, |
| and new classes :class:`~email.parser.BytesFeedParser` and |
| :class:`~email.parser.BytesParser` allow binary message data to be parsed |
| into model objects. |
| |
| * Given bytes input to the model, :meth:`~email.message.Message.get_payload` |
| will by default decode a message body that has a |
| :mailheader:`Content-Transfer-Encoding` of ``8bit`` using the charset |
| specified in the MIME headers and return the resulting string. |
| |
| * Given bytes input to the model, :class:`~email.generator.Generator` will |
| convert message bodies that have a :mailheader:`Content-Transfer-Encoding` of |
| 8bit to instead have a 7bit Content-Transfer-Encoding. |
| |
| * New class :class:`~email.generator.BytesGenerator` produces bytes |
| as output, preserving any unchanged non-ASCII data that was |
| present in the input used to build the model, including message bodies |
| with a :mailheader:`Content-Transfer-Encoding` of 8bit. |
| |
| Here are the major differences between :mod:`email` version 5.0 and version 4: |
| |
| * All operations are on unicode strings. Text inputs must be strings, |
| text outputs are strings. Outputs are limited to the ASCII character |
| set and so can be encoded to ASCII for transmission. Inputs are also |
| limited to ASCII; this is an acknowledged limitation of email 5.0 and |
| means it can only be used to parse email that is 7bit clean. |
| |
| Here are the major differences between :mod:`email` version 4 and version 3: |
| |
| * All modules have been renamed according to :pep:`8` standards. For example, |
| the version 3 module :mod:`email.Message` was renamed to :mod:`email.message` in |
| version 4. |
| |
| * A new subpackage :mod:`email.mime` was added and all the version 3 |
| :mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mime` |
| subpackage. For example, the version 3 module :mod:`email.MIMEText` was renamed |
| to :mod:`email.mime.text`. |
| |
| *Note that the version 3 names will continue to work until Python 2.6*. |
| |
| * The :mod:`email.mime.application` module was added, which contains the |
| :class:`~email.mime.application.MIMEApplication` class. |
| |
| * Methods that were deprecated in version 3 have been removed. These include |
| :meth:`Generator.__call__`, :meth:`Message.get_type`, |
| :meth:`Message.get_main_type`, :meth:`Message.get_subtype`. |
| |
| * Fixes have been added for :rfc:`2231` support which can change some of the |
| return types for :func:`Message.get_param <email.message.Message.get_param>` |
| and friends. Under some |
| circumstances, values which used to return a 3-tuple now return simple strings |
| (specifically, if all extended parameter segments were unencoded, there is no |
| language and charset designation expected, so the return type is now a simple |
| string). Also, %-decoding used to be done for both encoded and unencoded |
| segments; this decoding is now done only for encoded segments. |
| |
| Here are the major differences between :mod:`email` version 3 and version 2: |
| |
| * The :class:`~email.parser.FeedParser` class was introduced, and the |
| :class:`~email.parser.Parser` class was implemented in terms of the |
| :class:`~email.parser.FeedParser`. All parsing therefore is |
| non-strict, and parsing will make a best effort never to raise an exception. |
| Problems found while parsing messages are stored in the message's *defect* |
| attribute. |
| |
| * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2 |
| have been removed. These include the *_encoder* argument to the |
| :class:`~email.mime.text.MIMEText` constructor, the |
| :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair` |
| function, and the functions :func:`Utils.decode` and :func:`Utils.encode`. |
| |
| * New :exc:`DeprecationWarning`\ s have been added to: |
| :meth:`Generator.__call__`, :meth:`Message.get_type`, |
| :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict* |
| argument to the :class:`~email.parser.Parser` class. These are expected to |
| be removed in future versions. |
| |
| * Support for Pythons earlier than 2.3 has been removed. |
| |
| Here are the differences between :mod:`email` version 2 and version 1: |
| |
| * The :mod:`email.Header` and :mod:`email.Charset` modules have been added. |
| |
| * The pickle format for :class:`~email.message.Message` instances has changed. |
| Since this was never (and still isn't) formally defined, this isn't |
| considered a backward incompatibility. However if your application pickles |
| and unpickles :class:`~email.message.Message` instances, be aware that in |
| :mod:`email` version 2, :class:`~email.message.Message` instances now have |
| private variables *_charset* and *_default_type*. |
| |
| * Several methods in the :class:`~email.message.Message` class have been |
| deprecated, or their signatures changed. Also, many new methods have been |
| added. See the documentation for the :class:`~email.message.Message` class |
| for details. The changes should be completely backward compatible. |
| |
| * The object structure has changed in the face of :mimetype:`message/rfc822` |
| content types. In :mod:`email` version 1, such a type would be represented |
| by a scalar payload, i.e. the container message's |
| :meth:`~email.message.Message.is_multipart` returned false, |
| :meth:`~email.message.Message.get_payload` was not a list object, but a |
| single :class:`~email.message.Message` instance. |
| |
| This structure was inconsistent with the rest of the package, so the object |
| representation for :mimetype:`message/rfc822` content types was changed. In |
| :mod:`email` version 2, the container *does* return ``True`` from |
| :meth:`~email.message.Message.is_multipart`, and |
| :meth:`~email.message.Message.get_payload` returns a list containing a single |
| :class:`~email.message.Message` item. |
| |
| Note that this is one place that backward compatibility could not be |
| completely maintained. However, if you're already testing the return type of |
| :meth:`~email.message.Message.get_payload`, you should be fine. You just need |
| to make sure your code doesn't do a :meth:`~email.message.Message.set_payload` |
| with a :class:`~email.message.Message` instance on a container with a content |
| type of :mimetype:`message/rfc822`. |
| |
| * The :class:`~email.parser.Parser` constructor's *strict* argument was added, |
| and its :meth:`~email.parser.Parser.parse` and |
| :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument. |
| The *strict* flag was also added to functions :func:`email.message_from_file` |
| and :func:`email.message_from_string`. |
| |
| * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten |
| <email.generator.Generator.flatten>` instead. The |
| :class:`~email.generator.Generator` class has also grown the |
| :meth:`~email.generator.Generator.clone` method. |
| |
| * The :class:`~email.generator.DecodedGenerator` class in the |
| :mod:`email.generator` module was added. |
| |
| * The intermediate base classes |
| :class:`~email.mime.nonmultipart.MIMENonMultipart` and |
| :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed |
| in the class hierarchy for most of the other MIME-related derived classes. |
| |
| * The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor |
| has been deprecated. Encoding now happens implicitly based on the |
| *_charset* argument. |
| |
| * The following functions in the :mod:`email.Utils` module have been deprecated: |
| :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following |
| functions have been added to the module: :func:`make_msgid`, |
| :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`. |
| |
| * The non-public function :func:`email.Iterators._structure` was added. |
| |
| |
| Differences from :mod:`mimelib` |
| ------------------------------- |
| |
| The :mod:`email` package was originally prototyped as a separate library called |
| `mimelib <http://mimelib.sf.net/>`_. Changes have been made so that method names |
| are more consistent, and some methods or modules have either been added or |
| removed. The semantics of some of the methods have also changed. For the most |
| part, any functionality available in :mod:`mimelib` is still available in the |
| :mod:`email` package, albeit often in a different way. Backward compatibility |
| between the :mod:`mimelib` package and the :mod:`email` package was not a |
| priority. |
| |
| Here is a brief description of the differences between the :mod:`mimelib` and |
| the :mod:`email` packages, along with hints on how to port your applications. |
| |
| Of course, the most visible difference between the two packages is that the |
| package name has been changed to :mod:`email`. In addition, the top-level |
| package has the following differences: |
| |
| * :func:`messageFromString` has been renamed to :func:`message_from_string`. |
| |
| * :func:`messageFromFile` has been renamed to :func:`message_from_file`. |
| |
| The :class:`~email.message.Message` class has the following differences: |
| |
| * The method :meth:`asString` was renamed to |
| :meth:`~email.message.Message.as_string`. |
| |
| * The method :meth:`ismultipart` was renamed to |
| :meth:`~email.message.Message.is_multipart`. |
| |
| * The :meth:`~email.message.Message.get_payload` method has grown a *decode* |
| optional argument. |
| |
| * The method :meth:`getall` was renamed to |
| :meth:`~email.message.Message.get_all`. |
| |
| * The method :meth:`addheader` was renamed to |
| :meth:`~email.message.Message.add_header`. |
| |
| * The method :meth:`gettype` was renamed to :meth:`get_type`. |
| |
| * The method :meth:`getmaintype` was renamed to :meth:`get_main_type`. |
| |
| * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`. |
| |
| * The method :meth:`getparams` was renamed to |
| :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams` |
| returned a list of strings, :meth:`~email.message.Message.get_params` returns |
| a list of 2-tuples, effectively the key/value pairs of the parameters, split |
| on the ``'='`` sign. |
| |
| * The method :meth:`getparam` was renamed to |
| :meth:`~email.message.Message.get_param`. |
| |
| * The method :meth:`getcharsets` was renamed to |
| :meth:`~email.message.Message.get_charsets`. |
| |
| * The method :meth:`getfilename` was renamed to |
| :meth:`~email.message.Message.get_filename`. |
| |
| * The method :meth:`getboundary` was renamed to |
| :meth:`~email.message.Message.get_boundary`. |
| |
| * The method :meth:`setboundary` was renamed to |
| :meth:`~email.message.Message.set_boundary`. |
| |
| * The method :meth:`getdecodedpayload` was removed. To get similar |
| functionality, pass the value 1 to the *decode* flag of the |
| :meth:`~email.message.Message.get_payload` method. |
| |
| * The method :meth:`getpayloadastext` was removed. Similar functionality is |
| supported by the :class:`~email.generator.DecodedGenerator` class in the |
| :mod:`email.generator` module. |
| |
| * The method :meth:`getbodyastext` was removed. You can get similar |
| functionality by creating an iterator with |
| :func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators` |
| module. |
| |
| The :class:`~email.parser.Parser` class has no differences in its public |
| interface. It does have some additional smarts to recognize |
| :mimetype:`message/delivery-status` type messages, which it represents as a |
| :class:`~email.message.Message` instance containing separate |
| :class:`~email.message.Message` subparts for each header block in the delivery |
| status notification [#]_. |
| |
| The :class:`~email.generator.Generator` class has no differences in its public |
| interface. There is a new class in the :mod:`email.generator` module though, |
| called :class:`~email.generator.DecodedGenerator` which provides most of the |
| functionality previously available in the :meth:`Message.getpayloadastext` |
| method. |
| |
| The following modules and classes have been changed: |
| |
| * The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major* |
| and *_minor* have changed to *_maintype* and *_subtype* respectively. |
| |
| * The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor* |
| argument has been renamed to *_subtype*. |
| |
| * The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor* |
| argument has been renamed to *_subtype*. |
| |
| * The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note |
| that an earlier version of :mod:`mimelib` called this class/module ``RFC822``, |
| but that clashed with the Python standard library module :mod:`rfc822` on some |
| case-insensitive file systems. |
| |
| Also, the :class:`~email.mime.message.MIMEMessage` class now represents any |
| kind of MIME message |
| with main type :mimetype:`message`. It takes an optional argument *_subtype* |
| which is used to set the MIME subtype. *_subtype* defaults to |
| :mimetype:`rfc822`. |
| |
| :mod:`mimelib` provided some utility functions in its :mod:`address` and |
| :mod:`date` modules. All of these functions have been moved to the |
| :mod:`email.utils` module. |
| |
| The ``MsgReader`` class/module has been removed. Its functionality is most |
| closely supported in the :func:`~email.iterators.body_line_iterator` function |
| in the :mod:`email.iterators` module. |
| |
| .. rubric:: Footnotes |
| |
| .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. |