11.10 imaplib -- IMAP4 protocol client

# 11.10 `imaplib` -- IMAP4 protocol client

This module defines three classes, `IMAP4`, `IMAP4_SSL` and `IMAP4_stream`, which encapsulate a connection to an IMAP4 server and implement a large subset of the IMAP4rev1 client protocol as defined in RFC 2060. It is backward compatible with IMAP4 (RFC 1730) servers, but note that the "`STATUS`" command is not supported in IMAP4.

Three classes are provided by the `imaplib` module, `IMAP4` is the base class:

class `IMAP4`( | [host[, port]])

  This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If host is not specified, `''` (the local host) is used. If port is omitted, the standard IMAP4 port (143) is used.

Three exceptions are defined as attributes of the `IMAP4` class:

exception `IMAP4.error`
  Exception raised on any errors. The reason for the exception is passed to the constructor as a string.

exception `IMAP4.abort`
  IMAP4 server errors cause this exception to be raised. This is a sub-class of `IMAP4.error`. Note that closing the instance and instantiating a new one will usually allow recovery from this exception.

exception `IMAP4.readonly`
  This exception is raised when a writable mailbox has its status changed by the server. This is a sub-class of `IMAP4.error`. Some other client now has write permission, and the mailbox will need to be re-opened to re-obtain write permission.

There's also a subclass for secure connections:

class `IMAP4_SSL`( | [host[, port[, keyfile[, certfile]]]])

  This is a subclass derived from `IMAP4` that connects over an SSL encrypted socket (to use this class you need a socket module that was compiled with SSL support). If host is not specified, `''` (the local host) is used. If port is omitted, the standard IMAP4-over-SSL port (993) is used. keyfile and certfile are also optional - they can contain a PEM formatted private key and certificate chain file for the SSL connection.

The second subclass allows for connections created by a child process:

class `IMAP4_stream`( | command)

  This is a subclass derived from `IMAP4` that connects to the `stdin/stdout` file descriptors created by passing command to `os.popen2()`. New in version 2.3.

The following utility functions are defined:

`Internaldate2tuple`( | datestr)

  Converts an IMAP4 INTERNALDATE string to Coordinated Universal Time. Returns a `time` module tuple.

`Int2AP`( | num)

  Converts an integer into a string representation using characters from the set [`A` .. `P`].

`ParseFlags`( | flagstr)

  Converts an IMAP4 "`FLAGS`" response to a tuple of individual flags.

`Time2Internaldate`( | date_time)

  Converts a `time` module tuple to an IMAP4 "`INTERNALDATE`" representation. Returns a string in the form: `"DD-Mmm-YYYY HH:MM:SS +HHMM"` (including double-quotes).

Note that IMAP4 message numbers change as the mailbox changes; in particular, after an "`EXPUNGE`" command performs deletions the remaining messages are renumbered. So it is highly advisable to use UIDs instead, with the UID command.

At the end of the module, there is a test section that contains a more extensive example of usage.

See Also:

Documents describing the protocol, and sources and binaries for servers implementing it, can all be found at the University of Washington's IMAP Information Center (http://www.cac.washington.edu/imap/).