Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Vast update to email version 2. This could surely use proofreading.

This commit is contained in:
Barry Warsaw 2002-10-01 01:05:52 +00:00
parent 2d7fab1a45
commit 5b9da893d3
10 changed files with 1188 additions and 328 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

217
Doc/lib/email.tex
View File

@ -1,4 +1,4 @@
% Copyright (C) 2001 Python Software Foundation
% Copyright (C) 2001,2002 Python Software Foundation
% Author: barry@zope.com (Barry Warsaw)
\section{\module{email} ---
@ -19,13 +19,10 @@ 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\footnote{For this reason,
line endings in the \module{email} package are always native line
endings. The \module{smtplib} module is responsible for converting
from native line endings to \rfc{2821} line endings, just as your mail
server would be responsible for converting from \rfc{2821} line
endings to native line endings when it stores messages in a local
mailbox.}.
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
\rfc{2045}-\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
@ -55,8 +52,8 @@ 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, from which the \module{email} package is
descended, a section on differences and porting is provided.
\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}
@ -72,133 +69,10 @@ descended, a section on differences and porting is provided.
\input{emailgenerator}
\subsection{Creating email and MIME objects from scratch}
\input{emailmimebase}
Ordinarily, you get a message object tree by passing some text to a
parser, which parses the text and returns the root of the message
object tree. However you can also build a complete object tree from
scratch, or even individual \class{Message} objects by hand. In fact,
you can also take an existing tree 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 tree by creating \class{Message}
instances, adding payloads and all the appropriate headers manually.
For MIME messages though, the \module{email} package provides some
convenient classes 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}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
_encoder\optional{, **_params}}}}
A subclass of \class{MIMEBase}, 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 \emph{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}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
_encoder\optional{, **_params}}}}
A subclass of \class{MIMEBase}, 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 \emph{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}{MIMEText}{_text\optional{, _subtype\optional{,
_charset\optional{, _encoder}}}}
A subclass of \class{MIMEBase}, 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{MIMEBase} 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.
The \var{_encoding} argument is as with the \class{MIMEImage} class
constructor, except that the default encoding for \class{MIMEText}
objects is one that doesn't actually modify the payload, but does set
the \mailheader{Content-Transfer-Encoding} header to \code{7bit} or
\code{8bit} as appropriate.
\end{classdesc}
\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
A subclass of \class{MIMEBase}, 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}
\subsection{Headers, Character sets, and Internationalization}
\input{emailheaders}
\subsection{Encoders}
\input{emailencoders}
@ -212,6 +86,77 @@ to \mimetype{rfc822}.
\subsection{Iterators}
\input{emailiter}
\subsection{Differences from \module{email} v1 (up to Python 2.2.1)}
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. \module{email} version 2 is
almost entirely backwards compatible with version 1, with the
following differences:
\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 backwards 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 changes. Also, many new methods
have been added. See the documentation for the \class{Message}
class for deatils. The changes should be completely backwards
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, and was
actually a \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 backwards 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 heirarchy 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

8
Doc/lib/emailencoders.tex
View File

@ -17,8 +17,8 @@ set the \mailheader{Content-Transfer-Encoding} header as appropriate.
Here are the encoding functions provided:
\begin{funcdesc}{encode_quopri}{msg}
Encodes the payload into \emph{Quoted-Printable} form and sets the
\code{Content-Transfer-Encoding:} header to
Encodes the payload into quoted-Printable form and sets the
\mailheader{Content-Transfer-Encoding} header to
\code{quoted-printable}\footnote{Note that encoding with
\method{encode_quopri()} also encodes all tabs and space characters in
the data.}.
@ -27,11 +27,11 @@ printable data, but contains a few unprintable characters.
\end{funcdesc}
\begin{funcdesc}{encode_base64}{msg}
Encodes the payload into \emph{Base64} form and sets the
Encodes the payload into base64 form and sets the
\mailheader{Content-Transfer-Encoding} header to
\code{base64}. This is a good encoding to use when most of your payload
is unprintable data since it is a more compact form than
Quoted-Printable. The drawback of Base64 encoding is that it
quoted-printable. The drawback of base64 encoding is that it
renders the text non-human readable.
\end{funcdesc}

10
Doc/lib/emailexc.tex
View File

@ -21,7 +21,7 @@ a message, this class is derived from \exception{MessageParseError}.
It can be raised from the \method{Parser.parse()} or
\method{Parser.parsestr()} methods.
Situations where it can be raised include finding a \emph{Unix-From}
Situations where it can be raised include finding an envelope
header after the first \rfc{2822} header of the message, finding a
continuation line before the first \rfc{2822} header is found, or finding
a line in the headers which is neither a header or a continuation
@ -35,7 +35,8 @@ It can be raised from the \method{Parser.parse()} or
\method{Parser.parsestr()} methods.
Situations where it can be raised include not being able to find the
starting or terminating boundary in a \mimetype{multipart/*} message.
starting or terminating boundary in a \mimetype{multipart/*} message
when strict parsing is used.
\end{excclassdesc}
\begin{excclassdesc}{MultipartConversionError}{}
@ -45,4 +46,9 @@ message's \mailheader{Content-Type} main type is not either
\mimetype{multipart} or missing. \exception{MultipartConversionError}
multiply inherits from \exception{MessageError} and the built-in
\exception{TypeError}.
Since \method{Message.add_payload()} is deprecated, this exception is
rarely raised in practice. However the exception may also be raised
if the \method{attach()} method is called on an instance of a class
derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}).
\end{excclassdesc}

93
Doc/lib/emailgenerator.tex
View File

@ -1,11 +1,11 @@
\declaremodule{standard}{email.Generator}
\modulesynopsis{Generate flat text email messages from a message object tree.}
\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
message represented by a message object tree. You will need to do
message represented by a message object structure. You will need to do
this if you want to send your message via the \refmodule{smtplib}
module or the \refmodule{nntplib} module, or print the message on the
console. Taking a message object tree and producing a flat text
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
@ -13,10 +13,9 @@ 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
and non-MIME email messages just fine, and is designed so that the
transformation from flat text, to an object tree via the
\class{Parser} class,
and back to flat text, is idempotent (the input is identical to the
output).
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:
@ -27,14 +26,16 @@ object called \var{outfp} for an argument. \var{outfp} must support
the \method{write()} method and be usable as the output file in a
Python 2.0 extended print statement.
Optional \var{mangle_from_} is a flag that, when true, puts a \samp{>}
character in front of any line in the body that starts exactly as
Optional \var{mangle_from_} is a flag that, when \code{True}, puts a
\samp{>} character in front of any line in the body that starts exactly as
\samp{From } (i.e. \code{From} followed by a space at the front of the
line). This is the only guaranteed portable way to avoid having such
lines be mistaken for \emph{Unix-From} headers (see
lines be mistaken for a Unix mailbox format envelope header separator (see
\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
for details).
for details). \var{mangle_from_} defaults to \code{True}, but you
might want to set this to \code{False} if you are not writing Unix
mailbox format files.
Optional \var{maxheaderlen} specifies the longest length for a
non-continued header. When a header line is longer than
@ -47,20 +48,28 @@ recommended (but not required) by \rfc{2822}.
The other public \class{Generator} methods are:
\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
Print the textual representation of the message object tree rooted at
\begin{methoddesc}[Generator]{flatten()}{msg\optional{, unixfrom}}
Print the textual representation of the message object structure rooted at
\var{msg} to the output file specified when the \class{Generator}
instance was created. Sub-objects are visited depth-first and the
resulting text will be properly MIME encoded.
Optional \var{unixfrom} is a flag that forces the printing of the
\emph{Unix-From} (a.k.a. envelope header or \code{From_} header)
delimiter before the first \rfc{2822} header of the root message
object. If the root object has no \emph{Unix-From} header, a standard
one is crafted. By default, this is set to 0 to inhibit the printing
of the \emph{Unix-From} delimiter.
envelope header delimiter before the first \rfc{2822} header of the
root message object. If the root object has no envelope header, a
standard one is crafted. By default, this is set to \code{False} to
inhibit the printing of the envelope delimiter.
Note that for sub-objects, no \emph{Unix-From} header is ever printed.
Note that for sub-objects, no envelope header is ever printed.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Generator]{clone}{fp}
Return an independent clone of this \class{Generator} instance with
the exact same options.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Generator]{write}{s}
@ -74,3 +83,49 @@ 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}.
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.
\begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{,
maxheaderlen\optional{, fmt}}}}
This class, derived from \class{Generator} walks through all the
subparts of a message. If the subpart is of main type
\mimetype{text}, then it prints the decoded payload of the subpart.
Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the
\class{Generator} base class.
If the subpart is not of main type \mimetype{text}, optional \var{fmt}
is a format string that is used instead of the message
payload. \var{fmt} is expanded with the following keywords (in
\samp{\%(keyword)s} format):
type : Full MIME type of the non-\mimetype{text} part
maintype : Main MIME type of the non-\mimetype{text} part
subtype : Sub-MIME type of the non-\mimetype{text} part
filename : Filename of the non-\mimetype{text} part
description: Description associated with the non-\mimetype{text} part
encoding : Content transfer encoding of the non-\mimetype{text} part
The default value for \var{fmt} is \code{None}, meaning
\begin{verbatim}
[Non-text (%(type)s) part of message omitted, filename %(filename)s]
\end{verbatim}
\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}

409
Doc/lib/emailheaders.tex Normal file
View File

@ -0,0 +1,409 @@
\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 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 (in module \module{email.Header} 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 many 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, StringType)} 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)} calls.
\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}
\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 the 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 qp or
base64 encoding, or \code{None} for no encoding. \code{SHORTEST} is
only valid for \var{header_enc}. It describes how message headers and
message bodies in the input charset are to be encoded. Default is 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(charset, codecname)} 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}

32
Doc/lib/emailiter.tex
View File

@ -29,3 +29,35 @@ Thus, by default \function{typed_subpart_iterator()} returns each
subpart that has a MIME type of \mimetype{text/*}.
\end{funcdesc}
The following function has been added as a useful debugging tool. It
should \emph{not} be considered part of the supported public interface
for the package.
\begin{funcdesc}{_structure}{msg\optional{, fp\optional{, level}}}
Prints an indented representation of the content types of the
message object structure. For example:
\begin{verbatim}
>>> msg = email.message_from_file(somefile)
>>> _structure(msg)
multipart/mixed
text/plain
text/plain
multipart/digest
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
text/plain
\end{verbatim}
Optional \var{fp} is a file-like object to print the output to. It
must be suitable for Python's extended print statement. \var{level}
is used internally.
\end{funcdesc}

409
Doc/lib/emailmessage.tex
View File

@ -12,12 +12,12 @@ values where the field name and value are separated by a colon. The
colon is not part of either the field name or the field value.
Headers are stored and returned in case-preserving form but are
matched case-insensitively. There may also be a single
\emph{Unix-From} header, also known as the envelope header or the
matched case-insensitively. There may also be a single envelope
header, also known as the \emph{Unix-From} header or the
\code{From_} header. The payload is either a string in the case of
simple message objects, a list of \class{Message} objects for
multipart MIME documents, or a single \class{Message} instance for
\mimetype{message/rfc822} type objects.
simple message objects or a list of \class{Message} objects for
MIME container documents (e.g. \mimetype{multipart/*} and
\mimetype{message/rfc822}).
\class{Message} objects provide a mapping style interface for
accessing the message headers, and an explicit interface for accessing
@ -35,82 +35,96 @@ The constructor takes no arguments.
\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
Return the entire formatted message as a string. Optional
\var{unixfrom}, when true, specifies to include the \emph{Unix-From}
envelope header; it defaults to 0.
envelope header; it defaults to \code{False}.
\end{methoddesc}
\begin{methoddesc}[Message]{__str__}{}
Equivalent to \method{aMessage.as_string(unixfrom=1)}.
Equivalent to \method{aMessage.as_string(unixfrom=True)}.
\end{methoddesc}
\begin{methoddesc}[Message]{is_multipart}{}
Return 1 if the message's payload is a list of sub-\class{Message}
objects, otherwise return 0. When \method{is_multipart()} returns 0,
the payload should either be a string object, or a single
\class{Message} instance.
Return \code{True} if the message's payload is a list of
sub-\class{Message} objects, otherwise return \code{False}. When
\method{is_multipart()} returns False, the payload should be a string
object.
\end{methoddesc}
\begin{methoddesc}[Message]{set_unixfrom}{unixfrom}
Set the \emph{Unix-From} (a.k.a envelope header or \code{From_}
header) to \var{unixfrom}, which should be a string.
Set the message's envelope header to \var{unixfrom}, which should be a string.
\end{methoddesc}
\begin{methoddesc}[Message]{get_unixfrom}{}
Return the \emph{Unix-From} header. Defaults to \code{None} if the
\emph{Unix-From} header was never set.
\end{methoddesc}
\begin{methoddesc}[Message]{add_payload}{payload}
Add \var{payload} to the message object's existing payload. If, prior
to calling this method, the object's payload was \code{None}
(i.e. never before set), then after this method is called, the payload
will be the argument \var{payload}.
If the object's payload was already a list
(i.e. \method{is_multipart()} returns 1), then \var{payload} is
appended to the end of the existing payload list.
For any other type of existing payload, \method{add_payload()} will
transform the new payload into a list consisting of the old payload
and \var{payload}, but only if the document is already a MIME
multipart document. This condition is satisfied if the message's
\mailheader{Content-Type} header's main type is either
\mimetype{multipart}, or there is no \mailheader{Content-Type}
header. In any other situation,
\exception{MultipartConversionError} is raised.
Return the message's envelope header. Defaults to \code{None} if the
envelope header was never set.
\end{methoddesc}
\begin{methoddesc}[Message]{attach}{payload}
Synonymous with \method{add_payload()}.
Add the given payload to the current payload, which must be
\code{None} or a list of \class{Message} objects before the call.
After the call, the payload will always be a list of \class{Message}
objects. If you want to set the payload to a scalar object (e.g. a
string), use \method{set_payload()} instead.
\end{methoddesc}
\begin{methoddesc}[Message]{get_payload}{\optional{i\optional{, decode}}}
Return the current payload, which will be a list of \class{Message}
objects when \method{is_multipart()} returns 1, or a scalar (either a
string or a single \class{Message} instance) when
\method{is_multipart()} returns 0.
Return a reference the current payload, which will be a list of
\class{Message} objects when \method{is_multipart()} is \code{True}, or a
string when \method{is_multipart()} is \code{False}. If the
payload is a list and you mutate the list object, you modify the
message's payload in place.
With optional \var{i}, \method{get_payload()} will return the
With optional argument \var{i}, \method{get_payload()} will return the
\var{i}-th element of the payload, counting from zero, if
\method{is_multipart()} returns 1. An \exception{IndexError} will be raised
if \var{i} is less than 0 or greater than or equal to the number of
items in the payload. If the payload is scalar
(i.e. \method{is_multipart()} returns 0) and \var{i} is given, a
\method{is_multipart()} is \code{True}. An \exception{IndexError}
will be raised if \var{i} is less than 0 or greater than or equal to
the number of items in the payload. If the payload is a string
(i.e. \method{is_multipart()} is \code{False}) and \var{i} is given, a
\exception{TypeError} is raised.
Optional \var{decode} is a flag indicating whether the payload should be
decoded or not, according to the \mailheader{Content-Transfer-Encoding} header.
When true and the message is not a multipart, the payload will be
When \code{True} and the message is not a multipart, the payload will be
decoded if this header's value is \samp{quoted-printable} or
\samp{base64}. If some other encoding is used, or
\mailheader{Content-Transfer-Encoding} header is
missing, the payload is returned as-is (undecoded). If the message is
a multipart and the \var{decode} flag is true, then \code{None} is
returned.
a multipart and the \var{decode} flag is \code{True}, then \code{None} is
returned. The default for \var{decode} is \code{False}.
\end{methoddesc}
\begin{methoddesc}[Message]{set_payload}{payload}
\begin{methoddesc}[Message]{set_payload}{payload\optional{, charset}}
Set the entire message object's payload to \var{payload}. It is the
client's responsibility to ensure the payload invariants.
client's responsibility to ensure the payload invariants. Optional
\var{charset} sets the message's default character set (see
\method{set_charset()} for details.
\versionchanged[\var{charset} argument added]{2.2.2}
\end{methoddesc}
\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
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
\code{charset} parameter will be removed from the
\mailheader{Content-Type} header. Anything else will generate 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}
and encoded properly, if needed, when generating the plain text
representation of the message. MIME headers
(\mailheader{MIME-Version}, \mailheader{Content-Type},
\mailheader{Content-Transfer-Encoding}) will be added as needed.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_charset}{}
Return the \class{Charset} instance associated with the message's payload.
\versionadded{2.2.2}
\end{methoddesc}
The following methods implement a mapping-like interface for accessing
@ -123,8 +137,8 @@ in dictionaries there is no guaranteed order to the keys returned by
order. These semantic differences are intentional and are biased
toward maximal convenience.
Note that in all cases, any optional \emph{Unix-From} header the message
may have is not included in the mapping interface.
Note that in all cases, any envelope header present in the message is
not included in the mapping interface.
\begin{methoddesc}[Message]{__len__}{}
Return the total number of headers, including duplicates.
@ -177,32 +191,32 @@ present in the headers.
\end{methoddesc}
\begin{methoddesc}[Message]{has_key}{name}
Return 1 if the message contains a header field named \var{name},
otherwise return 0.
Return true if the message contains a header field named \var{name},
otherwise return false.
\end{methoddesc}
\begin{methoddesc}[Message]{keys}{}
Return a list of all the message's header field names. These keys
will be sorted in the order in which they were added to the message
via \method{__setitem__()}, and may contain duplicates. Any fields
deleted and then subsequently re-added are always appended to the end
of the header list.
will be sorted in the order in which they appeared in the original
message, or were added to the message and may contain
duplicates. Any fields deleted and then subsequently re-added are
always appended to the end of the header list.
\end{methoddesc}
\begin{methoddesc}[Message]{values}{}
Return a list of all the message's field values. These will be sorted
in the order in which they were added to the message via
\method{__setitem__()}, and may contain duplicates. Any fields
deleted and then subsequently re-added are always appended to the end
of the header list.
in the order in which they appeared in the original message, or were
added to the message, and may contain
duplicates. Any fields deleted and then subsequently re-added are
always appended to the end of the header list.
\end{methoddesc}
\begin{methoddesc}[Message]{items}{}
Return a list of 2-tuples containing all the message's field headers and
values. These will be sorted in the order in which they were added to
the message via \method{__setitem__()}, and may contain duplicates.
Any fields deleted and then subsequently re-added are always appended
to the end of the header list.
Return a list of 2-tuples containing all the message's field headers
and values. These will be sorted in the order in which they appeared
in the original message, or were added to the message, and may contain
duplicates. Any fields deleted and then subsequently re-added are
always appended to the end of the header list.
\end{methoddesc}
\begin{methoddesc}[Message]{get}{name\optional{, failobj}}
@ -215,10 +229,9 @@ Here are some additional useful methods:
\begin{methoddesc}[Message]{get_all}{name\optional{, failobj}}
Return a list of all the values for the field named \var{name}. These
will be sorted in the order in which they were added to the message
via \method{__setitem__()}. Any fields
deleted and then subsequently re-added are always appended to the end
of the list.
will be sorted in the order in which they appeared in the original
message, or were added to the message. Any fields deleted and then
subsequently re-added are always appended to the end of the list.
If there are no such named headers in the message, \var{failobj} is
returned (defaults to \code{None}).
@ -227,8 +240,8 @@ returned (defaults to \code{None}).
\begin{methoddesc}[Message]{add_header}{_name, _value, **_params}
Extended header setting. This method is similar to
\method{__setitem__()} except that additional header parameters can be
provided as keyword arguments. \var{_name} is the header to set and
\var{_value} is the \emph{primary} value for the header.
provided as keyword arguments. \var{_name} is the header field to add
and \var{_value} is the \emph{primary} value for the header.
For each item in the keyword argument dictionary \var{_params}, the
key is taken as the parameter name, with underscores converted to
@ -249,43 +262,84 @@ Content-Disposition: attachment; filename="bud.gif"
\end{verbatim}
\end{methoddesc}
\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
\begin{methoddesc}[Message]{replace_header}{_name, _value}
Replace a header. Replace the first header found in the message that
matches \var{_name}, retaining header order and field name case. If
no matching header was found, a \exception{KeyError} is raised.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_content_type}{}
Return the message's content type. The returned string is coerced to
lower case of the form \mimetype{maintype/subtype}. If there was no
\mailheader{Content-Type} header in the message the default type as
given by \method{get_default_type()} will be returned. Since
according to \rfc{2045}, messages always have a default type,
\method{get_content_type()} will always return a value.
\rfc{2045} defines a message's default type to be
\mimetype{text/plain} unless it appears inside a
\mimetype{multipart/digest} container, in which case it would be
\mimetype{message/rfc822}. If the \mailheader{Content-Type} header
has an invalid type specification, \rfc{2045} mandates that the
default type be \mimetype{text/plain}.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_content_maintype}{}
Return the message's main content type. This is the
\mimetype{maintype} part of the string returned by
\method{get_content_type()}.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_content_subtype}{}
Return the message's sub-content type. This is the \mimetype{subtype}
part of the string returned by \method{get_content_type()}.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_default_type}{}
Return the default content type. Most messages have a default content
type of \mimetype{text/plain}, except for messages that are subparts
of \mimetype{multipart/digest} containers. Such subparts have a
default content type of \mimetype{message/rfc822}.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{set_default_type}{ctype}
Set the default content type. \var{ctype} should either be
\mimetype{text/plain} or \mimetype{message/rfc822}, although this is
not enforced. The default content type is not stored in 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}).
\versionadded{2.2.2}
\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}.
\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}.
\end{methoddesc}
\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{, header}}}
\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{,
header\optional{, unquote}}}}
Return the message's \mailheader{Content-Type} parameters, as a list. The
elements of the returned list are 2-tuples of key/value pairs, as
split on the \character{=} sign. The left hand side of the
\character{=} is the key, while the right hand side is the value. If
there is no \character{=} sign in the parameter the value is the empty
string. The value is always unquoted with \method{Utils.unquote()}.
string, otherwise the value is as described in \method{get_param()} and is
unquoted if optional \var{unquote} is \code{True} (the default).
Optional \var{failobj} is the object to return if there is no
\mailheader{Content-Type} header. Optional \var{header} is the header to
search instead of \mailheader{Content-Type}.
\versionchanged[\var{unquote} argument added]{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_param}{param\optional{,
failobj\optional{, header}}}
failobj\optional{, header\optional{, unquote}}}}
Return the value of the \mailheader{Content-Type} header's parameter
\var{param} as a string. If the message has no \mailheader{Content-Type}
header or if there is no such parameter, then \var{failobj} is
@ -293,20 +347,80 @@ returned (defaults to \code{None}).
Optional \var{header} if given, specifies the message header to use
instead of \mailheader{Content-Type}.
Parameter keys are always compared case insensitively. The return
value can either be a string, or a 3-tuple if the parameter was
\rfc{2231} encoded. When it's a 3-tuple, the elements of the value are of
the form \samp{(CHARSET, LANGUAGE, VALUE)}, where \var{LANGUAGE} may
be the empty string. Your application should be prepared to deal with
3-tuple return values, which it can convert the parameter to a Unicode
string like so:
\begin{verbatim}
param = msg.get_param('foo')
if isinstance(param, tuple):
param = unicode(param[2], param[0])
\end{verbatim}
In any case, the parameter value (either the returned string, or the
\var{VALUE} item in the 3-tuple) is always unquoted, unless
\var{unquote} is set to \code{False}.
\versionchanged[\var{unquote} argument added, and 3-tuple return value
possible]{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_charsets}{\optional{failobj}}
Return a list containing the character set names in the message. If
the message is a \mimetype{multipart}, then the list will contain one
element for each subpart in the payload, otherwise, it will be a list
of length 1.
\begin{methoddesc}[Message]{set_param}{param, value\optional{,
header\optional{, requote\optional{, charset\optional{, language}}}}}
Each item in the list will be a string which is the value of the
\code{charset} parameter in the \mailheader{Content-Type} header for the
represented subpart. However, if the subpart has no
\mailheader{Content-Type} header, no \code{charset} parameter, or is not of
the \mimetype{text} main MIME type, then that item in the returned list
will be \var{failobj}.
Set a parameter in the \mailheader{Content-Type} header. If the
parameter already exists in the header, its value will be replaced
with \var{value}. If the \mailheader{Content-Type} header as not yet
been defined for this message, it will be set to \mimetype{text/plain}
and the new parameter value will be appended as per \rfc{2045}.
Optional \var{header} specifies an alternative header to
\mailheader{Content-Type}, and all parameters will be quoted as
necessary unless optional \var{requote} is \code{False} (the default
is \code{True}).
If optional \var{charset} is specified, the parameter will be encoded
according to \rfc{2231}. Optional \var{language} specifies the RFC
2231 language, defaulting to the empty string. Both \var{charset} and
\var{language} should be strings.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{del_param}{param\optional{, header\optional{,
requote}}}
Remove the given parameter completely from the
\mailheader{Content-Type} header. The header will be re-written in
place without the parameter or its value. All values will be quoted
as necessary unless \var{requote} is \code{False} (the default is
\code{True}). Optional \var{header} specifies an alterative to
\mailheader{Content-Type}.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{set_type}{type\optional{, header}\optional{,
requote}}
Set the main type and subtype for the \mailheader{Content-Type}
header. \var{type} must be a string in the form
\mimetype{maintype/subtype}, otherwise a \exception{ValueError} is
raised.
This method replaces the \mailheader{Content-Type} header, keeping all
the parameters in place. If \var{requote} is \code{False}, this
leaves the existing header's quoting as is, otherwise the parameters
will be quoted (the default).
An alternative header can be specified in the \var{header} argument.
When the \mailheader{Content-Type} header is set, we'll always also
add a \mailheader{MIME-Version} header.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
@ -340,6 +454,32 @@ However, it does \emph{not} preserve any continuation lines which may
have been present in the original \mailheader{Content-Type} header.
\end{methoddesc}
\begin{methoddesc}[Message]{get_content_charset}{\optional{failobj}}
Return the \code{charset} parameter of the \mailheader{Content-Type}
header. If there is no \mailheader{Content-Type} header, or if that
header has no \code{charset} parameter, \var{failobj} is returned.
Note that this method differs from \method{get_charset} which returns
the \class{Charset} instance for the default encoding of the message
body.
\versionadded{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Message]{get_charsets}{\optional{failobj}}
Return a list containing the character set names in the message. If
the message is a \mimetype{multipart}, then the list will contain one
element for each subpart in the payload, otherwise, it will be a list
of length 1.
Each item in the list will be a string which is the value of the
\code{charset} parameter in the \mailheader{Content-Type} header for the
represented subpart. However, if the subpart has no
\mailheader{Content-Type} header, no \code{charset} parameter, or is not of
the \mimetype{text} main MIME type, then that item in the returned list
will be \var{failobj}.
\end{methoddesc}
\begin{methoddesc}[Message]{walk}{}
The \method{walk()} method is an all-purpose generator which can be
used to iterate over all the parts and subparts of a message object
@ -380,7 +520,8 @@ the headers but before the first boundary string, it assigns this text
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.
text in the area between the headers and the first boundary. See
\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}.
@ -401,3 +542,59 @@ 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.
\end{datadesc}
\subsubsection{Deprecated methods}
The following methods are deprecated in \module{email} version 2.
They are documented here for completeness.
\begin{methoddesc}[Message]{add_payload}{payload}
Add \var{payload} to the message object's existing payload. If, prior
to calling this method, the object's payload was \code{None}
(i.e. never before set), then after this method is called, the payload
will be the argument \var{payload}.
If the object's payload was already a list
(i.e. \method{is_multipart()} returns 1), then \var{payload} is
appended to the end of the existing payload list.
For any other type of existing payload, \method{add_payload()} will
transform the new payload into a list consisting of the old payload
and \var{payload}, but only if the document is already a MIME
multipart document. This condition is satisfied if the message's
\mailheader{Content-Type} header's main type is either
\mimetype{multipart}, or there is no \mailheader{Content-Type}
header. In any other situation,
\exception{MultipartConversionError} is raised.
\deprecated{2.2.2}{Use the \method{attach()} method instead.}
\end{methoddesc}
\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}

159
Doc/lib/emailmimebase.tex Normal file
View File

@ -0,0 +1,159 @@
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 of
the message object structure. However you can also build a complete
object 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 \emph{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 \emph{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}

111
Doc/lib/emailparser.tex
View File

@ -1,20 +1,20 @@
\declaremodule{standard}{email.Parser}
\modulesynopsis{Parse flat text email messages to produce a message
object tree.}
object structure.}
Message object trees can be created in one of two ways: they can be
Message object structures can be created in one of two ways: they can be
created from whole cloth by instantiating \class{Message} objects and
stringing them together via \method{add_payload()} and
stringing them together via \method{attach()} and
\method{set_payload()} calls, or they can be created by parsing a flat text
representation of the email message.
The \module{email} package provides a standard parser that understands
most email document structures, including MIME documents. You can
pass the parser a string or a file object, and the parser will return
to you the root \class{Message} instance of the object tree. For
to you the root \class{Message} instance of the object structure. For
simple, non-MIME messages the payload of this root object will likely
be a string containing the text of the message. For MIME
messages, the root object will return true from its
messages, the root object will return \code{True} from its
\method{is_multipart()} method, and the subparts can be accessed via
the \method{get_payload()} and \method{walk()} methods.
@ -27,28 +27,46 @@ message object trees any way it finds necessary.
The primary parser class is \class{Parser} which parses both the
headers and the payload of the message. In the case of
\mimetype{multipart} messages, it will recursively parse the body of
the container message. 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 this 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.
the container message. Two modes of parsing are supported,
\emph{strict} parsing, which will usually reject any non-RFC compliant
message, and \emph{lax} parsing, which attempts to adjust for common
MIME formatting problems.
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.
\subsubsection{Parser class API}
\begin{classdesc}{Parser}{\optional{_class}}
The constructor for the \class{Parser} class takes a single optional
\begin{classdesc}{Parser}{\optional{_class\optional{, strict}}}
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
arguments.
The optional \var{strict} flag specifies whether strict or lax parsing
should be performed. Normally, when things like MIME terminating
boundaries are missing, or when messages contain other formatting
problems, the \class{Parser} will raise a
\exception{MessageParseError}. However, when lax parsing is enabled,
the \class{Parser} will attempt to workaround such broken formatting
to produce a usable message structure (this doesn't mean
\exception{MessageParseError}s are never raised; some ill-formatted
messages just can't be parsed). The \var{strict} flag defaults to
\code{False} since lax parsing usually provides the most convenient
behavior.
\versionchanged[The \var{strict} flag was added]{2.2.2}
\end{classdesc}
The other public \class{Parser} methods are:
\begin{methoddesc}[Parser]{parse}{fp}
\begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}}
Read all the data from the file-like object \var{fp}, parse the
resulting text, and return the root message object. \var{fp} must
support both the \method{readline()} and the \method{read()} methods
@ -56,32 +74,49 @@ on file-like objects.
The text contained in \var{fp} must be formatted as a block of \rfc{2822}
style headers and header continuation lines, optionally preceeded by a
\emph{Unix-From} header. The header block is terminated either by the
envelope header. The header block is terminated either by the
end of the data or by a blank line. Following the header block is the
body of the message (which may contain MIME-encoded subparts).
Optional \var{headersonly} is a flag specifying whether to stop
parsing after reading the headers or not. The default is \code{False},
meaning it parses the entire contents of the file.
\versionchanged[The \var{headersonly} flag was added]{2.2.2}
\end{methoddesc}
\begin{methoddesc}[Parser]{parsestr}{text}
\begin{methoddesc}[Parser]{parsestr}{text\optional{, headersonly}}
Similar to the \method{parse()} method, except it takes a string
object instead of a file-like object. Calling this method on a string
is exactly equivalent to wrapping \var{text} in a \class{StringIO}
instance first and calling \method{parse()}.
Optional \var{headersonly} is a flag specifying whether to stop
parsing after reading the headers or not. The default is \code{False},
meaning it parses the entire contents of the file.
\versionchanged[The \var{headersonly} flag was added]{2.2.2}
\end{methoddesc}
Since creating a message object tree from a string or a file object is
such a common task, two functions are provided as a convenience. They
are available in the top-level \module{email} package namespace.
Since creating a message object structure from a string or a file
object is such a common task, two functions are provided as a
convenience. They are available in the top-level \module{email}
package namespace.
\begin{funcdesc}{message_from_string}{s\optional{, _class}}
\begin{funcdesc}{message_from_string}{s\optional{, _class\optional{, strict}}}
Return a message object tree from a string. This is exactly
equivalent to \code{Parser().parsestr(s)}. Optional \var{_class} is
interpreted as with the \class{Parser} class constructor.
equivalent to \code{Parser().parsestr(s)}. Optional \var{_class} and
\var{strict} are interpreted as with the \class{Parser} class constructor.
\versionchanged[The \var{strict} flag was added]{2.2.2}
\end{funcdesc}
\begin{funcdesc}{message_from_file}{fp\optional{, _class}}
\begin{funcdesc}{message_from_file}{fp\optional{, _class\optional{, strict}}}
Return a message object tree from an open file object. This is exactly
equivalent to \code{Parser().parse(fp)}. Optional \var{_class} is
interpreted as with the \class{Parser} class constructor.
equivalent to \code{Parser().parse(fp)}. Optional \var{_class} and
\var{strict} are interpreted as with the \class{Parser} class constructor.
\versionchanged[The \var{strict} flag was added]{2.2.2}
\end{funcdesc}
Here's an example of how you might use this at an interactive Python
@ -99,15 +134,17 @@ Here are some notes on the parsing semantics:
\begin{itemize}
\item Most non-\mimetype{multipart} type messages are parsed as a single
message object with a string payload. These objects will return
0 for \method{is_multipart()}.
\item One exception is for \mimetype{message/delivery-status} type
messages. Because the body of such messages consist of
blocks of headers, \class{Parser} will create a non-multipart
object containing non-multipart subobjects for each header
block.
\item Another exception is for \mimetype{message/*} types (more
general than \mimetype{message/delivery-status}). These are
typically \mimetype{message/rfc822} messages, represented as a
non-multipart object containing a singleton payload which is
another non-multipart \class{Message} instance.
\code{False} for \method{is_multipart()}. Their
\method{get_payload()} method will return a string object.
\item All \mimetype{multipart} type messages will be parsed as a
container message object with a list of sub-message objects for
their payload. These messages will return \code{True} for
\method{is_multipart()} and their \method{get_payload()} method
will return a list of \class{Message} instances.
\item Most messages with a content type of \mimetype{message/*}
(e.g. \mimetype{message/deliver-status} and
\mimetype{message/rfc822}) will also be parsed as container
object containing a list payload of length 1. Their
\method{is_multipart()} method will return \code{True}. The
single element in the list payload will be a sub-message object.
\end{itemize}

68
Doc/lib/emailutil.tex
View File

@ -21,10 +21,10 @@ Parse address -- which should be the value of some address-containing
field such as \mailheader{To} or \mailheader{Cc} -- into its constituent
\emph{realname} and \emph{email address} parts. Returns a tuple of that
information, unless the parse fails, in which case a 2-tuple of
\code{(None, None)} is returned.
\code{('', '')} is returned.
\end{funcdesc}
\begin{funcdesc}{dump_address_pair}{pair}
\begin{funcdesc}{formataddr}{pair}
The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
\code{(realname, email_address)} and returns the string value suitable
for a \mailheader{To} or \mailheader{Cc} header. If the first element of
@ -48,27 +48,6 @@ all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{decode}{s}
This method decodes a string according to the rules in \rfc{2047}. It
returns the decoded string as a Python unicode string.
\end{funcdesc}
\begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
This method encodes a string according to the rules in \rfc{2047}. It
is not actually the inverse of \function{decode()} since it doesn't
handle multiple character sets or multiple string parts needing
encoding. In fact, the input string \var{s} must already be encoded
in the \var{charset} character set (Python can't reliably guess what
character set a string might be encoded in). The default
\var{charset} is \samp{iso-8859-1}.
\var{encoding} must be either the letter \character{q} for
Quoted-Printable or \character{b} for Base64 encoding. If
neither, a \exception{ValueError} is raised. Both the \var{charset} and
the \var{encoding} strings are case-insensitive, and coerced to lower
case in the returned string.
\end{funcdesc}
\begin{funcdesc}{parsedate}{date}
Attempts to parse a date according to the rules in \rfc{2822}.
however, some mailers don't follow that format as specified, so
@ -116,7 +95,48 @@ Optional \var{timeval} if given is a floating point time value as
accepted by \function{time.gmtime()} and \function{time.localtime()},
otherwise the current time is used.
Optional \var{localtime} is a flag that when true, interprets
Optional \var{localtime} is a flag that when \code{True}, interprets
\var{timeval}, and returns a date relative to the local timezone
instead of UTC, properly taking daylight savings time into account.
The default is \code{False} meaning UTC is used.
\end{funcdesc}
\begin{funcdesc}{make_msgid}{\optional{idstring}}
Returns a string suitable for an \rfc{2822}-compliant
\mailheader{Message-ID} header. Optional \var{idstring} if given, is
a string used to strengthen the uniqueness of the message id.
\end{funcdesc}
\begin{funcdesc}{decode_rfc2231}{s}
Decode the string \var{s} according to \rfc{2231}.
\end{funcdesc}
\begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}}
Encode the string \var{s} according to \rfc{2231}. Optional
\var{charset} and \var{language}, if given is the character set name
and language name to use. If neither is given, \var{s} is returned
as-is. If \var{charset} is given but \var{language} is not, the
string is encoded using the empty string for \var{language}.
\end{funcdesc}
\begin{funcdesc}{decode_params}{params}
Decode parameters list according to \rfc{2231}. \var{params} is a
sequence of 2-tuples containing elements of the form
\code{(content-type, string-value)}.
\end{funcdesc}
The following functions have been deprecated:
\begin{funcdesc}{dump_address_pair}{pair}
\deprecated{2.2.2}{Use \function{formataddr()} instead.}
\end{funcdesc}
\begin{funcdesc}{decode}{s}
\deprecated{2.2.2}{Use \method{Header.decode_header()} instead.}
\end{funcdesc}
\begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
\deprecated{2.2.2}{Use \method{Header.encode()} instead.}
\end{funcdesc}