This commit was manufactured by cvs2svn to create branch

'release22-maint'.

Doc/lib/email-dir.py

+#!/usr/bin/env python
+
+"""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 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.MIMEMultipart import MIMEMultipart
+from email.MIMEImage import MIMEImage
+from email.MIMEText import MIMEText
+
+COMMASPACE = ', '
+
+
+def usage(code, msg=''):
+    print >> sys.stderr, __doc__
+    if msg:
+        print >> sys.stderr, msg
+    sys.exit(code)
+
+
+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:]
+    
+    # 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.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)
+        if not os.path.isfile(path):
+            continue
+        # Guess the content type based on the file's extension.  Encoding
+        # will be ignored, although we should check for simple things like
+        # gzip'd or compressed files.
+        ctype, encoding = mimetypes.guess_type(path)
+        if ctype is None or encoding is not None:
+            # No guess could be made, or the file is encoded (compressed), so
+            # use a generic bag-of-bits type.
+            ctype = 'application/octet-stream'
+        maintype, subtype = ctype.split('/', 1)
+        if maintype == 'text':
+            fp = open(path)
+            # Note: we should handle calculating the charset
+            msg = MIMEText(fp.read(), _subtype=subtype)
+            fp.close()
+        elif maintype == 'image':
+            fp = open(path, 'rb')
+            msg = MIMEImage(fp.read(), _subtype=subtype)
+            fp.close()
+        elif maintype == 'audio':
+            fp = open(path, 'rb')
+            msg = MIMEAudio(fp.read(), _subtype=subtype)
+            fp.close()
+        else:
+            fp = open(path, 'rb')
+            msg = MIMEBase(maintype, subtype)
+            msg.set_payload(fp.read())
+            fp.close()
+            # Encode the payload using Base64
+            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()
+
+
+if __name__ == '__main__':
+    main()

Doc/lib/email-mime.py

+# Import smtplib for the actual sending function
+import smtplib
+
+# Here are the email pacakge modules we'll need
+from email.MIMEImage import MIMEImage
+from email.MIMEMultipart import MIMEMultipart
+
+COMMASPACE = ', '
+
+# Create the container (outer) email message.
+msg = MIMEMultipart()
+msg['Subject'] = 'Our family reunion'
+# me == the sender's email address
+# family = the list of all recipients' email addresses
+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:
+    # Open the files in binary mode.  Let the MIMEImage class automatically
+    # guess the specific image type.
+    fp = open(file, 'rb')
+    img = MIMEImage(fp.read())
+    fp.close()
+    msg.attach(img)
+
+# Send the email via our own SMTP server.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, family, msg.as_string())
+s.close()

Doc/lib/email-simple.py

+# Import smtplib for the actual sending function
+import smtplib
+
+# Import the email modules we'll need
+from email.MIMEText import MIMEText
+
+# Open a plain text file for reading.  For this example, assume that
+# the text file contains only ASCII characters.
+fp = open(textfile, 'rb')
+# Create a text/plain message
+msg = MIMEText(fp.read())
+fp.close()
+
+# me == the sender's email address
+# you == the recipient's email address
+msg['Subject'] = 'The contents of %s' % textfile
+msg['From'] = me
+msg['To'] = you
+
+# Send the message via our own SMTP server, but don't include the
+# envelope header.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, [you], msg.as_string())
+s.close()

Doc/lib/email-unpack.py

+#!/usr/bin/env python
+
+"""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 errno
+import mimetypes
+import email
+
+
+def usage(code, msg=''):
+    print >> sys.stderr, __doc__
+    if msg:
+        print >> sys.stderr, msg
+    sys.exit(code)
+
+
+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
+
+    try:
+        msgfile = args[0]
+    except IndexError:
+        usage(1)
+
+    try:
+        os.mkdir(dir)
+    except OSError, e:
+        # Ignore directory exists error
+        if e.errno <> errno.EEXIST: raise
+
+    fp = open(msgfile)
+    msg = email.message_from_file(fp)
+    fp.close()
+
+    counter = 1
+    for part in msg.walk():
+        # multipart/* are just containers
+        if part.get_content_maintype() == 'multipart':
+            continue
+        # Applications should really sanitize the given filename so that an
+        # email message can't be used to overwrite important files
+        filename = part.get_filename()
+        if not filename:
+            ext = mimetypes.guess_extension(part.get_type())
+            if not ext:
+                # Use a generic bag-of-bits extension
+                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.close()
+
+
+if __name__ == '__main__':
+    main()

Doc/lib/emailcharsets.tex

+\declaremodule{standard}{email.Charset}
+\modulesynopsis{Character Sets}
+
+This module provides a class \class{Charset} for representing
+character sets and character set conversions in email messages, as
+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.
+
+\versionadded{2.2.2}
+
+\begin{classdesc}{Charset}{\optional{input_charset}}
+Map character sets to their email properties.
+
+This class provides information about the requirements imposed on
+email for a specific character set.  It also provides convenience
+routines for converting between character sets, given the availability
+of the applicable codecs.  Given a character set, it will do its best
+to provide information on how to use that character set in an email
+message in an RFC-compliant way.
+
+Certain character sets must be encoded with quoted-printable or base64
+when used in email headers or bodies.  Certain character sets must be
+converted outright, and are not allowed in email.
+
+Optional \var{input_charset} is as described below.  After being alias
+normalized it is also used as a lookup into the registry of character
+sets to find out the header encoding, body encoding, and output
+conversion codec to be used for the character set.  For example, if
+\var{input_charset} is \code{iso-8859-1}, then headers and bodies will
+be encoded using quoted-printable and no output conversion codec is
+necessary.  If \var{input_charset} is \code{euc-jp}, then headers will
+be encoded with base64, bodies will not be encoded, but output text
+will be converted from the \code{euc-jp} character set to the
+\code{iso-2022-jp} character set.
+\end{classdesc}
+
+\class{Charset} instances have the following data attributes:
+
+\begin{datadesc}{input_charset}
+The initial character set specified.  Common aliases are converted to
+their \emph{official} email names (e.g. \code{latin_1} is converted to
+\code{iso-8859-1}).  Defaults to 7-bit \code{us-ascii}.
+\end{datadesc}
+
+\begin{datadesc}{header_encoding}
+If the character set must be encoded before it can be used in an
+email header, this attribute will be set to \code{Charset.QP} (for
+quoted-printable), \code{Charset.BASE64} (for base64 encoding), or
+\code{Charset.SHORTEST} for the shortest of QP or BASE64 encoding.
+Otherwise, it will be \code{None}.
+\end{datadesc}
+
+\begin{datadesc}{body_encoding}
+Same as \var{header_encoding}, but describes the encoding for the
+mail message's body, which indeed may be different than the header
+encoding.  \code{Charset.SHORTEST} is not allowed for
+\var{body_encoding}.
+\end{datadesc}
+
+\begin{datadesc}{output_charset}
+Some character sets must be converted before they can be used in
+email headers or bodies.  If the \var{input_charset} is one of
+them, this attribute will contain the name of the character set
+output will be converted to.  Otherwise, it will be \code{None}.
+\end{datadesc}
+
+\begin{datadesc}{input_codec}
+The name of the Python codec used to convert the \var{input_charset} to
+Unicode.  If no conversion codec is necessary, this attribute will be
+\code{None}.
+\end{datadesc}
+
+\begin{datadesc}{output_codec}
+The name of the Python codec used to convert Unicode to the
+\var{output_charset}.  If no conversion codec is necessary, this
+attribute will have the same value as the \var{input_codec}.
+\end{datadesc}
+
+\class{Charset} instances also have the following methods:
+
+\begin{methoddesc}[Charset]{get_body_encoding}{}
+Return the content transfer encoding used for body encoding.
+
+This is either the string \samp{quoted-printable} or \samp{base64}
+depending on the encoding used, or it is a function, in which case you
+should call the function with a single argument, the Message object
+being encoded.  The function should then set the
+\mailheader{Content-Transfer-Encoding} header itself to whatever is
+appropriate.
+
+Returns the string \samp{quoted-printable} if
+\var{body_encoding} is \code{QP}, returns the string
+\samp{base64} if \var{body_encoding} is \code{BASE64}, and returns the
+string \samp{7bit} otherwise.
+\end{methoddesc}
+
+\begin{methoddesc}{convert}{s}
+Convert the string \var{s} from the \var{input_codec} to the
+\var{output_codec}.
+\end{methoddesc}
+
+\begin{methoddesc}{to_splittable}{s}
+Convert a possibly multibyte string to a safely splittable format.
+\var{s} is the string to split.
+
+Uses the \var{input_codec} to try and convert the string to Unicode,
+so it can be safely split on character boundaries (even for multibyte
+characters).
+
+Returns the string as-is if it isn't known how to convert \var{s} to
+Unicode with the \var{input_charset}.
+
+Characters that could not be converted to Unicode will be replaced
+with the Unicode replacement character \character{U+FFFD}.
+\end{methoddesc}
+
+\begin{methoddesc}{from_splittable}{ustr\optional{, to_output}}
+Convert a splittable string back into an encoded string.  \var{ustr}
+is a Unicode string to ``unsplit''.
+
+This method uses the proper codec to try and convert the string from
+Unicode back into an encoded format.  Return the string as-is if it is
+not Unicode, or if it could not be converted from Unicode.
+
+Characters that could not be converted from Unicode will be replaced
+with an appropriate character (usually \character{?}).
+
+If \var{to_output} is \code{True} (the default), uses
+\var{output_codec} to convert to an 
+encoded format.  If \var{to_output} is \code{False}, it uses
+\var{input_codec}.
+\end{methoddesc}
+
+\begin{methoddesc}{get_output_charset}{}
+Return the output character set.
+
+This is the \var{output_charset} attribute if that is not \code{None},
+otherwise it is \var{input_charset}.
+\end{methoddesc}
+
+\begin{methoddesc}{encoded_header_len}{}
+Return the length of the encoded header string, properly calculating
+for quoted-printable or base64 encoding.
+\end{methoddesc}
+
+\begin{methoddesc}{header_encode}{s\optional{, convert}}
+Header-encode the string \var{s}.
+
+If \var{convert} is \code{True}, the string will be converted from the
+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}.
+
+The type of encoding (base64 or quoted-printable) will be based on
+the \var{header_encoding} attribute.
+\end{methoddesc}
+
+\begin{methoddesc}{body_encode}{s\optional{, convert}}
+Body-encode the string \var{s}.
+
+If \var{convert} is \code{True} (the default), the string will be
+converted from the input charset to output charset automatically.
+Unlike \method{header_encode()}, there are no issues with byte
+boundaries and multibyte charsets in email bodies, so this is usually
+pretty safe.
+
+The type of encoding (base64 or quoted-printable) will be based on
+the \var{body_encoding} attribute.
+\end{methoddesc}
+
+The \class{Charset} class also provides a number of methods to support
+standard operations and built-in functions.
+
+\begin{methoddesc}[Charset]{__str__}{}
+Returns \var{input_charset} as a string coerced to lower case.
+\end{methoddesc}
+
+\begin{methoddesc}[Charset]{__eq__}{other}
+This method allows you to compare two \class{Charset} instances for equality.
+\end{methoddesc}
+
+\begin{methoddesc}[Header]{__ne__}{other}
+This method allows you to compare two \class{Charset} instances for inequality.
+\end{methoddesc}
+
+The \module{email.Charset} module also provides the following
+functions for adding new entries to the global character set, alias,
+and codec registries:
+
+\begin{funcdesc}{add_charset}{charset\optional{, header_enc\optional{,
+    body_enc\optional{, output_charset}}}}
+Add character properties to the global registry.
+
+\var{charset} is the input character set, and must be the canonical
+name of a character set.
+
+Optional \var{header_enc} and \var{body_enc} is either
+\code{Charset.QP} for quoted-printable, \code{Charset.BASE64} for
+base64 encoding, \code{Charset.SHORTEST} for the shortest of
+quoted-printable or base64 encoding, or \code{None} for no encoding.
+\code{SHORTEST} is only valid for \var{header_enc}. The default is
+\code{None} for no encoding.
+
+Optional \var{output_charset} is the character set that the output
+should be in.  Conversions will proceed from input charset, to
+Unicode, to the output charset when the method
+\method{Charset.convert()} is called.  The default is to output in the
+same character set as the input.
+
+Both \var{input_charset} and \var{output_charset} must have Unicode
+codec entries in the module's character set-to-codec mapping; use
+\function{add_codec()} to add codecs the module does
+not know about.  See the \refmodule{codecs} module's documentation for
+more information.
+
+The global character set registry is kept in the module global
+dictionary \code{CHARSETS}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_alias}{alias, canonical}
+Add a character set alias.  \var{alias} is the alias name,
+e.g. \code{latin-1}.  \var{canonical} is the character set's canonical
+name, e.g. \code{iso-8859-1}.
+
+The global charset alias registry is kept in the module global
+dictionary \code{ALIASES}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_codec}{charset, codecname}
+Add a codec that map characters in the given character set to and from
+Unicode.
+
+\var{charset} is the canonical name of a character set.
+\var{codecname} is the name of a Python codec, as appropriate for the
+second argument to the \function{unicode()} built-in, or to the
+\method{encode()} method of a Unicode string.
+\end{funcdesc}

Doc/lib/emailheaders.tex

+\declaremodule{standard}{email.Header}
+\modulesynopsis{Representing non-ASCII headers}
+
+\rfc{2822} is the base standard that describes the format of email
+messages.  It derives from the older \rfc{822} standard which came
+into widespread use at a time when most email was composed of \ASCII{}
+characters only.  \rfc{2822} is a specification written assuming email
+contains only 7-bit \ASCII{} characters.
+
+Of course, as email has been deployed worldwide, it has become
+internationalized, such that language specific character sets can now
+be used in email messages.  The base standard still requires email
+messages to be transfered using only 7-bit \ASCII{} characters, so a
+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.
+
+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:
+
+\begin{verbatim}
+>>> from email.Message import Message
+>>> from email.Header import Header
+>>> msg = Message()
+>>> h = Header('p\xf6stal', 'iso-8859-1')
+>>> msg['Subject'] = h
+>>> print msg.as_string()
+Subject: =?iso-8859-1?q?p=F6stal?=
+
+
+\end{verbatim}
+
+Notice here how we wanted the \mailheader{Subject} field to contain a
+non-\ASCII{} character?  We did this by creating a \class{Header}
+instance and passing in the character set that the byte string was
+encoded in.  When the subsequent \class{Message} instance was
+flattened, the \mailheader{Subject} field was properly \rfc{2047}
+encoded.  MIME-aware mail readers would show this header using the
+embedded ISO-8859-1 character.
+
+\versionadded{2.2.2}
+
+Here is the \class{Header} class description:
+
+\begin{classdesc}{Header}{\optional{s\optional{, charset\optional{,
+    maxlinelen\optional{, header_name\optional{, continuation_ws}}}}}}
+Create a MIME-compliant header that can contain strings in different
+character sets.
+
+Optional \var{s} is the initial header value.  If \code{None} (the
+default), the initial header value is not set.  You can later append
+to the header with \method{append()} method calls.  \var{s} may be a
+byte string or a Unicode string, but see the \method{append()}
+documentation for semantics.
+
+Optional \var{charset} serves two purposes: it has the same meaning as
+the \var{charset} argument to the \method{append()} method.  It also
+sets the default character set for all subsequent \method{append()}
+calls that omit the \var{charset} argument.  If \var{charset} is not
+provided in the constructor (the default), the \code{us-ascii}
+character set is used both as \var{s}'s initial charset and as the
+default for subsequent \method{append()} calls.
+
+The maximum line length can be specified explicit via
+\var{maxlinelen}.  For splitting the first line to a shorter value (to
+account for the field header which isn't included in \var{s},
+e.g. \mailheader{Subject}) pass in the name of the field in
+\var{header_name}.  The default \var{maxlinelen} is 76, and the
+default value for \var{header_name} is \code{None}, meaning it is not
+taken into account for the first line of a long, split header.
+
+Optional \var{continuation_ws} must be \rfc{2822}-compliant folding
+whitespace, and is usually either a space or a hard tab character.
+This character will be prepended to continuation lines.
+\end{classdesc}
+
+\begin{methoddesc}[Header]{append}{s\optional{, charset}}
+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
+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.
+
+\var{s} may be a byte string or a Unicode string.  If it is a byte
+string (i.e. \code{isinstance(s, str)} is true), then
+\var{charset} is the encoding of that byte string, and a
+\exception{UnicodeError} will be raised if the string cannot be
+decoded with that character set.
+
+If \var{s} is a Unicode string, then \var{charset} is a hint
+specifying the character set of the characters in the string.  In this
+case, when producing an \rfc{2822}-compliant header using \rfc{2047}
+rules, the Unicode string will be encoded using the following charsets
+in order: \code{us-ascii}, the \var{charset} hint, \code{utf-8}.  The
+first character set to not provoke a \exception{UnicodeError} is used.
+\end{methoddesc}
+
+\begin{methoddesc}[Header]{encode}{}
+Encode a message header into an RFC-compliant format, possibly
+wrapping long lines and encapsulating non-\ASCII{} parts in base64 or
+quoted-printable encodings.
+\end{methoddesc}
+
+The \class{Header} class also provides a number of methods to support
+standard operators and built-in functions.
+
+\begin{methoddesc}[Header]{__str__}{}
+A synonym for \method{Header.encode()}.  Useful for
+\code{str(aHeader)}.
+\end{methoddesc}
+
+\begin{methoddesc}[Header]{__unicode__}{}
+A helper for the built-in \function{unicode()} function.  Returns the
+header as a Unicode string.
+\end{methoddesc}
+
+\begin{methoddesc}[Header]{__eq__}{other}
+This method allows you to compare two \class{Header} instances for equality.
+\end{methoddesc}
+
+\begin{methoddesc}[Header]{__ne__}{other}
+This method allows you to compare two \class{Header} instances for inequality.
+\end{methoddesc}
+
+The \module{email.Header} module also provides the following
+convenient functions.
+
+\begin{funcdesc}{decode_header}{header}
+Decode a message header value without converting the character set.
+The header value is in \var{header}.
+
+This function returns a list of \code{(decoded_string, charset)} pairs
+containing each of the decoded parts of the header.  \var{charset} is
+\code{None} for non-encoded parts of the header, otherwise a lower
+case string containing the name of the character set specified in the
+encoded string.
+
+Here's an example:
+
+\begin{verbatim}
+>>> from email.Header import decode_header
+>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
+[('p\\xf6stal', 'iso-8859-1')]
+\end{verbatim}
+\end{funcdesc}
+
+\begin{funcdesc}{make_header}{decoded_seq\optional{, maxlinelen\optional{,
+    header_name\optional{, continuation_ws}}}}
+Create a \class{Header} instance from a sequence of pairs as returned
+by \function{decode_header()}.
+
+\function{decode_header()} takes a header value string and returns a
+sequence of pairs of the format \code{(decoded_string, charset)} where
+\var{charset} is the name of the character set.
+
+This function takes one of those sequence of pairs and returns a
+\class{Header} instance.  Optional \var{maxlinelen},
+\var{header_name}, and \var{continuation_ws} are as in the
+\class{Header} constructor.
+\end{funcdesc}

Doc/lib/emailmimebase.tex

+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
+structure from scratch, or even individual \class{Message} objects by
+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}
+
+Here are the classes:
+
+\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
+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
+primarily as a convenient base class for more specific MIME-aware
+subclasses.
+
+\var{_maintype} is the \mailheader{Content-Type} major type
+(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the
+\mailheader{Content-Type} minor type 
+(e.g. \mimetype{plain} or \mimetype{gif}).  \var{_params} is a parameter
+key/value dictionary and is passed directly to
+\method{Message.add_header()}.
+
+The \class{MIMEBase} class always adds a \mailheader{Content-Type} header
+(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a
+\mailheader{MIME-Version} header (always set to \code{1.0}).
+\end{classdesc}
+
+\begin{classdesc}{MIMENonMultipart}{}
+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,
+which only makes sense for \mimetype{multipart} messages.  If
+\method{attach()} is called, a \exception{MultipartConversionError}
+exception is raised.
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{,
+    boundary\optional{, _subparts\optional{, _params}}}}}
+
+A subclass of \class{MIMEBase}, this is an intermediate base class for
+MIME messages that are \mimetype{multipart}.  Optional \var{_subtype}
+defaults to \mimetype{mixed}, but can be used to specify the subtype
+of the message.  A \mailheader{Content-Type} header of
+\mimetype{multipart/}\var{_subtype} will be added to the message
+object.  A \mailheader{MIME-Version} header will also be added.
+
+Optional \var{boundary} is the multipart boundary string.  When
+\code{None} (the default), the boundary is calculated when needed.
+
+\var{_subparts} is a sequence of initial subparts for the payload.  It
+must be possible to convert this sequence to a list.  You can always
+attach new subparts to the message by using the
+\method{Message.attach()} method.
+
+Additional parameters for the \mailheader{Content-Type} header are
+taken from the keyword arguments, or passed into the \var{_params}
+argument, which is a keyword dictionary.
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
+    _encoder\optional{, **_params}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class
+is used to create MIME message objects of major type \mimetype{audio}.
+\var{_audiodata} is a string containing the raw audio data.  If this
+data can be decoded by the standard Python module \refmodule{sndhdr},
+then the subtype will be automatically included in the
+\mailheader{Content-Type} header.  Otherwise you can explicitly specify the
+audio subtype via the \var{_subtype} parameter.  If the minor type could
+not be guessed and \var{_subtype} was not given, then \exception{TypeError}
+is raised.
+
+Optional \var{_encoder} is a callable (i.e. function) which will
+perform the actual encoding of the audio data for transport.  This
+callable takes one argument, which is the \class{MIMEAudio} 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.
+\end{classdesc}
+
+\begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
+    _encoder\optional{, **_params}}}}
+
+A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is
+used to create MIME message objects of major type \mimetype{image}.
+\var{_imagedata} is a string containing the raw image data.  If this
+data can be decoded by the standard Python module \refmodule{imghdr},
+then the subtype will be automatically included in the
+\mailheader{Content-Type} header.  Otherwise you can explicitly specify the
+image subtype via the \var{_subtype} parameter.  If the minor type could
+not be guessed and \var{_subtype} was not given, then \exception{TypeError}
+is raised.
+
+Optional \var{_encoder} is a callable (i.e. function) which will
+perform the actual encoding of the image data for transport.  This
+callable takes one argument, which is the \class{MIMEImage} 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 \class{MIMEBase}
+constructor.
+\end{classdesc}
+
+\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
+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
+\class{Message} (or a subclass thereof), otherwise a
+\exception{TypeError} is raised.
+
+Optional \var{_subtype} sets the subtype of the message; it defaults
+to \mimetype{rfc822}.
+\end{classdesc}
+
+\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
+    _charset\optional{, _encoder}}}}
+
+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
+minor type and defaults to \mimetype{plain}.  \var{_charset} is the
+character set of the text and is passed as a parameter to the
+\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}.  No
+guessing or encoding is performed on the text data, but a newline is
+appended to \var{_text} if it doesn't already end with a newline.
+
+\deprecated{2.2.2}{The \var{_encoding} argument has been deprecated.
+Encoding now happens implicitly based on the \var{_charset} argument.}
+\end{classdesc}

Lib/email/MIMEMultipart.py

+# Copyright (C) 2002 Python Software Foundation
+# Author: barry@zope.com (Barry Warsaw)
+
+"""Base class for MIME multipart/* type messages.
+"""
+
+from email import MIMEBase
+
+
+
+class MIMEMultipart(MIMEBase.MIMEBase):
+    """Base class for MIME multipart/* type messages."""
+
+    def __init__(self, _subtype='mixed', boundary=None, *_subparts, **_params):
+        """Creates a multipart/* type message.
+
+        By default, creates a multipart/mixed message, with proper
+        Content-Type and MIME-Version headers.
+
+        _subtype is the subtype of the multipart content type, defaulting to
+        `mixed'.
+
+        boundary is the multipart boundary string.  By default it is
+        calculated as needed.
+
+        _subparts is a sequence of initial subparts for the payload.  It
+        must be possible to convert this sequence to a list.  You can always
+        attach new subparts to the message by using the attach() method.
+
+        Additional parameters for the Content-Type header are taken from the
+        keyword arguments (or passed into the _params argument).
+        """
+        MIMEBase.MIMEBase.__init__(self, 'multipart', _subtype, **_params)
+        if _subparts:
+            self.attach(*list(_subparts))
+        if boundary:
+            self.set_boundary(boundary)

Lib/email/MIMENonMultipart.py

+# Copyright (C) 2002 Python Software Foundation
+# Author: barry@zope.com (Barry Warsaw)
+
+"""Base class for MIME type messages that are not multipart.
+"""
+
+from email import Errors
+from email import MIMEBase
+
+
+
+class MIMENonMultipart(MIMEBase.MIMEBase):
+    """Base class for MIME multipart/* type messages."""
+
+    __pychecker__ = 'unusednames=payload'
+
+    def attach(self, payload):
+        # The public API prohibits attaching multiple subparts to MIMEBase
+        # derived subtypes since none of them are, by definition, of content
+        # type multipart/*
+        raise Errors.MultipartConversionError(
+            'Cannot attach additional subparts to non-multipart/*')
+
+    del __pychecker__

Lib/email/base64MIME.py

+# Copyright (C) 2002 Python Software Foundation
+# Author: che@debian.org (Ben Gertzfield)
+
+"""Base64 content transfer encoding per RFCs 2045-2047.
+
+This module handles the content transfer encoding method defined in RFC 2045
+to encode arbitrary 8-bit data using the three 8-bit bytes in four 7-bit
+characters encoding known as Base64.
+
+It is used in the MIME standards for email to attach images, audio, and text
+using some 8-bit character sets to messages.
+
+This module provides an interface to encode and decode both headers and bodies
+with Base64 encoding.
+
+RFC 2045 defines a method for including character set information in an
+`encoded-word' in a header.  This method is commonly used for 8-bit real names
+in To:, From:, Cc:, etc. fields, as well as Subject: lines.
+
+This module does not do the line wrapping or end-of-line character conversion
+necessary for proper internationalized headers; it only does dumb encoding and
+decoding.  To deal with the various line wrapping issues, use the email.Header
+module.
+"""
+
+import re
+from binascii import b2a_base64, a2b_base64
+from email.Utils import fix_eols
+
+try:
+    from email._compat22 import _floordiv
+except SyntaxError:
+    # Python 2.1 spells integer division differently
+    from email._compat21 import _floordiv
+
+
+CRLF = '\r\n'
+NL = '\n'
+EMPTYSTRING = ''
+
+# See also Charset.py
+MISC_LEN = 7
+
+try:
+    True, False
+except NameError:
+    True = 1
+    False = 0
+
+
+
+# Helpers
+def base64_len(s):
+    """Return the length of s when it is encoded with base64."""
+    groups_of_3, leftover = divmod(len(s), 3)
+    # 4 bytes out for each 3 bytes (or nonzero fraction thereof) in.
+    # Thanks, Tim!
+    n = groups_of_3 * 4
+    if leftover:
+        n += 4
+    return n
+
+
+
+def header_encode(header, charset='iso-8859-1', keep_eols=False,
+                  maxlinelen=76, eol=NL):
+    """Encode a single header line with Base64 encoding in a given charset.
+
+    Defined in RFC 2045, this Base64 encoding is identical to normal Base64
+    encoding, except that each line must be intelligently wrapped (respecting
+    the Base64 encoding), and subsequent lines must start with a space.
+
+    charset names the character set to use to encode the header.  It defaults
+    to iso-8859-1.
+
+    End-of-line characters (\\r, \\n, \\r\\n) will be automatically converted
+    to the canonical email line separator \\r\\n unless the keep_eols
+    parameter is True (the default is False).
+
+    Each line of the header will be terminated in the value of eol, which
+    defaults to "\\n".  Set this to "\\r\\n" if you are using the result of
+    this function directly in email.
+
+    The resulting string will be in the form:
+
+    "=?charset?b?WW/5ciBtYXp66XLrIHf8eiBhIGhhbXBzdGHuciBBIFlv+XIgbWF6euly?=\\n
+      =?charset?b?6yB3/HogYSBoYW1wc3Rh7nIgQkMgWW/5ciBtYXp66XLrIHf8eiBhIGhh?="
+
+    with each line wrapped at, at most, maxlinelen characters (defaults to 76
+    characters).
+    """
+    # Return empty headers unchanged
+    if not header:
+        return header
+
+    if not keep_eols:
+        header = fix_eols(header)
+
+    # Base64 encode each line, in encoded chunks no greater than maxlinelen in
+    # length, after the RFC chrome is added in.
+    base64ed = []
+    max_encoded = maxlinelen - len(charset) - MISC_LEN
+    max_unencoded = _floordiv(max_encoded * 3, 4)
+
+    # BAW: Ben's original code used a step of max_unencoded, but I think it
+    # ought to be max_encoded.  Otherwise, where's max_encoded used?  I'm
+    # still not sure what the
+    for i in range(0, len(header), max_unencoded):
+        base64ed.append(b2a_base64(header[i:i+max_unencoded]))
+
+    # Now add the RFC chrome to each encoded chunk
+    lines = []
+    for line in base64ed:
+        # Ignore the last character of each line if it is a newline
+        if line.endswith(NL):
+            line = line[:-1]
+        # Add the chrome
+        lines.append('=?%s?b?%s?=' % (charset, line))
+    # Glue the lines together and return it.  BAW: should we be able to
+    # specify the leading whitespace in the joiner?
+    joiner = eol + ' '
+    return joiner.join(lines)
+
+
+
+def encode(s, binary=True, maxlinelen=76, eol=NL):
+    """Encode a string with base64.
+
+    Each line will be wrapped at, at most, maxlinelen characters (defaults to
+    76 characters).
+
+    If binary is False, end-of-line characters will be converted to the
+    canonical email end-of-line sequence \\r\\n.  Otherwise they will be left
+    verbatim (this is the default).
+
+    Each line of encoded text will end with eol, which defaults to "\\n".  Set
+    this to "\r\n" if you will be using the result of this function directly
+    in an email.
+    """
+    if not s:
+        return s
+
+    if not binary:
+        s = fix_eols(s)
+
+    encvec = []
+    max_unencoded = _floordiv(maxlinelen * 3, 4)
+    for i in range(0, len(s), max_unencoded):
+        # BAW: should encode() inherit b2a_base64()'s dubious behavior in
+        # adding a newline to the encoded string?
+        enc = b2a_base64(s[i:i + max_unencoded])
+        if enc.endswith(NL) and eol <> NL:
+            enc = enc[:-1] + eol
+        encvec.append(enc)
+    return EMPTYSTRING.join(encvec)
+
+
+# For convenience and backwards compatibility w/ standard base64 module
+body_encode = encode
+encodestring = encode
+
+
+
+def decode(s, convert_eols=None):
+    """Decode a raw base64 string.
+
+    If convert_eols is set to a string value, all canonical email linefeeds,
+    e.g. "\\r\\n", in the decoded text will be converted to the value of
+    convert_eols.  os.linesep is a good choice for convert_eols if you are
+    decoding a text attachment.
+
+    This function does not parse a full MIME header value encoded with
+    base64 (like =?iso-8895-1?b?bmloISBuaWgh?=) -- please use the high
+    level email.Header class for that functionality.
+    """
+    if not s:
+        return s
+
+    dec = a2b_base64(s)
+    if convert_eols:
+        return dec.replace(CRLF, convert_eols)
+    return dec
+
+
+# For convenience and backwards compatibility w/ standard base64 module
+body_decode = decode
+decodestring = decode

Lib/email/test/data/msg_32.txt

+Delivered-To: freebsd-isp@freebsd.org
+Date: Tue, 26 Sep 2000 12:23:03 -0500
+From: Anne Person <aperson@example.com>
+To: Barney Dude <bdude@example.com>
+Subject: Re: Limiting Perl CPU Utilization...
+Mime-Version: 1.0
+Content-Type: text/plain; charset*=ansi-x3.4-1968''us-ascii
+Content-Disposition: inline
+User-Agent: Mutt/1.3.8i
+Sender: owner-freebsd-isp@FreeBSD.ORG
+Precedence: bulk
+X-Loop: FreeBSD.org
+
+Some message.

Lib/email/test/data/msg_33.txt

+Delivered-To: freebsd-isp@freebsd.org
+Date: Wed, 27 Sep 2000 11:11:09 -0500
+From: Anne Person <aperson@example.com>
+To: Barney Dude <bdude@example.com>
+Subject: Re: Limiting Perl CPU Utilization...
+Mime-Version: 1.0
+Content-Type: multipart/signed; micalg*=ansi-x3.4-1968''pgp-md5;
+	protocol*=ansi-x3.4-1968''application%2Fpgp-signature;
+	boundary*="ansi-x3.4-1968''EeQfGwPcQSOJBaQU"
+Content-Disposition: inline
+Sender: owner-freebsd-isp@FreeBSD.ORG
+Precedence: bulk
+X-Loop: FreeBSD.org
+
+
+--EeQfGwPcQSOJBaQU
+Content-Type: text/plain; charset*=ansi-x3.4-1968''us-ascii
+Content-Disposition: inline
+Content-Transfer-Encoding: quoted-printable
+
+part 1
+
+--EeQfGwPcQSOJBaQU
+Content-Type: text/plain
+Content-Disposition: inline
+
+part 2
+
+--EeQfGwPcQSOJBaQU--