 |
 |
 |
Python Library Reference |  |
 |
 |
The central class in the email package is the Message class; it is the base class for the email object model. Message provides the core functionality for setting and querying header fields, and for accessing message bodies.
Conceptually, a Message object consists of headers and 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 Unix-From header or the
From_ header. The payload is either a string in the case of
simple message objects or a list of Message objects for
MIME container documents (e.g. multipart/* and
message/rfc822).
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 Message class:
True, the envelope header is included in the
returned string. unixfrom defaults to False.
True if the message's payload is a list of
sub-Message objects, otherwise return False. When
is_multipart() returns False, the payload should be a string
object.
None if the
envelope header was never set.
None or a list of Message objects before the call.
After the call, the payload will always be a list of Message
objects. If you want to set the payload to a scalar object (e.g. a
string), use set_payload() instead.
True, or a
string when is_multipart() is False. If the
payload is a list and you mutate the list object, you modify the
message's payload in place.
With optional argument i, get_payload() will return the
i-th element of the payload, counting from zero, if
is_multipart() is True. An IndexError
will be raised if 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. is_multipart() is False) and i is given, a
TypeError is raised.
Optional decode is a flag indicating whether the payload should be
decoded or not, according to the Content-Transfer-Encoding: header.
When True and the message is not a multipart, the payload will be
decoded if this header's value is "quoted-printable" or
"base64". If some other encoding is used, or
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
decode flag is True, then None is returned. The
default for decode is False.
Changed in version 2.2.2: charset argument added.
None. If it is a string, it will be converted to a
Charset instance. If charset is None, the
charset parameter will be removed from the
Content-Type: header. Anything else will generate a
TypeError.
The message will be assumed to be of type text/* encoded with
charset.input_charset. It will be converted to
charset.output_charset
and encoded properly, if needed, when generating the plain text
representation of the message. MIME headers
(MIME-Version:, Content-Type:,
Content-Transfer-Encoding:) will be added as needed.
New in version 2.2.2.
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 keys(), but in a 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.
in operator,
e.g.:
if 'message-id' in myMessage:
print 'Message-ID:', myMessage['message-id']
None is returned; a 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 get_all() method to get the values of all the extant named headers.
Note that this does 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 name, delete the field first, e.g.:
del msg['subject'] msg['subject'] = 'Python roolz!'
None).
Here are some additional useful methods:
None).
For each item in the keyword argument dictionary _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 key="value" unless the value is
None, in which case only the key will be added.
Here's an example:
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
This will add a header that looks like
Content-Disposition: attachment; filename="bud.gif"
New in version 2.2.2.
RFC 2045 defines a message's default type to be text/plain unless it appears inside a multipart/digest container, in which case it would be message/rfc822. If the Content-Type: header has an invalid type specification, RFC 2045 mandates that the default type be text/plain.
New in version 2.2.2.
New in version 2.2.2.
New in version 2.2.2.
New in version 2.2.2.
New in version 2.2.2.
True (the default).
Optional failobj is the object to return if there is no Content-Type: header. Optional header is the header to search instead of Content-Type:.
Changed in version 2.2.2: unquote argument added.
None).
Optional header if given, specifies the message header to use instead of 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 (CHARSET, LANGUAGE, VALUE), where LANGUAGE may
be the empty string. Your application should be prepared to deal with
3-tuple return values, which it can convert to a Unicode string like
so:
param = msg.get_param('foo')
if isinstance(param, tuple):
param = unicode(param[2], param[0])
In any case, the parameter value (either the returned string, or the
VALUE item in the 3-tuple) is always unquoted, unless
unquote is set to False.
Changed in version 2.2.2: unquote argument added, and 3-tuple return value possible.
Set a parameter in the Content-Type: header. If the parameter already exists in the header, its value will be replaced with value. If the Content-Type: header as not yet been defined for this message, it will be set to text/plain and the new parameter value will be appended as per RFC 2045.
Optional header specifies an alternative header to
Content-Type:, and all parameters will be quoted as
necessary unless optional requote is False (the default
is True).
If optional charset is specified, the parameter will be encoded according to RFC 2231. Optional language specifies the RFC 2231 language, defaulting to the empty string. Both charset and language should be strings.
New in version 2.2.2.
False (the default is
True). Optional header specifies an alternative to
Content-Type:.
New in version 2.2.2.
This method replaces the Content-Type: header, keeping all
the parameters in place. If requote is 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 header argument. When the Content-Type: header is set a MIME-Version: header is also added.
New in version 2.2.2.
filename parameter of the
Content-Disposition: header of the message, or failobj if
either the header is missing, or has no filename parameter.
The returned string will always be unquoted as per
Utils.unquote().
boundary parameter of the
Content-Type: header of the message, or failobj if either
the header is missing, or has no boundary parameter. The
returned string will always be unquoted as per
Utils.unquote().
boundary parameter of the Content-Type:
header to boundary. set_boundary() will always quote
boundary if necessary. A HeaderParseError is raised
if the message object has no Content-Type: header.
Note that using this method is subtly different than deleting the old Content-Type: header and adding a new one with the new boundary via add_header(), because set_boundary() preserves the order of the Content-Type: header in the list of headers. However, it does not preserve any continuation lines which may have been present in the original Content-Type: header.
charset parameter of the Content-Type:
header, coerced to lower case. If there is no
Content-Type: header, or if that header has no
charset parameter, failobj is returned.
Note that this method differs from get_charset() which returns the Charset instance for the default encoding of the message body.
New in version 2.2.2.
Each item in the list will be a string which is the value of the
charset parameter in the Content-Type: header for the
represented subpart. However, if the subpart has no
Content-Type: header, no charset parameter, or is not of
the text main MIME type, then that item in the returned list
will be failobj.
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:
>>> for part in msg.walk(): >>> print part.get_content_type() multipart/report text/plain message/delivery-status text/plain text/plain message/rfc822
Message objects can also optionally contain two instance attributes, which can be used when generating the plain text of a MIME message.
The preamble attribute contains this leading extra-armor text for MIME documents. When the Parser discovers some text after the headers but before the first boundary string, it assigns this text to the message's preamble attribute. When the Generator is writing out the plain text representation of a MIME message, and it finds the message has a preamble attribute, it will write this text in the area between the headers and the first boundary. See email.Parser and email.Generator for details.
Note that if the message object has no preamble, the
preamble attribute will be None.
One note: when generating the flat text for a multipart message that has no epilogue (using the standard Generator class), no newline is added after the closing boundary line. If the message object has an epilogue and its value does not start with a newline, a newline is printed after the closing boundary. This seems a little clumsy, but it makes the most practical sense. The upshot is that if you want to ensure that a newline get printed after your closing multipart boundary, set the epilogue to the empty string.
|
|
|
Python Library Reference | |
|
|