The email package documentation, currently organized the way I think

Fred prefers.  I'm not sure I like this organization, so it may change.

1 files changed, 384 insertions, 0 deletions

diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex
new file mode 100644
index 0000000..bc9c0ce
--- /dev/null
+++ b/Doc/lib/emailmessage.tex
@@ -0,0 +1,384 @@
+\section{\module{email.Message} ---
+         The Message class}
+
+\declaremodule{standard}{email.Message}
+\modulesynopsis{The base class representing email messages.}
+\sectionauthor{Barry A. Warsaw}{barry@zope.com}
+
+\versionadded{2.2}
+
+The \module{Message} module provides a single class, the
+\class{Message} class.  This class is the base class for the
+\module{email} package object model.  It has a fairly extensive set of
+methods to get and set email headers and email payloads.  For an
+introduction of the \module{email} package, please read the
+\refmodule{email} package overview.
+
+\class{Message} instances can be created either directly, or
+indirectly by using a \refmodule{email.Parser}.  \class{Message}
+objects provide a mapping style interface for accessing the message
+headers, and an explicit interface for accessing both the headers and
+the payload.  It provides convenience methods for generating a flat
+text representation of the message object tree, for accessing commonly
+used header parameters, and for recursively walking over the object
+tree.
+
+Here are the methods of the \class{Message} class:
+
+\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.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__str__()}{}
+Equivalent to \method{aMessage.as_string(unixfrom=1)}.
+\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.
+\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.
+\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
+\code{Content-Type:} header's main type is either \var{multipart}, or
+there is no \code{Content-Type:} header.  In any other situation,
+\exception{MultipartConversionError} is raised.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{attach}{payload}
+Synonymous with \method{add_payload()}.
+\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.
+
+With optional \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 \code{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
+\code{TypeError} is raised.
+
+Optional \var{decode} is a flag indicating whether the payload should be
+decoded or not, according to the \code{Content-Transfer-Encoding:} header.
+When 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
+\code{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.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_payload}{payload}
+Set the entire message object's payload to \var{payload}.  It is the
+client's responsibility to ensure the payload invariants.
+\end{methoddesc}
+
+The following methods implement a mapping-like interface for accessing
+the message object's \rfc{2822} headers.  Note that there are some
+semantic differences between these methods and a normal mapping
+(i.e. dictionary) interface.  For example, in a dictionary there are
+no duplicate keys, but here there may be duplicate message headers.  Also,
+in dictionaries there is no guaranteed order to the keys returned by
+\method{keys()}, but in a \class{Message} object, there is an explicit
+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.
+
+\begin{methoddesc}[Message]{__len__}{}
+Return the total number of headers, including duplicates.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__contains__}{name}
+Return true if the message object has a field named \var{name}.
+Match is done case-insensitively and \var{name} should not include the
+trailing colon.  Used for the \code{in} operator,
+e.g.:
+
+\begin{verbatim}
+if 'message-id' in myMessage:
+    print 'Message-ID:', myMessage['message-id']
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__getitem__}{name}
+Return the value of the named header field.  \var{name} should not
+include the colon field separator.  If the header is missing,
+\code{None} is returned; a \code{KeyError} is never raised.
+
+Note that if the named field appears more than once in the message's
+headers, exactly which of those field values will be returned is
+undefined.  Use the \method{get_all()} method to get the values of all
+the extant named headers.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__setitem__}{name, val}
+Add a header to the message with field name \var{name} and value
+\var{val}.  The field is appended to the end of the message's existing
+fields.
+
+Note that this does \emph{not} overwrite or delete any existing header
+with the same name.  If you want to ensure that the new header is the
+only one present in the message with field name
+\var{name}, first use \method{__delitem__()} to delete all named
+fields, e.g.:
+
+\begin{verbatim}
+del msg['subject']
+msg['subject'] = 'Python roolz!'
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__delitem__}{name}
+Delete all occurrences of the field with name \var{name} from the
+message's headers.  No exception is raised if the named field isn't
+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.
+\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.
+\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.
+\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.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get}{name\optional{, failobj}}
+Return the value of the named header field.  This is identical to
+\method{__getitem__()} except that optional \var{failobj} is returned
+if the named header is missing (defaults to \code{None}).
+\end{methoddesc}
+
+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.
+
+If there are no such named headers in the message, \var{failobj} is
+returned (defaults to \code{None}).
+\end{methoddesc}
+
+\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.
+
+For each item in the keyword argument dictionary \var{_params}, the
+key is taken as the parameter name, with underscores converted to
+dashes (since dashes are illegal in Python identifiers).  Normally,
+the parameter will be added as \code{key="value"} unless the value is
+\code{None}, in which case only the key will be added.
+
+Here's an example:
+
+\begin{verbatim}
+msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+\end{verbatim}
+
+This will add a header that looks like
+
+\begin{verbatim}
+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
+``maintype/subtype'' as taken from the \code{Content-Type:} header.
+The returned string is coerced to lowercase.
+
+If there is no \code{Content-Type:} header in the message,
+\var{failobj} is returned (defaults to \code{None}).
+\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}}}
+Return the message's \code{Content-Type:} parameters, as a list.  The
+elements of the returned list are 2-tuples of key/value pairs, as
+split on the \samp{=} sign.  The left hand side of the \samp{=} is the
+key, while the right hand side is the value.  If there is no \samp{=}
+sign in the parameter the value is the empty string.  The value is
+always unquoted with \method{Utils.unquote()}.
+
+Optional \var{failobj} is the object to return if there is no
+\code{Content-Type:} header.  Optional \var{header} is the header to
+search instead of \code{Content-Type:}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_param}{param\optional{,
+    failobj\optional{, header}}}
+Return the value of the \code{Content-Type:} header's parameter
+\var{param} as a string.  If the message has no \code{Content-Type:}
+header or if there is no such parameter, then \var{failobj} is
+returned (defaults to \code{None}).
+
+Optional \var{header} if given, specifies the message header to use
+instead of \code{Content-Type:}.
+\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 \code{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 \code{Content-Type:} header for the
+represented subpart.  However, if the subpart has no
+\code{Content-Type:} header, no \code{charset} parameter, or is not of
+the \code{text} main MIME type, then that item in the returned list
+will be \var{failobj}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
+Return the value of the \code{filename} parameter of the
+\code{Content-Disposition:} header of the message, or \var{failobj} if
+either the header is missing, or has no \code{filename} parameter.
+The returned string will always be unquoted as per
+\method{Utils.unquote()}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_boundary}{\optional{failobj}}
+Return the value of the \code{boundary} parameter of the
+\code{Content-Type:} header of the message, or \var{failobj} if either
+the header is missing, or has no \code{boundary} parameter.  The
+returned string will always be unquoted as per
+\method{Utils.unquote()}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_boundary}{boundary}
+Set the \code{boundary} parameter of the \code{Content-Type:} header
+to \var{boundary}.  \method{set_boundary()} will always quote
+\var{boundary} so you should not quote it yourself.  A
+\code{HeaderParseError} is raised if the message object has no
+\code{Content-Type:} header.
+
+Note that using this method is subtly different than deleting the old
+\code{Content-Type:} header and adding a new one with the new boundary
+via \method{add_header()}, because \method{set_boundary()} preserves the
+order of the \code{Content-Type:} header in the list of headers.
+However, it does \emph{not} preserve any continuation lines which may
+have been present in the original \code{Content-Type:} header.
+\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
+tree, in depth-first traversal order.  You will typically use
+\method{walk()} as the iterator in a \code{for ... in} loop; each
+iteration returns the next subpart.
+
+Here's an example that prints the MIME type of every part of a message
+object tree:
+
+\begin{verbatim}
+>>> for part in msg.walk():
+>>>     print part.get_type('text/plain')
+multipart/report
+text/plain
+message/delivery-status
+text/plain
+text/plain
+message/rfc822
+\end{verbatim}
+\end{methoddesc}
+
+\class{Message} objects can also optionally contain two instance
+attributes, which can be used when generating the plain text of a MIME
+message.
+
+\begin{datadesc}{preamble}
+The format of a MIME document allows for some text between the blank
+line following the headers, and the first multipart boundary string.
+Normally, this text is never visible in a MIME-aware mail reader
+because it falls outside the standard MIME armor.  However, when
+viewing the raw text of the message, or when viewing the message in a
+non-MIME aware reader, this text can become visible.
+
+The \var{preamble} attribute contains this leading extra-armor text
+for MIME documents.  When the \class{Parser} discovers some text after
+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.
+
+Note that if the message object has no preamble, the
+\var{preamble} attribute will be \code{None}.
+\end{datadesc}
+
+\begin{datadesc}{epilogue}
+The \var{epilogue} attribute acts the same way as the \var{preamble}
+attribute, except that it contains text that appears between the last
+boundary and the end of the message.
+\end{datadesc}