diff options
Diffstat (limited to 'Doc/lib/emailmessage.tex')
| -rw-r--r-- | Doc/lib/emailmessage.tex | 384 |
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} |