The mimelib.Message class (hereafter referred to simply as Message) is the base class for the mimelib object model. It provides the core functionality for setting and querying header fields, and for accessing message bodies. It knows nothing about parsing or generating MIME flat text documents.
Conceptually, a Message object consists of headers and
payloads. Headers are all normal the RFC 822 style header and
values. Headers are stored and returned in case-preserving form but
are matched case-insensitively. There may also be a single
``Unix-From'' header, also known as the envelope 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 more
complex MIME documents.
Message objects provide a mapping style interface for accessing the message headers, and an explicit interface for accessing both the headers and the payload. Here are the methods of the Message class:
From_
header)
to unixfrom, which should be a string.
None
if the
``Unix-From'' header was never set.
None
(i.e. never before set), then after this method is called, the payload
will be a scalar. In other words, ismultipart() would return
0.
If however the object's payload was already a scalar, its payload is transformed into a list, such that ismultipart() would then return 1. If the payload was already a list, then payload is simply appended to the end of the existing payload list.
With optional i, get_payload() will return the
i-th element of the payload, if ismultipart() returns
0. An IndexError
will be raised if i is less than 0 or
greater than the number of items in the payload. If the payload is
scalar (i.e. ismultipart() returns 0) and i is given, a
TypeError
is raised.
The following methods implement a mapping-like interface for accessing the message object's RFC 822 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 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, there is an explicit order. These semantic differences are intentional and are biased toward maximal convenience.
Note that in all cases, any optional ``Unix-From'' header the message may have is not included in the mapping interface.
None
is returned instead of raising a KeyError
.
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 getall() 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 headers is the only one present in the message with field name name, first use __delitem__() to delete all named headers.
None
).
Here are some additional useful methods:
If there are no such named headers in the message, failobj is
returned (defaults to 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.addheader('Content-Disposition', 'attachment', filename='bud.gif')
This will add a header that looks like
Content-Disposition: attachment; filename="bud.gif"
Content-Type:
header.
The returned string is coerced to lowercase.
If there is no Content-Type:
header in the message,
failobj is returned (defaults to None
).
Content-Type:
header as a
list of strings. If the message has no Content-Type:
header,
then failobj is returned (defaults to None
).
Content-Type:
header's name
parameter as a string. If the message has no Content-Type:
header or if there is no name parameter, then failobj is
returned (defaults to None
).
See About this document... for information on suggesting changes.