12.3.6 Auxiliary utilities

There are several useful utilities provided with the mimelib package.

MsgReader (rootmsg)
This class (imported from the mimelib.MsgReader module, provides a file-like interface to a message object tree. Actually, at the moment it only provides a limited subset of file methods, but more may be added in the future. It's primary purpose is to enable line-by-line iteration over the textual representation of the message object tree, without having to flatten it with a Generator first.

rootmsg is the root of the object tree to iterate line-by-line over.

readline ()
Return the next line from as would be read from the flattened text representation of the message object tree. Like ``standard'' readline(), this returns the empty string when the end of the message object tree is reached. Note that message headers are not included in the line-by-line iteration, only the payloads and recursively, the payloads of the sub-objects in a depth-first traversal.

The mimelib.address module exports some of the more useful address parsing related functions from rfc822. They are mostly provided for convenience.

quote (str)
Replaces backslashes in str with two backslashes and replaces double quotes with backslash-double quote.

unquote (str)
If str ends and begins with double quotes, they are stripped off. Likewise if str ends and begins with angle brackets, they are stripped off.

parseaddr (address)
Parse address - which should be the value of some address-containing field such as To: or Cc: - into its constituent ``realname'' and ``email address'' parts. Returns a tuple of that information, unless the parse fails, in which case a 2-tuple of (None, None) is returned.

dump_address_pair (pair)
The inverse of parseaddr(), this takes a 2-tuple of the form (realname, email_address) and returns the string value suitable for a To: or Cc: header. If the first element of pair is false, then the second element is returned unmodified.

Module address also provides the following useful function:

getaddresses (fieldvalues)
This method returns a list of 2-tuples of the form returned by parseaddr(). fieldvalues is a sequence of header field values as might be returned by Message.getall(). Here's a simple example that gets all the recipients of a message:

from mimelib.address import getaddresses

tos = msg.getall('to')
ccs = msg.getall('cc')
resent_tos = msg.getall('resent-to')
resent_ccs = msg.getall('resent-cc')
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

The mimelib.date module exports some other useful date related functions from rfc822. They are mostly provided for convenience.

parsedate (date)
Attempts to parse a date according to the rules in RFC 822. however, some mailers don't follow that format as specified, so parsedate() tries to guess correctly in such cases. date is a string containing an RFC 822 date, such as 'Mon, 20 Nov 1995 19:12:08 -0500'. If it succeeds in parsing the date, parsedate() returns a 9-tuple that can be passed directly to time.mktime(); otherwise None will be returned. Note that fields 6, 7, and 8 of the result tuple are not usable.

parsedate_tz (date)
Performs the same function as parsedate(), but returns either None or a 10-tuple; the first 9 elements make up a tuple that can be passed directly to time.mktime(), and the tenth is the offset of the date's timezone from UTC (which is the official term for Greenwich Mean Time). (Note that the sign of the timezone offset is the opposite of the sign of the time.timezone variable for the same timezone; the latter variable follows the POSIX standard while this module follows RFC 822.) If the input string has no timezone, the last element of the tuple returned is None. Note that fields 6, 7, and 8 of the result tuple are not usable.

mktime_tz (tuple)
Turn a 10-tuple as returned by parsedate_tz() into a UTC timestamp. It the timezone item in the tuple is None, assume local time. Minor deficiency: this first interprets the first 8 elements as a local time and then compensates for the timezone difference; this may yield a slight error around daylight savings time switch dates. Not enough to worry about for common use.

formatdate ([timeval])
Returns the time formatted as per Internet standards RFC 822 and updated by RFC 1123. If timeval is provided, then it should be a floating point time value as expected by time.gmtime(), otherwise the current time is used.

See About this document... for information on suggesting changes.