diff options
Diffstat (limited to 'Doc/lib/emailmessage.tex')
| -rw-r--r-- | Doc/lib/emailmessage.tex | 561 |
1 files changed, 0 insertions, 561 deletions
diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex deleted file mode 100644 index 7bd7dd8..0000000 --- a/Doc/lib/emailmessage.tex +++ /dev/null @@ -1,561 +0,0 @@ -\declaremodule{standard}{email.message} -\modulesynopsis{The base class representing email messages.} - -The central class in the \module{email} package is the -\class{Message} class, imported from the \module{email.message} module. It is -the base class for the \module{email} object model. \class{Message} provides -the core functionality for setting and querying header fields, and for -accessing message bodies. - -Conceptually, a \class{Message} object consists of \emph{headers} and -\emph{payloads}. Headers are \rfc{2822} style field names and -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 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 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 -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{classdesc}{Message}{} -The constructor takes no arguments. -\end{classdesc} - -\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}} -Return the entire message flatten as a string. When optional -\var{unixfrom} is \code{True}, the envelope header is included in the -returned string. \var{unixfrom} defaults to \code{False}. - -Note that this method is provided as a convenience and may not always format -the message the way you want. For example, by default it mangles lines that -begin with \code{From }. For more flexibility, instantiate a -\class{Generator} instance and use its -\method{flatten()} method directly. For example: - -\begin{verbatim} -from cStringIO import StringIO -from email.generator import Generator -fp = StringIO() -g = Generator(fp, mangle_from_=False, maxheaderlen=60) -g.flatten(msg) -text = fp.getvalue() -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[Message]{__str__}{} -Equivalent to \method{as_string(unixfrom=True)}. -\end{methoddesc} - -\begin{methoddesc}[Message]{is_multipart}{} -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 message's envelope header to \var{unixfrom}, which should be a string. -\end{methoddesc} - -\begin{methoddesc}[Message]{get_unixfrom}{} -Return the message's envelope header. Defaults to \code{None} if the -envelope header was never set. -\end{methoddesc} - -\begin{methoddesc}[Message]{attach}{payload} -Add the given \var{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 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 argument \var{i}, \method{get_payload()} will return the -\var{i}-th element of the payload, counting from zero, if -\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 \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, or if the payload has bogus base64 data, the payload is -returned as-is (undecoded). If the message is 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\optional{, charset}} -Set the entire message object's payload to \var{payload}. It is the -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 -\var{charset.input_charset}. It will be converted to -\var{charset.output_charset} -and encoded properly, if needed, when generating the plain text -representation of the message. MIME headers -(\mailheader{MIME-Version}, \mailheader{Content-Type}, -\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 -the message'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, headers are always -returned in the order they appeared in the original message, or were -added to the message later. Any header deleted and then re-added are -always appended to the end of the header list. - -These semantic differences are intentional and are biased toward -maximal convenience. - -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. -\end{methoddesc} - -\begin{methoddesc}[Message]{__contains__}{name} -Return true if the message object has a field named \var{name}. -Matching 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 \exception{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}, delete the field first, 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 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. -\end{methoddesc} - -\begin{methoddesc}[Message]{values}{} -Return a list of all the message's field values. -\end{methoddesc} - -\begin{methoddesc}[Message]{items}{} -Return a list of 2-tuples containing all the message's field headers -and values. -\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}. -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 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 -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]{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. - -\versionadded{2.2.2} -\end{methoddesc} - -\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, 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\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 -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 \code{(CHARSET, LANGUAGE, VALUE)}. Note that both \code{CHARSET} and -\code{LANGUAGE} can be \code{None}, in which case you should consider -\code{VALUE} to be encoded in the \code{us-ascii} charset. You can -usually ignore \code{LANGUAGE}. - -If your application doesn't care whether the parameter was encoded as in -\rfc{2231}, you can collapse the parameter value by calling -\function{email.Utils.collapse_rfc2231_value()}, passing in the return value -from \method{get_param()}. This will return a suitably decoded Unicode string -whn the value is a tuple, or the original string unquoted if it isn't. For -example: - -\begin{verbatim} -rawparam = msg.get_param('foo') -param = email.Utils.collapse_rfc2231_value(rawparam) -\end{verbatim} - -In any case, the parameter value (either the returned string, or the -\code{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]{set_param}{param, value\optional{, - header\optional{, requote\optional{, charset\optional{, language}}}}} - -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 alternative 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 a -\mailheader{MIME-Version} header is also added. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_filename}{\optional{failobj}} -Return the value of the \code{filename} parameter of the -\mailheader{Content-Disposition} header of the message. If the header does -not have a \code{filename} parameter, this method falls back to looking for -the \code{name} parameter. If neither is found, or the header is missing, -then \var{failobj} is returned. 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 -\mailheader{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 \mailheader{Content-Type} -header to \var{boundary}. \method{set_boundary()} will always quote -\var{boundary} if necessary. A \exception{HeaderParseError} is raised -if the message object has no \mailheader{Content-Type} header. - -Note that using this method is subtly different than deleting the old -\mailheader{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 \mailheader{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 \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, coerced to lower case. 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 -tree, in depth-first traversal order. You will typically use -\method{walk()} as the iterator in a \code{for} loop; each -iteration returns the next subpart. - -Here's an example that prints the MIME type of every part of a -multipart message structure: - -\begin{verbatim} ->>> for part in msg.walk(): -... print part.get_content_type() -multipart/report -text/plain -message/delivery-status -text/plain -text/plain -message/rfc822 -\end{verbatim} -\end{methoddesc} - -\versionchanged[The previously deprecated methods \method{get_type()}, -\method{get_main_type()}, and \method{get_subtype()} were removed]{2.5} - -\class{Message} objects can also optionally contain two instance -attributes, which can be used when generating the plain text of a MIME -message. - -\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. 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}. -\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. - -\versionchanged[You do not need to set the epilogue to the empty string in -order for the \class{Generator} to print a newline at the end of the -file]{2.5} -\end{datadesc} - -\begin{datadesc}{defects} -The \var{defects} attribute contains a list of all the problems found when -parsing this message. See \refmodule{email.errors} for a detailed description -of the possible parsing defects. - -\versionadded{2.4} -\end{datadesc} |