Move the 3k reST doc tree in place.

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`.