diff options
Diffstat (limited to 'Doc/library/email.rst')
| -rw-r--r-- | Doc/library/email.rst | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/Doc/library/email.rst b/Doc/library/email.rst new file mode 100644 index 0000000..212c321 --- /dev/null +++ b/Doc/library/email.rst @@ -0,0 +1,324 @@ +.. % Copyright (C) 2001-2007 Python Software Foundation +.. % Author: barry@python.org (Barry Warsaw) + + +: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> + + +.. versionadded:: 2.2 + +The :mod:`email` package is a library for managing email messages, including +MIME and other :rfc:`2822`\ -based message documents. It subsumes most of the +functionality in several older standard modules such as :mod:`rfc822`, +:mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as +:mod:`mimecntl`. 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.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 | ++---------------+------------------------------+-----------------------+ + +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:`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` 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:`FeedParser` class was introduced, and the :class:`Parser` class + was implemented in terms of the :class:`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:`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:`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:`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:`Message` instances, be aware that in :mod:`email` version 2, + :class:`Message` instances now have private variables *_charset* and + *_default_type*. + +* Several methods in the :class:`Message` class have been deprecated, or their + signatures changed. Also, many new methods have been added. See the + documentation for the :class:`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:`is_multipart` returned + false, :meth:`get_payload` was not a list object, but a single :class:`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:`is_multipart`, and :meth:`get_payload` returns a list containing a single + :class:`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:`get_payload`, you should be fine. You just need to make sure your code + doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container + with a content type of :mimetype:`message/rfc822`. + +* The :class:`Parser` constructor's *strict* argument was added, and its + :meth:`parse` and :meth:`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` + instead. The :class:`Generator` class has also grown the :meth:`clone` method. + +* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was + added. + +* The intermediate base classes :class:`MIMENonMultipart` and + :class:`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:`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:`Message` class has the following differences: + +* The method :meth:`asString` was renamed to :meth:`as_string`. + +* The method :meth:`ismultipart` was renamed to :meth:`is_multipart`. + +* The :meth:`get_payload` method has grown a *decode* optional argument. + +* The method :meth:`getall` was renamed to :meth:`get_all`. + +* The method :meth:`addheader` was renamed to :meth:`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:`get_params`. Also, whereas + :meth:`getparams` returned a list of strings, :meth:`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:`get_param`. + +* The method :meth:`getcharsets` was renamed to :meth:`get_charsets`. + +* The method :meth:`getfilename` was renamed to :meth:`get_filename`. + +* The method :meth:`getboundary` was renamed to :meth:`get_boundary`. + +* The method :meth:`setboundary` was renamed to :meth:`set_boundary`. + +* The method :meth:`getdecodedpayload` was removed. To get similar + functionality, pass the value 1 to the *decode* flag of the get_payload() + method. + +* The method :meth:`getpayloadastext` was removed. Similar functionality is + supported by the :class:`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:`typed_subpart_iterator` in the + :mod:`email.iterators` module. + +The :class:`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:`Message` instance containing +separate :class:`Message` subparts for each header block in the delivery status +notification [#]_. + +The :class:`Generator` class has no differences in its public interface. There +is a new class in the :mod:`email.generator` module though, called +:class:`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:`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:`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:`body_line_iterator` function in the +:mod:`email.iterators` module. + +.. rubric:: Footnotes + +.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. |