mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-30 23:08:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

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

Browse source 
and NEWS updates.
This commit is contained in:
Barry Warsaw 2006-03-18 15:41:53 +00:00
parent 9ae019bf5b
commit 40ef0067ad
44 changed files with 3821 additions and 468 deletions
Download patch file Download diff file Expand all files Collapse all files

127
Doc/lib/email-dir.py
View file

@ -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
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
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)
parser = OptionParser(usage="""\
Send the contents of a directory as a MIME message.
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:]
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__':

6
Doc/lib/email-mime.py
View file

@ -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:

2
Doc/lib/email-simple.py
View file

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

63
Doc/lib/email-unpack.py
View file

@ -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)
parser = OptionParser(usage="""\
Unpack a MIME message into a directory of files.
dir = os.curdir
for opt, arg in opts:
if opt in ('-h', '--help'):
usage(0)
elif opt in ('-d', '--directory'):
dir = arg
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()

72
Doc/lib/email.tex
View file

@ -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}

8
Doc/lib/emailcharsets.tex
View file

@ -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:

4
Doc/lib/emailencoders.tex
View file

@ -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

6
Doc/lib/emailexc.tex
View file

@ -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}

25
Doc/lib/emailgenerator.tex
View file

@ -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}

17
Doc/lib/emailheaders.tex
View file

@ -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}

4
Doc/lib/emailiter.tex
View file

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

73
Doc/lib/emailmessage.tex
View file

@ -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}

65
Doc/lib/emailmimebase.tex
View file

@ -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

26
Doc/lib/emailparser.tex
View file

@ -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}

6
Doc/lib/emailutil.tex
View file

@ -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', [])

17
Doc/lib/mimelib.tex
View file

@ -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