403 lines
16 KiB
TeX
403 lines
16 KiB
TeX
% Copyright (C) 2001-2006 Python Software Foundation
|
|
% Author: barry@python.org (Barry Warsaw)
|
|
|
|
\section{\module{email} ---
|
|
An email and MIME handling package}
|
|
|
|
\declaremodule{standard}{email}
|
|
\modulesynopsis{Package supporting the parsing, manipulating, and
|
|
generating email messages, including MIME documents.}
|
|
\moduleauthor{Barry A. Warsaw}{barry@python.org}
|
|
\sectionauthor{Barry A. Warsaw}{barry@python.org}
|
|
|
|
\versionadded{2.2}
|
|
|
|
The \module{email} package is a library for managing email messages,
|
|
including MIME and other \rfc{2822}-based message documents. It
|
|
subsumes most of the functionality in several older standard modules
|
|
such as \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}), 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
|
|
that it splits the parsing and generating of email messages from the
|
|
internal \emph{object model} representation of email. Applications
|
|
using the \module{email} package deal primarily with objects; you can
|
|
add sub-objects to messages, remove sub-objects from messages,
|
|
completely re-arrange the contents, etc. There is a separate parser
|
|
and a separate generator which handles the transformation from flat
|
|
text to the object model, and then back to flat text again. There
|
|
are also handy subclasses for some common MIME object types, and a few
|
|
miscellaneous utilities that help with such common tasks as extracting
|
|
and parsing message field values, creating RFC-compliant dates, etc.
|
|
|
|
The following sections describe the functionality of the
|
|
\module{email} package. The ordering follows a progression that
|
|
should be common in applications: an email message is read as flat
|
|
text from a file or other source, the text is parsed to produce the
|
|
object structure of the email message, this structure is manipulated,
|
|
and finally, the object tree is rendered back into flat text.
|
|
|
|
It is perfectly feasible to create the object structure out of whole
|
|
cloth --- i.e. completely from scratch. From there, a similar
|
|
progression can be taken as above.
|
|
|
|
Also included are detailed specifications of all the classes and
|
|
modules that the \module{email} package provides, the exception
|
|
classes you might encounter while using the \module{email} package,
|
|
some auxiliary utilities, and a few examples. For users of the older
|
|
\module{mimelib} package, or previous versions of the \module{email}
|
|
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}
|
|
\input{emailmessage}
|
|
|
|
\subsection{Parsing email messages}
|
|
\input{emailparser}
|
|
|
|
\subsection{Generating MIME documents}
|
|
\input{emailgenerator}
|
|
|
|
\subsection{Creating email and MIME objects from scratch}
|
|
\input{emailmimebase}
|
|
|
|
\subsection{Internationalized headers}
|
|
\input{emailheaders}
|
|
|
|
\subsection{Representing character sets}
|
|
\input{emailcharsets}
|
|
|
|
\subsection{Encoders}
|
|
\input{emailencoders}
|
|
|
|
\subsection{Exception and Defect classes}
|
|
\input{emailexc}
|
|
|
|
\subsection{Miscellaneous utilities}
|
|
\input{emailutil}
|
|
|
|
\subsection{Iterators}
|
|
\input{emailiter}
|
|
|
|
\subsection{Package History\label{email-pkg-history}}
|
|
|
|
This table describes the release history of the email package, corresponding
|
|
to the version of Python that the package was released with. For purposes of
|
|
this document, when you see a note about change or added versions, these refer
|
|
to the Python version the change was made it, \emph{not} the email package
|
|
version. This table also describes the Python compatibility of each version
|
|
of the package.
|
|
|
|
\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 major differences between \module{email} version 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()}.
|
|
|
|
\item Fixes have been added for \rfc{2231} support which can change some of
|
|
the return types for \function{Message.get_param()} and friends. Under
|
|
some circumstances, values which used to return a 3-tuple now return
|
|
simple strings (specifically, if all extended parameter segments were
|
|
unencoded, there is no language and charset designation expected, so the
|
|
return type is now a simple string). Also, \%-decoding used to be done
|
|
for both encoded and unencoded segments; this decoding is now done only
|
|
for encoded segments.
|
|
\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
|
|
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.
|
|
|
|
\item All aspects of the API which raised \exception{DeprecationWarning}s in
|
|
version 2 have been removed. These include the \var{_encoder} argument
|
|
to the \class{MIMEText} constructor, the \method{Message.add_payload()}
|
|
method, the \function{Utils.dump_address_pair()} function, and the
|
|
functions \function{Utils.decode()} and \function{Utils.encode()}.
|
|
|
|
\item New \exception{DeprecationWarning}s have been added to:
|
|
\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 future versions.
|
|
|
|
\item Support for Pythons earlier than 2.3 has been removed.
|
|
\end{itemize}
|
|
|
|
Here are the differences between \module{email} version 2 and version 1:
|
|
|
|
\begin{itemize}
|
|
\item The \module{email.Header} and \module{email.Charset} modules
|
|
have been added.
|
|
|
|
\item The pickle format for \class{Message} instances has changed.
|
|
Since this was never (and still isn't) formally defined, this
|
|
isn't considered a backward incompatibility. However if your
|
|
application pickles and unpickles \class{Message} instances, be
|
|
aware that in \module{email} version 2, \class{Message}
|
|
instances now have private variables \var{_charset} and
|
|
\var{_default_type}.
|
|
|
|
\item Several methods in the \class{Message} class have been
|
|
deprecated, or their signatures changed. Also, many new methods
|
|
have been added. See the documentation for the \class{Message}
|
|
class for details. The changes should be completely backward
|
|
compatible.
|
|
|
|
\item The object structure has changed in the face of
|
|
\mimetype{message/rfc822} content types. In \module{email}
|
|
version 1, such a type would be represented by a scalar payload,
|
|
i.e. the container message's \method{is_multipart()} returned
|
|
false, \method{get_payload()} was not a list object, but a single
|
|
\class{Message} instance.
|
|
|
|
This structure was inconsistent with the rest of the package, so
|
|
the object representation for \mimetype{message/rfc822} content
|
|
types was changed. In \module{email} version 2, the container
|
|
\emph{does} return \code{True} from \method{is_multipart()}, and
|
|
\method{get_payload()} returns a list containing a single
|
|
\class{Message} item.
|
|
|
|
Note that this is one place that backward compatibility could
|
|
not be completely maintained. However, if you're already
|
|
testing the return type of \method{get_payload()}, you should be
|
|
fine. You just need to make sure your code doesn't do a
|
|
\method{set_payload()} with a \class{Message} instance on a
|
|
container with a content type of \mimetype{message/rfc822}.
|
|
|
|
\item The \class{Parser} constructor's \var{strict} argument was
|
|
added, and its \method{parse()} and \method{parsestr()} methods
|
|
grew a \var{headersonly} argument. The \var{strict} flag was
|
|
also added to functions \function{email.message_from_file()}
|
|
and \function{email.message_from_string()}.
|
|
|
|
\item \method{Generator.__call__()} is deprecated; use
|
|
\method{Generator.flatten()} instead. The \class{Generator}
|
|
class has also grown the \method{clone()} method.
|
|
|
|
\item The \class{DecodedGenerator} class in the
|
|
\module{email.Generator} module was added.
|
|
|
|
\item The intermediate base classes \class{MIMENonMultipart} and
|
|
\class{MIMEMultipart} have been added, and interposed in the
|
|
class hierarchy for most of the other MIME-related derived
|
|
classes.
|
|
|
|
\item The \var{_encoder} argument to the \class{MIMEText} constructor
|
|
has been deprecated. Encoding now happens implicitly based
|
|
on the \var{_charset} argument.
|
|
|
|
\item The following functions in the \module{email.Utils} module have
|
|
been deprecated: \function{dump_address_pairs()},
|
|
\function{decode()}, and \function{encode()}. The following
|
|
functions have been added to the module:
|
|
\function{make_msgid()}, \function{decode_rfc2231()},
|
|
\function{encode_rfc2231()}, and \function{decode_params()}.
|
|
|
|
\item The non-public function \function{email.Iterators._structure()}
|
|
was added.
|
|
\end{itemize}
|
|
|
|
\subsection{Differences from \module{mimelib}}
|
|
|
|
The \module{email} package was originally prototyped as a separate
|
|
library called
|
|
\ulink{\module{mimelib}}{http://mimelib.sf.net/}.
|
|
Changes have been made so that
|
|
method names are more consistent, and some methods or modules have
|
|
either been added or removed. The semantics of some of the methods
|
|
have also changed. For the most part, any functionality available in
|
|
\module{mimelib} is still available in the \refmodule{email} package,
|
|
albeit often in a different way. Backward compatibility between
|
|
the \module{mimelib} package and the \module{email} package was not a
|
|
priority.
|
|
|
|
Here is a brief description of the differences between the
|
|
\module{mimelib} and the \refmodule{email} packages, along with hints on
|
|
how to port your applications.
|
|
|
|
Of course, the most visible difference between the two packages is
|
|
that the package name has been changed to \refmodule{email}. In
|
|
addition, the top-level package has the following differences:
|
|
|
|
\begin{itemize}
|
|
\item \function{messageFromString()} has been renamed to
|
|
\function{message_from_string()}.
|
|
|
|
\item \function{messageFromFile()} has been renamed to
|
|
\function{message_from_file()}.
|
|
|
|
\end{itemize}
|
|
|
|
The \class{Message} class has the following differences:
|
|
|
|
\begin{itemize}
|
|
\item The method \method{asString()} was renamed to \method{as_string()}.
|
|
|
|
\item The method \method{ismultipart()} was renamed to
|
|
\method{is_multipart()}.
|
|
|
|
\item The \method{get_payload()} method has grown a \var{decode}
|
|
optional argument.
|
|
|
|
\item The method \method{getall()} was renamed to \method{get_all()}.
|
|
|
|
\item The method \method{addheader()} was renamed to \method{add_header()}.
|
|
|
|
\item The method \method{gettype()} was renamed to \method{get_type()}.
|
|
|
|
\item The method \method{getmaintype()} was renamed to
|
|
\method{get_main_type()}.
|
|
|
|
\item The method \method{getsubtype()} was renamed to
|
|
\method{get_subtype()}.
|
|
|
|
\item The method \method{getparams()} was renamed to
|
|
\method{get_params()}.
|
|
Also, whereas \method{getparams()} returned a list of strings,
|
|
\method{get_params()} returns a list of 2-tuples, effectively
|
|
the key/value pairs of the parameters, split on the \character{=}
|
|
sign.
|
|
|
|
\item The method \method{getparam()} was renamed to \method{get_param()}.
|
|
|
|
\item The method \method{getcharsets()} was renamed to
|
|
\method{get_charsets()}.
|
|
|
|
\item The method \method{getfilename()} was renamed to
|
|
\method{get_filename()}.
|
|
|
|
\item The method \method{getboundary()} was renamed to
|
|
\method{get_boundary()}.
|
|
|
|
\item The method \method{setboundary()} was renamed to
|
|
\method{set_boundary()}.
|
|
|
|
\item The method \method{getdecodedpayload()} was removed. To get
|
|
similar functionality, pass the value 1 to the \var{decode} flag
|
|
of the {get_payload()} method.
|
|
|
|
\item The method \method{getpayloadastext()} was removed. Similar
|
|
functionality
|
|
is supported by the \class{DecodedGenerator} class in the
|
|
\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.
|
|
\end{itemize}
|
|
|
|
The \class{Parser} class has no differences in its public interface.
|
|
It does have some additional smarts to recognize
|
|
\mimetype{message/delivery-status} type messages, which it represents as
|
|
a \class{Message} instance containing separate \class{Message}
|
|
subparts for each header block in the delivery status
|
|
notification\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}
|
|
module though, called \class{DecodedGenerator} which provides most of
|
|
the functionality previously available in the
|
|
\method{Message.getpayloadastext()} method.
|
|
|
|
The following modules and classes have been changed:
|
|
|
|
\begin{itemize}
|
|
\item The \class{MIMEBase} class constructor arguments \var{_major}
|
|
and \var{_minor} have changed to \var{_maintype} and
|
|
\var{_subtype} respectively.
|
|
|
|
\item The \code{Image} class/module has been renamed to
|
|
\code{MIMEImage}. The \var{_minor} argument has been renamed to
|
|
\var{_subtype}.
|
|
|
|
\item The \code{Text} class/module has been renamed to
|
|
\code{MIMEText}. The \var{_minor} argument has been renamed to
|
|
\var{_subtype}.
|
|
|
|
\item The \code{MessageRFC822} class/module has been renamed to
|
|
\code{MIMEMessage}. Note that an earlier version of
|
|
\module{mimelib} called this class/module \code{RFC822}, but
|
|
that clashed with the Python standard library module
|
|
\refmodule{rfc822} on some case-insensitive file systems.
|
|
|
|
Also, the \class{MIMEMessage} class now represents any kind of
|
|
MIME message with main type \mimetype{message}. It takes an
|
|
optional argument \var{_subtype} which is used to set the MIME
|
|
subtype. \var{_subtype} defaults to \mimetype{rfc822}.
|
|
\end{itemize}
|
|
|
|
\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.
|
|
|
|
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.
|
|
|
|
\subsection{Examples}
|
|
|
|
Here are a few examples of how to use the \module{email} package to
|
|
read, write, and send simple email messages, as well as more complex
|
|
MIME messages.
|
|
|
|
First, let's see how to create and send a simple text message:
|
|
|
|
\verbatiminput{email-simple.py}
|
|
|
|
Here's an example of how to send a MIME message containing a bunch of
|
|
family pictures that may be residing in a directory:
|
|
|
|
\verbatiminput{email-mime.py}
|
|
|
|
Here's an example of how to send the entire contents of a directory as
|
|
an email message:
|
|
\footnote{Thanks to Matthew Dixon Cowles for the original inspiration
|
|
and examples.}
|
|
|
|
\verbatiminput{email-dir.py}
|
|
|
|
And finally, here's an example of how to unpack a MIME message like
|
|
the one above, into a directory of files:
|
|
|
|
\verbatiminput{email-unpack.py}
|