diff options
Diffstat (limited to 'Doc/library/email.rst')
| -rw-r--r-- | Doc/library/email.rst | 464 |
1 files changed, 113 insertions, 351 deletions
diff --git a/Doc/library/email.rst b/Doc/library/email.rst index e8bb02bff5..c4187dd009 100644 --- a/Doc/library/email.rst +++ b/Doc/library/email.rst @@ -3,50 +3,104 @@ .. 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 + email messages. +.. moduleauthor:: Barry A. Warsaw <barry@python.org>, + R. David Murray <rdmurray@bitdance.com> +.. sectionauthor:: R. David Murray <rdmurray@bitdance.com> **Source code:** :source:`Lib/email/__init__.py` -------------- -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 :mod:`email` package is a library for managing email messages. 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 :rfc:`5233` and :rfc:`6532`, as well as +such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`, +and :rfc:`2231`. + +The overall structure of the email package can be divided into three major +components, plus a fourth component that controls the behavior of the other +components. + +The central component of the package is an "object model" that represents email +messages. An application interacts with the package primarily through the +object model interface defined in the :mod:`~email.message` sub-module. The +application can use this API to ask questions about an existing email, to +construct a new email, or to add or remove email subcomponents that themselves +use the same object model interface. That is, following the nature of email +messages and their MIME subcomponents, the email object model is a tree +structure of objects that all provide the :class:`~email.message.EmailMessage` +API. + +The other two major components of the package are the :mod:`~email.parser` and +the :mod:`~email.generator`. The parser takes the serialized version of an +email message (a stream of bytes) and converts it into a tree of +:class:`~email.message.EmailMessage` objects. The generator takes an +:class:`~email.message.EmailMessage` and turns it back into a serialized byte +stream. (The parser and generator also handle streams of text characters, but +this usage is discouraged as it is too easy to end up with messages that are +not valid in one way or another.) + +The control component is the :mod:`~email.policy` module. Every +:class:`~email.message.EmailMessage`, every :mod:`~email.generator`, and every +:mod:`~email.parser` has an associated :mod:`~email.policy` object that +controls its behavior. Usually an application only needs to specify the policy +when an :class:`~email.message.EmailMessage` is created, either by directly +instantiating an :class:`~email.message.EmailMessage` to create a new email, +or by parsing an input stream using a :mod:`~email.parser`. But the policy can +be changed when the message is serialized using a :mod:`~email.generator`. +This allows, for example, a generic email message to be parsed from disk, but +to serialize it using standard SMTP settings when sending it to an email +server. + +The email package does its best to hide the details of the various governing +RFCs from the application. Conceptually the application should be able to +treat the email message as a structured tree of unicode text and binary +attachments, without having to worry about how these are represented when +serialized. In practice, however, it is often necessary to be aware of at +least some of the rules governing MIME messages and their structure, +specifically the names and nature of the MIME "content types" and how they +identify multipart documents. For the most part this knowledge should only be +required for more complex applications, and even then it should only be the +high level structure in question, and not the details of how those structures +are represented. Since MIME content types are used widely in modern internet +software (not just email), this will be a familiar concept to many programmers. 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. +We start with the :mod:`~email.message` object model, which is the primary +interface an application will use, and follow that with the +:mod:`~email.parser` and :mod:`~email.generator` components. Then we cover the +:mod:`~email.policy` controls, which completes the treatment of the main +components of the library. + +The next three sections cover the exceptions the package may raise and the +defects (non-compliance with the RFCs) that the :mod:`~email.parser` may +detect. Then we cover the :mod:`~email.headerregistry` and the +:mod:`~email.contentmanager` sub-components, which provide tools for doing more +detailed manipulation of headers and payloads, respectively. Both of these +components contain features relevant to consuming and producing non-trivial +messages, but also document their extensibility APIs, which will be of interest +to advanced applications. + +Following those is a set of examples of using the fundamental parts of the APIs +covered in the preceding sections. + +The forgoing represent the modern (unicode friendly) API of the email package. +The remaining sections, starting with the :class:`~email.message.Message` +class, cover the legacy :data:`~email.policy.compat32` API that deals much more +directly with the details of how email messages are represented. The +:data:`~email.policy.compat32` API does *not* hide the details of the RFCs from +the application, but for applications that need to operate at that level, they +can be useful tools. This documentation is also relevant for applications that +are still using the :mod:`~email.policy.compat32` API for backward +compatibility reasons. + +.. versionchanged:: 3.6 + Docs reorganized and rewritten to promote the new + :class:`~email.message.EmailMessage`/:class:`~email.policy.EmailPolicy` + API. Contents of the :mod:`email` package documentation: @@ -56,335 +110,43 @@ Contents of the :mod:`email` package documentation: email.parser.rst email.generator.rst email.policy.rst + + email.errors.rst email.headerregistry.rst email.contentmanager.rst + + email.examples.rst + +Legacy API: + +.. toctree:: + + email.compat32-message.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 and Python 2.5 | Python 2.3 to 2.6 | -+---------------+------------------------------+-----------------------+ -| :const:`4.0` | Python 2.5 to Python 2.7 | Python 2.3 to 2.7 | -+---------------+------------------------------+-----------------------+ -| :const:`5.0` | Python 3.0 and Python 3.1 | Python 3.0 to 3.2 | -+---------------+------------------------------+-----------------------+ -| :const:`5.1` | Python 3.2 | Python 3.2 | -+---------------+------------------------------+-----------------------+ - -After Version 5.1 (Python 3.2), the email package no longer has a version that -is separate from the Python version. (See the :ref:`whatsnew-index` documents -for the respective Python versions for details on changes.) - -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. + SMTP (Simple Mail Transport Protcol) client -* 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. + Module :mod:`poplib` + POP (Post Office Protocol) client - 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. + Module :mod:`imaplib` + IMAP (Internet Message Access Protocol) client - 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.sourceforge.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. + Module :mod:`nntplib` + NNTP (Net News Transport Protocol) client -.. rubric:: Footnotes + Module :mod:`mailbox` + Tools for creating, reading, and managing collections of messages on disk + using a variety standard formats. -.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. + Module :mod:`smtpd` + SMTP server framework (primarily useful for testing) |