Merge email package 4.0 from the sandbox, including documentation, test cases,

and NEWS updates.

16 files changed, 260 insertions, 267 deletions

diff --git a/Doc/lib/email-dir.py b/Doc/lib/email-dir.py
index 2d89a2f..c04f57d 100644
--- a/Doc/lib/email-dir.py
+++ b/Doc/lib/email-dir.py
@@ -1,83 +1,69 @@
 #!/usr/bin/env python
 
-"""Send the contents of a directory as a MIME message.
+"""Send the contents of a directory as a MIME message."""
 
-Usage: dirmail [options] from to [to ...]*
-
-Options:
-    -h / --help
-        Print this message and exit.
-
-    -d directory
-    --directory=directory
-        Mail the contents of the specified directory, otherwise use the
-        current directory.  Only the regular files in the directory are sent,
-        and we don't recurse to subdirectories.
-
-`from' is the email address of the sender of the message.
-
-`to' is the email address of the recipient of the message, and multiple
-recipients may be given.
-
-The email is sent by forwarding to your local SMTP server, which then does the
-normal delivery process.  Your local machine must be running an SMTP server.
-"""
-
-import sys
 import os
-import getopt
+import sys
 import smtplib
 # For guessing MIME type based on file name extension
 import mimetypes
 
-from email import Encoders
-from email.Message import Message
-from email.MIMEAudio import MIMEAudio
-from email.MIMEBase import MIMEBase
-from email.MIMEMultipart import MIMEMultipart
-from email.MIMEImage import MIMEImage
-from email.MIMEText import MIMEText
-
-COMMASPACE = ', '
+from optparse import OptionParser
 
+from email import encoders
+from email.message import Message
+from email.mime.audio import MIMEAudio
+from email.mime.base import MIMEBase
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
 
-def usage(code, msg=''):
-    print >> sys.stderr, __doc__
-    if msg:
-        print >> sys.stderr, msg
-    sys.exit(code)
+COMMASPACE = ', '
 
 
 def main():
-    try:
-        opts, args = getopt.getopt(sys.argv[1:], 'hd:', ['help', 'directory='])
-    except getopt.error, msg:
-        usage(1, msg)
-
-    dir = os.curdir
-    for opt, arg in opts:
-        if opt in ('-h', '--help'):
-            usage(0)
-        elif opt in ('-d', '--directory'):
-            dir = arg
-
-    if len(args) < 2:
-        usage(1)
-
-    sender = args[0]
-    recips = args[1:]
-
+    parser = OptionParser(usage="""\
+Send the contents of a directory as a MIME message.
+
+Usage: %prog [options]
+
+Unless the -o option is given, the email is sent by forwarding to your local
+SMTP server, which then does the normal delivery process.  Your local machine
+must be running an SMTP server.
+""")
+    parser.add_option('-d', '--directory',
+                      type='string', action='store',
+                      help="""Mail the contents of the specified directory,
+                      otherwise use the current directory.  Only the regular
+                      files in the directory are sent, and we don't recurse to
+                      subdirectories.""")
+    parser.add_option('-o', '--output',
+                      type='string', action='store', metavar='FILE',
+                      help="""Print the composed message to FILE instead of
+                      sending the message to the SMTP server.""")
+    parser.add_option('-s', '--sender',
+                      type='string', action='store', metavar='SENDER',
+                      help='The value of the From: header (required)')
+    parser.add_option('-r', '--recipient',
+                      type='string', action='append', metavar='RECIPIENT',
+                      default=[], dest='recipients',
+                      help='A To: header value (at least one required)')
+    opts, args = parser.parse_args()
+    if not opts.sender or not opts.recipients:
+        parser.print_help()
+        sys.exit(1)
+    directory = opts.directory
+    if not directory:
+        directory = '.'
     # Create the enclosing (outer) message
     outer = MIMEMultipart()
-    outer['Subject'] = 'Contents of directory %s' % os.path.abspath(dir)
-    outer['To'] = COMMASPACE.join(recips)
-    outer['From'] = sender
+    outer['Subject'] = 'Contents of directory %s' % os.path.abspath(directory)
+    outer['To'] = COMMASPACE.join(opts.recipients)
+    outer['From'] = opts.sender
     outer.preamble = 'You will not see this in a MIME-aware mail reader.\n'
-    # To guarantee the message ends with a newline
-    outer.epilogue = ''
 
-    for filename in os.listdir(dir):
-        path = os.path.join(dir, filename)
+    for filename in os.listdir(directory):
+        path = os.path.join(directory, filename)
         if not os.path.isfile(path):
             continue
         # Guess the content type based on the file's extension.  Encoding
@@ -108,16 +94,21 @@ def main():
             msg.set_payload(fp.read())
             fp.close()
             # Encode the payload using Base64
-            Encoders.encode_base64(msg)
+            encoders.encode_base64(msg)
         # Set the filename parameter
         msg.add_header('Content-Disposition', 'attachment', filename=filename)
         outer.attach(msg)
-
-    # Now send the message
-    s = smtplib.SMTP()
-    s.connect()
-    s.sendmail(sender, recips, outer.as_string())
-    s.close()
+    # Now send or store the message
+    composed = outer.as_string()
+    if opts.output:
+        fp = open(opts.output, 'w')
+        fp.write(composed)
+        fp.close()
+    else:
+        s = smtplib.SMTP()
+        s.connect()
+        s.sendmail(opts.sender, opts.recipients, composed)
+        s.close()
 
 
 if __name__ == '__main__':
diff --git a/Doc/lib/email-mime.py b/Doc/lib/email-mime.py
index 048a59f..5097253 100644
--- a/Doc/lib/email-mime.py
+++ b/Doc/lib/email-mime.py
@@ -2,8 +2,8 @@
 import smtplib
 
 # Here are the email package modules we'll need
-from email.MIMEImage import MIMEImage
-from email.MIMEMultipart import MIMEMultipart
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
 
 COMMASPACE = ', '
 
@@ -15,8 +15,6 @@ msg['Subject'] = 'Our family reunion'
 msg['From'] = me
 msg['To'] = COMMASPACE.join(family)
 msg.preamble = 'Our family reunion'
-# Guarantees the message ends in a newline
-msg.epilogue = ''
 
 # Assume we know that the image files are all in PNG format
 for file in pngfiles:
diff --git a/Doc/lib/email-simple.py b/Doc/lib/email-simple.py
index a445f1b..44152a4 100644
--- a/Doc/lib/email-simple.py
+++ b/Doc/lib/email-simple.py
@@ -2,7 +2,7 @@
 import smtplib
 
 # Import the email modules we'll need
-from email.MIMEText import MIMEText
+from email.mime.text import MIMEText
 
 # Open a plain text file for reading.  For this example, assume that
 # the text file contains only ASCII characters.
diff --git a/Doc/lib/email-unpack.py b/Doc/lib/email-unpack.py
index b166fdb..fc05d99 100644
--- a/Doc/lib/email-unpack.py
+++ b/Doc/lib/email-unpack.py
@@ -1,59 +1,44 @@
 #!/usr/bin/env python
 
-"""Unpack a MIME message into a directory of files.
+"""Unpack a MIME message into a directory of files."""
 
-Usage: unpackmail [options] msgfile
-
-Options:
-    -h / --help
-        Print this message and exit.
-
-    -d directory
-    --directory=directory
-        Unpack the MIME message into the named directory, which will be
-        created if it doesn't already exist.
-
-msgfile is the path to the file containing the MIME message.
-"""
-
-import sys
 import os
-import getopt
+import sys
+import email
 import errno
 import mimetypes
-import email
-
 
-def usage(code, msg=''):
-    print >> sys.stderr, __doc__
-    if msg:
-        print >> sys.stderr, msg
-    sys.exit(code)
+from optparse import OptionParser
 
 
 def main():
-    try:
-        opts, args = getopt.getopt(sys.argv[1:], 'hd:', ['help', 'directory='])
-    except getopt.error, msg:
-        usage(1, msg)
-
-    dir = os.curdir
-    for opt, arg in opts:
-        if opt in ('-h', '--help'):
-            usage(0)
-        elif opt in ('-d', '--directory'):
-            dir = arg
+    parser = OptionParser(usage="""\
+Unpack a MIME message into a directory of files.
+
+Usage: %prog [options] msgfile
+""")
+    parser.add_option('-d', '--directory',
+                      type='string', action='store',
+                      help="""Unpack the MIME message into the named
+                      directory, which will be created if it doesn't already
+                      exist.""")
+    opts, args = parser.parse_args()
+    if not opts.directory:
+        parser.print_help()
+        sys.exit(1)
 
     try:
         msgfile = args[0]
     except IndexError:
-        usage(1)
+        parser.print_help()
+        sys.exit(1)
 
     try:
-        os.mkdir(dir)
+        os.mkdir(opts.directory)
     except OSError, e:
         # Ignore directory exists error
-        if e.errno <> errno.EEXIST: raise
+        if e.errno <> errno.EEXIST:
+            raise
 
     fp = open(msgfile)
     msg = email.message_from_file(fp)
@@ -74,8 +59,8 @@ def main():
                 ext = '.bin'
             filename = 'part-%03d%s' % (counter, ext)
         counter += 1
-        fp = open(os.path.join(dir, filename), 'wb')
-        fp.write(part.get_payload(decode=1))
+        fp = open(os.path.join(opts.directory, filename), 'wb')
+        fp.write(part.get_payload(decode=True))
         fp.close()
 
 
diff --git a/Doc/lib/email.tex b/Doc/lib/email.tex
index 3a90e22..6853325 100644
--- a/Doc/lib/email.tex
+++ b/Doc/lib/email.tex
@@ -1,4 +1,4 @@
-% Copyright (C) 2001-2004 Python Software Foundation
+% Copyright (C) 2001-2006 Python Software Foundation
 % Author: barry@python.org (Barry Warsaw)
 
 \section{\module{email} ---
@@ -18,10 +18,10 @@ subsumes most of the functionality in several older standard modules
 such as \refmodule{rfc822}, \refmodule{mimetools},
 \refmodule{multifile}, and other non-standard packages such as
 \module{mimecntl}.  It is specifically \emph{not} designed to do any
-sending of email messages to SMTP (\rfc{2821}) servers; that is the
-function of the \refmodule{smtplib} module.  The \module{email}
-package attempts to be as RFC-compliant as possible, supporting in
-addition to \rfc{2822}, such MIME-related RFCs as
+sending of email messages to SMTP (\rfc{2821}), NNTP, or other servers; those
+are functions of modules such as \refmodule{smtplib} and \refmodule{nntplib}.
+The \module{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 \module{email} package is
@@ -41,7 +41,7 @@ The following sections describe the functionality of the
 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 rendered back into flat text.
+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
@@ -56,6 +56,7 @@ package, a section on differences and porting is provided.
 
 \begin{seealso}
     \seemodule{smtplib}{SMTP protocol client}
+    \seemodule{nntplib}{NNTP protocol client}
 \end{seealso}
 
 \subsection{Representing an email message}
@@ -88,22 +89,51 @@ package, a section on differences and porting is provided.
 \subsection{Iterators}
 \input{emailiter}
 
-\subsection{Package History}
+\subsection{Package History\label{email-pkg-history}}
 
-Version 1 of the \module{email} package was bundled with Python
-releases up to Python 2.2.1.  Version 2 was developed for the Python
-2.3 release, and backported to Python 2.2.2.  It was also available as
-a separate distutils-based package, and is compatible back to Python 2.1.
+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 it, \emph{not} the email package
+version.  This table also describes the Python compatibility of each version
+of the package.
 
-\module{email} version 3.0 was released with Python 2.4 and as a separate
-distutils-based package.  It is compatible back to Python 2.3.
+\begin{tableiii}{l|l|l}{constant}{email version}{distributed with}{compatible with}
+\lineiii{1.x}{Python 2.2.0 to Python 2.2.1}{\emph{no longer supported}}
+\lineiii{2.5}{Python 2.2.2+ and Python 2.3}{Python 2.1 to 2.5}
+\lineiii{3.0}{Python 2.4}{Python 2.3 to 2.5}
+\lineiii{4.0}{Python 2.5}{Python 2.3 to 2.5}
+\end{tableiii}
 
-Here are the differences between \module{email} version 3 and version 2:
+Here are the major differences between \module{email} verson 4 and version 3:
+
+\begin{itemize}
+\item All modules have been renamed according to \pep{8} standards.  For
+      example, the version 3 module \module{email.Message} was renamed to
+      \module{email.message} in version 4.
+
+\item A new subpackage \module{email.mime} was added and all the version 3
+      \module{email.MIME*} modules were renamed and situated into the
+      \module{email.mime} subpackage.  For example, the version 3 module
+      \module{email.MIMEText} was renamed to \module{email.mime.text}.
+
+      \emph{Note that the version 3 names will continue to work until Python
+      2.6}.
+
+\item The \module{email.mime.application} module was added, which contains the
+      \class{MIMEApplication} class.
+
+\item Methods that were deprecated in version 3 have been removed.  These
+      include \method{Generator.__call__()}, \method{Message.get_type()},
+      \method{Message.get_main_type()}, \method{Message.get_subtype()}.
+\end{itemize}
+
+Here are the major differences between \module{email} version 3 and version 2:
 
 \begin{itemize}
 \item The \class{FeedParser} class was introduced, and the \class{Parser}
       class was implemented in terms of the \class{FeedParser}.  All parsing
-      there for is non-strict, and parsing will make a best effort never to
+      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 \var{defect} attribute.
 
@@ -117,7 +147,7 @@ Here are the differences between \module{email} version 3 and version 2:
       \method{Generator.__call__()}, \method{Message.get_type()},
       \method{Message.get_main_type()}, \method{Message.get_subtype()}, and
       the \var{strict} argument to the \class{Parser} class.  These are
-      expected to be removed in email 3.1.
+      expected to be removed in future versions.
 
 \item Support for Pythons earlier than 2.3 has been removed.
 \end{itemize}
@@ -278,12 +308,12 @@ The \class{Message} class has the following differences:
 \item The method \method{getpayloadastext()} was removed.  Similar
       functionality
       is supported by the \class{DecodedGenerator} class in the
-      \refmodule{email.Generator} module.
+      \refmodule{email.generator} module.
 
 \item The method \method{getbodyastext()} was removed.  You can get
       similar functionality by creating an iterator with
       \function{typed_subpart_iterator()} in the
-      \refmodule{email.Iterators} module.
+      \refmodule{email.iterators} module.
 \end{itemize}
 
 The \class{Parser} class has no differences in its public interface.
@@ -295,7 +325,7 @@ notification\footnote{Delivery Status Notifications (DSN) are defined
 in \rfc{1894}.}.
 
 The \class{Generator} class has no differences in its public
-interface.  There is a new class in the \refmodule{email.Generator}
+interface.  There is a new class in the \refmodule{email.generator}
 module though, called \class{DecodedGenerator} which provides most of
 the functionality previously available in the
 \method{Message.getpayloadastext()} method.
@@ -329,11 +359,11 @@ The following modules and classes have been changed:
 
 \module{mimelib} provided some utility functions in its
 \module{address} and \module{date} modules.  All of these functions
-have been moved to the \refmodule{email.Utils} module.
+have been moved to the \refmodule{email.utils} module.
 
 The \code{MsgReader} class/module has been removed.  Its functionality
 is most closely supported in the \function{body_line_iterator()}
-function in the \refmodule{email.Iterators} module.
+function in the \refmodule{email.iterators} module.
 
 \subsection{Examples}
 
diff --git a/Doc/lib/emailcharsets.tex b/Doc/lib/emailcharsets.tex
index 18f2a01..e0be68a 100644
--- a/Doc/lib/emailcharsets.tex
+++ b/Doc/lib/emailcharsets.tex
@@ -1,4 +1,4 @@
-\declaremodule{standard}{email.Charset}
+\declaremodule{standard}{email.charset}
 \modulesynopsis{Character Sets}
 
 This module provides a class \class{Charset} for representing
@@ -7,6 +7,8 @@ well as a character set registry and several convenience methods for
 manipulating this registry.  Instances of \class{Charset} are used in
 several other modules within the \module{email} package.
 
+Import this class from the \module{email.charset} module.
+
 \versionadded{2.2.2}
 
 \begin{classdesc}{Charset}{\optional{input_charset}}
@@ -153,7 +155,7 @@ input charset to the output charset automatically.  This is not useful
 for multibyte character sets, which have line length issues (multibyte
 characters must be split on a character, not a byte boundary); use the
 higher-level \class{Header} class to deal with these issues (see
-\refmodule{email.Header}).  \var{convert} defaults to \code{False}.
+\refmodule{email.header}).  \var{convert} defaults to \code{False}.
 
 The type of encoding (base64 or quoted-printable) will be based on
 the \var{header_encoding} attribute.
@@ -188,7 +190,7 @@ This method allows you to compare two \class{Charset} instances for equality.
 This method allows you to compare two \class{Charset} instances for inequality.
 \end{methoddesc}
 
-The \module{email.Charset} module also provides the following
+The \module{email.charset} module also provides the following
 functions for adding new entries to the global character set, alias,
 and codec registries:
 
diff --git a/Doc/lib/emailencoders.tex b/Doc/lib/emailencoders.tex
index a49e04d..3d05c2a 100644
--- a/Doc/lib/emailencoders.tex
+++ b/Doc/lib/emailencoders.tex
@@ -1,4 +1,4 @@
-\declaremodule{standard}{email.Encoders}
+\declaremodule{standard}{email.encoders}
 \modulesynopsis{Encoders for email message payloads.}
 
 When creating \class{Message} objects from scratch, you often need to
@@ -7,7 +7,7 @@ This is especially true for \mimetype{image/*} and \mimetype{text/*}
 type messages containing binary data.
 
 The \module{email} package provides some convenient encodings in its
-\module{Encoders} module.  These encoders are actually used by the
+\module{encoders} module.  These encoders are actually used by the
 \class{MIMEAudio} and \class{MIMEImage} class constructors to provide default
 encodings.  All encoder functions take exactly one argument, the message
 object to encode.  They usually extract the payload, encode it, and reset the
diff --git a/Doc/lib/emailexc.tex b/Doc/lib/emailexc.tex
index 6ac0889..3cef1d5 100644
--- a/Doc/lib/emailexc.tex
+++ b/Doc/lib/emailexc.tex
@@ -1,8 +1,8 @@
-\declaremodule{standard}{email.Errors}
+\declaremodule{standard}{email.errors}
 \modulesynopsis{The exception classes used by the email package.}
 
 The following exception classes are defined in the
-\module{email.Errors} module:
+\module{email.errors} module:
 
 \begin{excclassdesc}{MessageError}{}
 This is the base class for all exceptions that the \module{email}
@@ -59,7 +59,7 @@ problem was found, so for example, if a message nested inside a
 \mimetype{multipart/alternative} had a malformed header, that nested message
 object would have a defect, but the containing messages would not.
 
-All defect classes are subclassed from \class{email.Errors.MessageDefect}, but
+All defect classes are subclassed from \class{email.errors.MessageDefect}, but
 this class is \emph{not} an exception!
 
 \versionadded[All the defect classes were added]{2.4}
diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex
index 330abc0..3415442 100644
--- a/Doc/lib/emailgenerator.tex
+++ b/Doc/lib/emailgenerator.tex
@@ -1,4 +1,4 @@
-\declaremodule{standard}{email.Generator}
+\declaremodule{standard}{email.generator}
 \modulesynopsis{Generate flat text email messages from a message structure.}
 
 One of the most common tasks is to generate the flat text of the email
@@ -8,7 +8,7 @@ module or the \refmodule{nntplib} module, or print the message on the
 console.  Taking a message object structure and producing a flat text
 document is the job of the \class{Generator} class.
 
-Again, as with the \refmodule{email.Parser} module, you aren't limited
+Again, as with the \refmodule{email.parser} module, you aren't limited
 to the functionality of the bundled generator; you could write one
 from scratch yourself.  However the bundled generator knows how to
 generate most email in a standards-compliant way, should handle MIME
@@ -17,7 +17,8 @@ transformation from flat text, to a message structure via the
 \class{Parser} class, and back to flat text, is idempotent (the input
 is identical to the output).
 
-Here are the public methods of the \class{Generator} class:
+Here are the public methods of the \class{Generator} class, imported from the
+\module{email.generator} module:
 
 \begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
     maxheaderlen}}}
@@ -40,7 +41,7 @@ mailbox format files.
 Optional \var{maxheaderlen} specifies the longest length for a
 non-continued header.  When a header line is longer than
 \var{maxheaderlen} (in characters, with tabs expanded to 8 spaces),
-the header will be split as defined in the \module{email.Header}
+the header will be split as defined in the \module{email.header.Header}
 class.  Set to zero to disable header wrapping.  The default is 78, as
 recommended (but not required) by \rfc{2822}.
 \end{classdesc}
@@ -81,9 +82,9 @@ be used in extended print statements.
 As a convenience, see the methods \method{Message.as_string()} and
 \code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
 simplify the generation of a formatted string representation of a
-message object.  For more detail, see \refmodule{email.Message}.
+message object.  For more detail, see \refmodule{email.message}.
 
-The \module{email.Generator} module also provides a derived class,
+The \module{email.generator} module also provides a derived class,
 called \class{DecodedGenerator} which is like the \class{Generator}
 base class, except that non-\mimetype{text} parts are substituted with
 a format string representing the part.
@@ -128,13 +129,5 @@ The default value for \var{fmt} is \code{None}, meaning
 \versionadded{2.2.2}
 \end{classdesc}
 
-\subsubsection{Deprecated methods}
-
-The following methods are deprecated in \module{email} version 2.
-They are documented here for completeness.
-
-\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
-This method is identical to the \method{flatten()} method.
-
-\deprecated{2.2.2}{Use the \method{flatten()} method instead.}
-\end{methoddesc}
+\versionchanged[The previously deprecated method \method{__call__()} was
+removed]{2.5}
diff --git a/Doc/lib/emailheaders.tex b/Doc/lib/emailheaders.tex
index 2795644b..524d08c 100644
--- a/Doc/lib/emailheaders.tex
+++ b/Doc/lib/emailheaders.tex
@@ -1,4 +1,4 @@
-\declaremodule{standard}{email.Header}
+\declaremodule{standard}{email.header}
 \modulesynopsis{Representing non-ASCII headers}
 
 \rfc{2822} is the base standard that describes the format of email
@@ -15,17 +15,18 @@ slew of RFCs have been written describing how to encode email
 containing non-\ASCII{} characters into \rfc{2822}-compliant format.
 These RFCs include \rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}.
 The \module{email} package supports these standards in its
-\module{email.Header} and \module{email.Charset} modules.
+\module{email.header} and \module{email.charset} modules.
 
 If you want to include non-\ASCII{} characters in your email headers,
 say in the \mailheader{Subject} or \mailheader{To} fields, you should
 use the \class{Header} class and assign the field in the
 \class{Message} object to an instance of \class{Header} instead of
-using a string for the header value.  For example:
+using a string for the header value.  Import the \class{Header} class from the
+\module{email.header} module.  For example:
 
 \begin{verbatim}
->>> from email.Message import Message
->>> from email.Header import Header
+>>> from email.message import Message
+>>> from email.header import Header
 >>> msg = Message()
 >>> h = Header('p\xf6stal', 'iso-8859-1')
 >>> msg['Subject'] = h
@@ -87,7 +88,7 @@ Optional \var{errors} is passed straight through to the
 Append the string \var{s} to the MIME header.
 
 Optional \var{charset}, if given, should be a \class{Charset} instance
-(see \refmodule{email.Charset}) or the name of a character set, which
+(see \refmodule{email.charset}) or the name of a character set, which
 will be converted to a \class{Charset} instance.  A value of
 \code{None} (the default) means that the \var{charset} given in the
 constructor is used.
@@ -139,7 +140,7 @@ This method allows you to compare two \class{Header} instances for equality.
 This method allows you to compare two \class{Header} instances for inequality.
 \end{methoddesc}
 
-The \module{email.Header} module also provides the following
+The \module{email.header} module also provides the following
 convenient functions.
 
 \begin{funcdesc}{decode_header}{header}
@@ -155,7 +156,7 @@ encoded string.
 Here's an example:
 
 \begin{verbatim}
->>> from email.Header import decode_header
+>>> from email.header import decode_header
 >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
 [('p\xf6stal', 'iso-8859-1')]
 \end{verbatim}
diff --git a/Doc/lib/emailiter.tex b/Doc/lib/emailiter.tex
index d1a8f98..ef8ef6f 100644
--- a/Doc/lib/emailiter.tex
+++ b/Doc/lib/emailiter.tex
@@ -1,8 +1,8 @@
-\declaremodule{standard}{email.Iterators}
+\declaremodule{standard}{email.iterators}
 \modulesynopsis{Iterate over a  message object tree.}
 
 Iterating over a message object tree is fairly easy with the
-\method{Message.walk()} method.  The \module{email.Iterators} module
+\method{Message.walk()} method.  The \module{email.iterators} module
 provides some useful higher level iterations over message object
 trees.
 
diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex
index 9b41852..7bd7dd8 100644
--- a/Doc/lib/emailmessage.tex
+++ b/Doc/lib/emailmessage.tex
@@ -1,10 +1,11 @@
-\declaremodule{standard}{email.Message}
+\declaremodule{standard}{email.message}
 \modulesynopsis{The base class representing email messages.}
 
 The central class in the \module{email} package is the
-\class{Message} class; it is the base class for the \module{email}
-object model.  \class{Message} provides the core functionality for
-setting and querying header fields, and for accessing message bodies.
+\class{Message} class, imported from the \module{email.message} module.  It is
+the base class for the \module{email} object model.  \class{Message} provides
+the core functionality for setting and querying header fields, and for
+accessing message bodies.
 
 Conceptually, a \class{Message} object consists of \emph{headers} and
 \emph{payloads}.  Headers are \rfc{2822} style field names and
@@ -45,7 +46,7 @@ begin with \code{From }.  For more flexibility, instantiate a
 
 \begin{verbatim}
 from cStringIO import StringIO
-from email.Generator import Generator
+from email.generator import Generator
 fp = StringIO()
 g = Generator(fp, mangle_from_=False, maxheaderlen=60)
 g.flatten(msg)
@@ -119,7 +120,7 @@ client's responsibility to ensure the payload invariants.  Optional
 
 \begin{methoddesc}[Message]{set_charset}{charset}
 Set the character set of the payload to \var{charset}, which can
-either be a \class{Charset} instance (see \refmodule{email.Charset}), a
+either be a \class{Charset} instance (see \refmodule{email.charset}), a
 string naming a character set,
 or \code{None}.  If it is a string, it will be converted to a
 \class{Charset} instance.  If \var{charset} is \code{None}, the
@@ -128,8 +129,8 @@ or \code{None}.  If it is a string, it will be converted to a
 \exception{TypeError}.
 
 The message will be assumed to be of type \mimetype{text/*} encoded with
-\code{charset.input_charset}.  It will be converted to
-\code{charset.output_charset}
+\var{charset.input_charset}.  It will be converted to
+\var{charset.output_charset}
 and encoded properly, if needed, when generating the plain text
 representation of the message.  MIME headers
 (\mailheader{MIME-Version}, \mailheader{Content-Type},
@@ -513,6 +514,9 @@ message/rfc822
 \end{verbatim}
 \end{methoddesc}
 
+\versionchanged[The previously deprecated methods \method{get_type()},
+\method{get_main_type()}, and \method{get_subtype()} were removed]{2.5}
+
 \class{Message} objects can also optionally contain two instance
 attributes, which can be used when generating the plain text of a MIME
 message.
@@ -532,7 +536,7 @@ to the message's \var{preamble} attribute.  When the \class{Generator}
 is writing out the plain text representation of a MIME message, and it
 finds the message has a \var{preamble} attribute, it will write this
 text in the area between the headers and the first boundary.  See
-\refmodule{email.Parser} and \refmodule{email.Generator} for details.
+\refmodule{email.parser} and \refmodule{email.generator} for details.
 
 Note that if the message object has no preamble, the
 \var{preamble} attribute will be \code{None}.
@@ -543,58 +547,15 @@ The \var{epilogue} attribute acts the same way as the \var{preamble}
 attribute, except that it contains text that appears between the last
 boundary and the end of the message.
 
-One note: when generating the flat text for a \mimetype{multipart}
-message that has no \var{epilogue} (using the standard
-\class{Generator} class), no newline is added after the closing
-boundary line.  If the message object has an \var{epilogue} and its
-value does not start with a newline, a newline is printed after the
-closing boundary.  This seems a little clumsy, but it makes the most
-practical sense.  The upshot is that if you want to ensure that a
-newline get printed after your closing \mimetype{multipart} boundary,
-set the \var{epilogue} to the empty string.
+\versionchanged[You do not need to set the epilogue to the empty string in
+order for the \class{Generator} to print a newline at the end of the
+file]{2.5}
 \end{datadesc}
 
 \begin{datadesc}{defects}
 The \var{defects} attribute contains a list of all the problems found when
-parsing this message.  See \refmodule{email.Errors} for a detailed description
+parsing this message.  See \refmodule{email.errors} for a detailed description
 of the possible parsing defects.
 
 \versionadded{2.4}
 \end{datadesc}
-
-\subsubsection{Deprecated methods}
-
-\versionchanged[The \method{add_payload()} method was removed; use the
-\method{attach()} method instead]{2.4}
-
-The following methods are deprecated.  They are documented here for
-completeness.
-
-\begin{methoddesc}[Message]{get_type}{\optional{failobj}}
-Return the message's content type, as a string of the form
-\mimetype{maintype/subtype} as taken from the
-\mailheader{Content-Type} header.
-The returned string is coerced to lowercase.
-
-If there is no \mailheader{Content-Type} header in the message,
-\var{failobj} is returned (defaults to \code{None}).
-
-\deprecated{2.2.2}{Use the \method{get_content_type()} method instead.}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_main_type}{\optional{failobj}}
-Return the message's \emph{main} content type.  This essentially returns the
-\var{maintype} part of the string returned by \method{get_type()}, with the
-same semantics for \var{failobj}.
-
-\deprecated{2.2.2}{Use the \method{get_content_maintype()} method instead.}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_subtype}{\optional{failobj}}
-Return the message's sub-content type.  This essentially returns the
-\var{subtype} part of the string returned by \method{get_type()}, with the
-same semantics for \var{failobj}.
-
-\deprecated{2.2.2}{Use the \method{get_content_subtype()} method instead.}
-\end{methoddesc}
-
diff --git a/Doc/lib/emailmimebase.tex b/Doc/lib/emailmimebase.tex
index 070c9a2..4735be3 100644
--- a/Doc/lib/emailmimebase.tex
+++ b/Doc/lib/emailmimebase.tex
@@ -1,3 +1,11 @@
+\declaremodule{standard}{email.mime}
+\declaremodule{standard}{email.mime.base}
+\declaremodule{standard}{email.mime.nonmultipart}
+\declaremodule{standard}{email.mime.multipart}
+\declaremodule{standard}{email.mime.audio}
+\declaremodule{standard}{email.mime.image}
+\declaremodule{standard}{email.mime.message}
+\declaremodule{standard}{email.mime.text}
 Ordinarily, you get a message object structure by passing a file or
 some text to a parser, which parses the text and returns the root
 message object.  However you can also build a complete message
@@ -6,26 +14,16 @@ hand.  In fact, you can also take an existing structure and add new
 \class{Message} objects, move them around, etc.  This makes a very
 convenient interface for slicing-and-dicing MIME messages.
 
-You can create a new object structure by creating \class{Message}
-instances, adding attachments and all the appropriate headers manually.
-For MIME messages though, the \module{email} package provides some
-convenient subclasses to make things easier.  Each of these classes
-should be imported from a module with the same name as the class, from
-within the \module{email} package.  E.g.:
-
-\begin{verbatim}
-import email.MIMEImage.MIMEImage
-\end{verbatim}
-
-or
-
-\begin{verbatim}
-from email.MIMEText import MIMEText
-\end{verbatim}
+You can create a new object structure by creating \class{Message} instances,
+adding attachments and all the appropriate headers manually.  For MIME
+messages though, the \module{email} package provides some convenient
+subclasses to make things easier.
 
 Here are the classes:
 
 \begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
+Module: \module{email.mime.base}
+
 This is the base class for all the MIME-specific subclasses of
 \class{Message}.  Ordinarily you won't create instances specifically
 of \class{MIMEBase}, although you could.  \class{MIMEBase} is provided
@@ -45,6 +43,8 @@ The \class{MIMEBase} class always adds a \mailheader{Content-Type} header
 \end{classdesc}
 
 \begin{classdesc}{MIMENonMultipart}{}
+Module: \module{email.mime.nonmultipart}
+
 A subclass of \class{MIMEBase}, this is an intermediate base class for
 MIME messages that are not \mimetype{multipart}.  The primary purpose
 of this class is to prevent the use of the \method{attach()} method,
@@ -57,6 +57,7 @@ exception is raised.
 
 \begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{,
     boundary\optional{, _subparts\optional{, _params}}}}}
+Module: \module{email.mime.multipart}
 
 A subclass of \class{MIMEBase}, this is an intermediate base class for
 MIME messages that are \mimetype{multipart}.  Optional \var{_subtype}
@@ -80,8 +81,31 @@ argument, which is a keyword dictionary.
 \versionadded{2.2.2}
 \end{classdesc}
 
+\begin{classdesc}{MIMEApplication}{_data\optional{, _subtype\optional{,
+    _encoder\optional{, **_params}}}}
+Module: \module{email.mime.application}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEApplication} class is
+used to represent MIME message objects of major type \mimetype{application}.
+\var{_data} is a string containing the raw byte data.  Optional \var{_subtype}
+specifies the MIME subtype and defaults to \mimetype{octet-stream}.  
+
+Optional \var{_encoder} is a callable (i.e. function) which will
+perform the actual encoding of the data for transport.  This
+callable takes one argument, which is the \class{MIMEApplication} instance.
+It should use \method{get_payload()} and \method{set_payload()} to
+change the payload to encoded form.  It should also add any
+\mailheader{Content-Transfer-Encoding} or other headers to the message
+object as necessary.  The default encoding is base64.  See the
+\refmodule{email.encoders} module for a list of the built-in encoders.
+
+\var{_params} are passed straight through to the base class constructor.
+\versionadded{2.5}
+\end{classdesc}
+
 \begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
     _encoder\optional{, **_params}}}}
+Module: \module{email.mime.audio}
 
 A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class
 is used to create MIME message objects of major type \mimetype{audio}.
@@ -100,13 +124,14 @@ It should use \method{get_payload()} and \method{set_payload()} to
 change the payload to encoded form.  It should also add any
 \mailheader{Content-Transfer-Encoding} or other headers to the message
 object as necessary.  The default encoding is base64.  See the
-\refmodule{email.Encoders} module for a list of the built-in encoders.
+\refmodule{email.encoders} module for a list of the built-in encoders.
 
 \var{_params} are passed straight through to the base class constructor.
 \end{classdesc}
 
 \begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
     _encoder\optional{, **_params}}}}
+Module: \module{email.mime.image}
 
 A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is
 used to create MIME message objects of major type \mimetype{image}.
@@ -125,13 +150,15 @@ It should use \method{get_payload()} and \method{set_payload()} to
 change the payload to encoded form.  It should also add any
 \mailheader{Content-Transfer-Encoding} or other headers to the message
 object as necessary.  The default encoding is base64.  See the
-\refmodule{email.Encoders} module for a list of the built-in encoders.
+\refmodule{email.encoders} module for a list of the built-in encoders.
 
 \var{_params} are passed straight through to the \class{MIMEBase}
 constructor.
 \end{classdesc}
 
 \begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
+Module: \module{email.mime.message}
+
 A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class
 is used to create MIME objects of main type \mimetype{message}.
 \var{_msg} is used as the payload, and must be an instance of class
@@ -143,6 +170,8 @@ to \mimetype{rfc822}.
 \end{classdesc}
 
 \begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}}
+Module: \module{email.mime.text}
+
 A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
 used to create MIME objects of major type \mimetype{text}.
 \var{_text} is the string for the payload.  \var{_subtype} is the
diff --git a/Doc/lib/emailparser.tex b/Doc/lib/emailparser.tex
index 5fac92f..609fa40 100644
--- a/Doc/lib/emailparser.tex
+++ b/Doc/lib/emailparser.tex
@@ -1,4 +1,4 @@
-\declaremodule{standard}{email.Parser}
+\declaremodule{standard}{email.parser}
 \modulesynopsis{Parse flat text email messages to produce a message
 	        object structure.}
 
@@ -41,9 +41,10 @@ message object trees any way it finds necessary.
 
 \versionadded{2.4}
 
-The \class{FeedParser} provides an API that is conducive to incremental
-parsing of email messages, such as would be necessary when reading the text of
-an email message from a source that can block (e.g. a socket).  The
+The \class{FeedParser}, imported from the \module{email.feedparser} module,
+provides an API that is conducive to incremental parsing of email messages,
+such as would be necessary when reading the text of an email message from a
+source that can block (e.g. a socket).  The
 \class{FeedParser} can of course be used to parse an email message fully
 contained in a string or a file, but the classic \class{Parser} API may be
 more convenient for such use cases.  The semantics and results of the two
@@ -56,14 +57,14 @@ accurate when parsing standards-compliant messages, and it does a very good
 job of parsing non-compliant messages, providing information about how a
 message was deemed broken.  It will populate a message object's \var{defects}
 attribute with a list of any problems it found in a message.  See the
-\refmodule{email.Errors} module for the list of defects that it can find.
+\refmodule{email.errors} module for the list of defects that it can find.
 
 Here is the API for the \class{FeedParser}:
 
 \begin{classdesc}{FeedParser}{\optional{_factory}}
 Create a \class{FeedParser} instance.  Optional \var{_factory} is a
 no-argument callable that will be called whenever a new message object is
-needed.  It defaults to the \class{email.Message.Message} class.
+needed.  It defaults to the \class{email.message.Message} class.
 \end{classdesc}
 
 \begin{methoddesc}[FeedParser]{feed}{data}
@@ -82,21 +83,22 @@ more data to a closed \class{FeedParser}.
 
 \subsubsection{Parser class API}
 
-The \class{Parser} provides an API that can be used to parse a message when
-the complete contents of the message are available in a string or file.  The
-\module{email.Parser} module also provides a second class, called
+The \class{Parser} class, imported from the \module{email.parser} module,
+provides an API that can be used to parse a message when the complete contents
+of the message are available in a string or file.  The
+\module{email.parser} module also provides a second class, called
 \class{HeaderParser} which can be used if you're only interested in
 the headers of the message. \class{HeaderParser} can be much faster in
 these situations, since it does not attempt to parse the message body,
 instead setting the payload to the raw body as a string.
 \class{HeaderParser} has the same API as the \class{Parser} class.
 
-\begin{classdesc}{Parser}{\optional{_class\optional{, strict}}}
+\begin{classdesc}{Parser}{\optional{_class}}
 The constructor for the \class{Parser} class takes an optional
 argument \var{_class}.  This must be a callable factory (such as a
 function or a class), and it is used whenever a sub-message object
 needs to be created.  It defaults to \class{Message} (see
-\refmodule{email.Message}).  The factory will be called without
+\refmodule{email.message}).  The factory will be called without
 arguments.
 
 The optional \var{strict} flag is ignored.  \deprecated{2.4}{Because the
@@ -201,6 +203,6 @@ Here are some notes on the parsing semantics:
       \method{is_multipart()} method may return \code{False}.  If such
       messages were parsed with the \class{FeedParser}, they will have an
       instance of the \class{MultipartInvariantViolationDefect} class in their
-      \var{defects} attribute list.  See \refmodule{email.Errors} for
+      \var{defects} attribute list.  See \refmodule{email.errors} for
       details.
 \end{itemize}
diff --git a/Doc/lib/emailutil.tex b/Doc/lib/emailutil.tex
index 491a2b9..fe96473 100644
--- a/Doc/lib/emailutil.tex
+++ b/Doc/lib/emailutil.tex
@@ -1,7 +1,7 @@
-\declaremodule{standard}{email.Utils}
+\declaremodule{standard}{email.utils}
 \modulesynopsis{Miscellaneous email package utilities.}
 
-There are several useful utilities provided in the \module{email.Utils}
+There are several useful utilities provided in the \module{email.utils}
 module:
 
 \begin{funcdesc}{quote}{str}
@@ -38,7 +38,7 @@ values as might be returned by \method{Message.get_all()}.  Here's a
 simple example that gets all the recipients of a message:
 
 \begin{verbatim}
-from email.Utils import getaddresses
+from email.utils import getaddresses
 
 tos = msg.get_all('to', [])
 ccs = msg.get_all('cc', [])
diff --git a/Doc/lib/mimelib.tex b/Doc/lib/mimelib.tex
index 67de597..491d844 100644
--- a/Doc/lib/mimelib.tex
+++ b/Doc/lib/mimelib.tex
@@ -12,9 +12,9 @@
 \authoraddress{\email{barry@python.org}}
 
 \date{\today}
-\release{3.0}			% software release, not documentation
+\release{4.0}			% software release, not documentation
 \setreleaseinfo{}		% empty for final release
-\setshortversion{3.0}		% major.minor only for software
+\setshortversion{4.0}		% major.minor only for software
 
 \begin{document}
 
@@ -38,11 +38,11 @@ The \module{email} package provides classes and utilities to create,
 parse, generate, and modify email messages, conforming to all the
 relevant email and MIME related RFCs.
 
-This document describes version 3.0 of the \module{email} package, which is
-distributed with Python 2.4 and is available as a standalone distutils-based
-package for use with Python 2.3.  \module{email} 3.0 is not compatible with
-Python versions earlier than 2.3.  For more information about the
-\module{email} package, including download links and mailing lists, see
+This document describes version 4.0 of the \module{email} package, which is
+distributed with Python 2.5 and is available as a standalone distutils-based
+package for use with earlier Python versions.  \module{email} 4.0 is not
+compatible with Python versions earlier than 2.3.  For more information about
+the \module{email} package, including download links and mailing lists, see
 \ulink{Python's email SIG}{http://www.python.org/sigs/email-sig}.
 
 The documentation that follows was written for the Python project, so
@@ -51,7 +51,8 @@ package documentation, there are a few notes to be aware of:
 
 \begin{itemize}
 \item Deprecation and ``version added'' notes are relative to the
-      Python version a feature was added or deprecated.
+      Python version a feature was added or deprecated.  See
+      the package history in section \ref{email-pkg-history} for details.
 
 \item If you're reading this documentation as part of the
       standalone \module{email} package, some of the internal links to