12.3.1 The mimelib.Message class

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:

ismultipart ()
Return 1 if the payload is a list of sub-Message objects, otherwise return 0 (implying that the payload is a simple string object).

set_unixfrom (unixfrom)
Set the ``Unix-From'' (a.k.a envelope header or From_ header) to unixfrom, which should be a string.

get_unixfrom ()
Return the ``Unix-From'' header. Defaults to None if the ``Unix-From'' header was never set.

add_payload (payload)
Add payload to the message object's existing payload. If, prior to calling this method, the object's payload was 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.

get_payload ([i])
Return the current payload, which will be a list when ismultipart() returns 1, or a scalar (hopefully a string0 when ismultipart() returns 0.

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.

set_payload (payload)
Set the entire message object's payload to payload.

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.

__len__ ()
Return the total number of headers, including duplicates.

__getitem__ (name)
Return the value of the named header field. name should not include the colon field separator. If the header is missing, 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.

__setitem__ (name, val)
Add a header to the message with field name name and value val. The field is appended to the end of the message's 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.

__delitem__ (name)
Delete all occurrences of the field with name name from the message's headers. No exception is raised if the named field isn't present in the headers.

has_key (name)
Return 1 if the message contains a header field named name, otherwise return 0.

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 __setitem__(), and may contain duplicates. Any fields deleted and then subsequently re-added are always appended to the end of the header list.

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 __setitem__(), and may contain duplicates. Any fields deleted and then subsequently re-added are always appended to the end of the header list.

items ()
Return a list of 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 __setitem__(), and may contain duplicates. Any fields deleted and then subsequently re-added are always appended to the end of the header list.

get (name[, failobj])
Return the value of the named header field. This is identical to __getitem__() except that optional failobj is returned if the named header is missing (defaults to None).

Here are some additional useful methods:

getall (name[, failobj])
Return a list of all the values for the field named name. These will be sorted in the order in which they were added to the message via __setitem__(), and may contain duplicates. Any fields deleted and then subsequently re-added are always appended to the end of the header list.

If there are no such named headers in the message, failobj is returned (defaults to None).

addheader (_name, _value, **_params)
Extended header setting. This method is similar to __setitem__() except that additional header parameters can be provided as keyword arguments. _name is the header to set and _value is the ``primary'' value for the header.

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"

gettype ([failobj])
Return the message's content type, as a string of the form ``maintype/subtype'' as taken from the 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).

getmaintype ([failobj])
Return the message's main content type. This essentially returns the ``maintype'' part of the string returned by gettype(), with the same semantics for failobj.

getsubtype ([failobj])
Return the message's sub-content type. This essentially returns the ``subtype'' part of the string returned by gettype(), with the same semantics for failobj.

getparams ([failobj])
Return the field parameters for the Content-Type: header as a list of strings. If the message has no Content-Type: header, then failobj is returned (defaults to None).

getparam (param[, failobj])
Return the value of the 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.