Doc/lib/libimaplib.tex

\section{\module{imaplib} ---
         IMAP4 protocol client}

\declaremodule{standard}{imaplib}
\modulesynopsis{IMAP4 protocol client (requires sockets).}
\moduleauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}
\sectionauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}

% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
% Revised by ESR, January 2000.

\indexii{IMAP4}{protocol}

This module defines a class, \class{IMAP4}, which encapsulates a
connection to an IMAP4 server and implements 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
\samp{STATUS} command is not supported in IMAP4.

A single class is provided by the \module{imaplib} module:

\begin{classdesc}{IMAP4}{\optional{host\optional{, 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 \var{host} is not specified, \code{''} (the local host) is used.
If \var{port} is omitted, the standard IMAP4 port (143) is used.
\end{classdesc}

Two exceptions are defined as attributes of the \class{IMAP4} class:

\begin{excdesc}{IMAP4.error}
Exception raised on any errors.  The reason for the exception is
passed to the constructor as a string.
\end{excdesc}

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

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

The following utility functions are defined:

\begin{funcdesc}{Internaldate2tuple}{datestr}
  Converts an IMAP4 INTERNALDATE string to Coordinated Universal
  Time. Returns a \refmodule{time} module tuple.
\end{funcdesc}

\begin{funcdesc}{Int2AP}{num}
  Converts an integer into a string representation using characters
  from the set [\code{A} .. \code{P}].
\end{funcdesc}

\begin{funcdesc}{ParseFlags}{flagstr}
  Converts an IMAP4 \samp{FLAGS} response to a tuple of individual
  flags.
\end{funcdesc}

\begin{funcdesc}{Time2Internaldate}{date_time}
  Converts a \refmodule{time} module tuple to an IMAP4
  \samp{INTERNALDATE} representation.  Returns a string in the form:
  \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes).
\end{funcdesc}


Note that IMAP4 message numbers change as the mailbox changes; in
particular, after an \samp{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.

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


\subsection{IMAP4 Objects \label{imap4-objects}}

All IMAP4rev1 commands are represented by methods of the same name,
either upper-case or lower-case.

All arguments to commands are converted to strings, except for
\samp{AUTHENTICATE}, and the last argument to \samp{APPEND} which is
passed as an IMAP4 literal.  If necessary (the string contains IMAP4
protocol-sensitive characters and isn't enclosed with either
parentheses or double quotes) each string is quoted. However, the
\var{password} argument to the \samp{LOGIN} command is always quoted.
If you want to avoid having an argument string quoted
(eg: the \var{flags} argument to \samp{STORE}) then enclose the string in
parentheses (eg: \code{r'(\e Deleted)'}).

Each command returns a tuple: \code{(\var{type}, [\var{data},
...])} where \var{type} is usually \code{'OK'} or \code{'NO'},
and \var{data} is either the text from the command response, or
mandated results from the command.

An \class{IMAP4} instance has the following methods:


\begin{methoddesc}{append}{mailbox, flags, date_time, message}
  Append message to named mailbox. 
\end{methoddesc}

\begin{methoddesc}{authenticate}{func}
  Authenticate command --- requires response processing. This is
  currently unimplemented, and raises an exception. 
\end{methoddesc}

\begin{methoddesc}{check}{}
  Checkpoint mailbox on server. 
\end{methoddesc}

\begin{methoddesc}{close}{}
  Close currently selected mailbox. Deleted messages are removed from
  writable mailbox. This is the recommended command before
  \samp{LOGOUT}.
\end{methoddesc}

\begin{methoddesc}{copy}{message_set, new_mailbox}
  Copy \var{message_set} messages onto end of \var{new_mailbox}. 
\end{methoddesc}

\begin{methoddesc}{create}{mailbox}
  Create new mailbox named \var{mailbox}.
\end{methoddesc}

\begin{methoddesc}{delete}{mailbox}
  Delete old mailbox named \var{mailbox}.
\end{methoddesc}

\begin{methoddesc}{expunge}{}
  Permanently remove deleted items from selected mailbox. Generates an
  \samp{EXPUNGE} response for each deleted message. Returned data
  contains a list of \samp{EXPUNGE} message numbers in order
  received.
\end{methoddesc}

\begin{methoddesc}{fetch}{message_set, message_parts}
  Fetch (parts of) messages.  \var{message_parts} should be
  a string of message part names enclosed within parentheses,
  eg: \samp{"(UID BODY[TEXT])"}.  Returned data are tuples
  of message part envelope and data.
\end{methoddesc}

\begin{methoddesc}{list}{\optional{directory\optional{, pattern}}}
  List mailbox names in \var{directory} matching
  \var{pattern}.  \var{directory} defaults to the top-level mail
  folder, and \var{pattern} defaults to match anything.  Returned data
  contains a list of \samp{LIST} responses.
\end{methoddesc}

\begin{methoddesc}{login}{user, password}
  Identify the client using a plaintext password.
  The \var{password} will be quoted.
\end{methoddesc}

\begin{methoddesc}{logout}{}
  Shutdown connection to server. Returns server \samp{BYE} response.
\end{methoddesc}

\begin{methoddesc}{lsub}{\optional{directory\optional{, pattern}}}
  List subscribed mailbox names in directory matching pattern.
  \var{directory} defaults to the top level directory and
  \var{pattern} defaults to match any mailbox.
  Returned data are tuples of message part envelope and data.
\end{methoddesc}

\begin{methoddesc}{noop}{}
  Send \samp{NOOP} to server.
\end{methoddesc}

\begin{methoddesc}{open}{host, port}
  Opens socket to \var{port} at \var{host}.
  You may override this method.
\end{methoddesc}

\begin{methoddesc}{partial}{message_num, message_part, start, length}
  Fetch truncated part of a message.
  Returned data is a tuple of message part envelope and data.
\end{methoddesc}

\begin{methoddesc}{recent}{}
  Prompt server for an update. Returned data is \code{None} if no new
  messages, else value of \samp{RECENT} response.
\end{methoddesc}

\begin{methoddesc}{rename}{oldmailbox, newmailbox}
  Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
\end{methoddesc}

\begin{methoddesc}{response}{code}
  Return data for response \var{code} if received, or
  \code{None}. Returns the given code, instead of the usual type.
\end{methoddesc}

\begin{methoddesc}{search}{charset, criterium\optional{, ...}}
  Search mailbox for matching messages.  Returned data contains a space
  separated list of matching message numbers.  \var{charset} may be
  \code{None}, in which case no \samp{CHARSET} will be specified in the
  request to the server.  The IMAP protocol requires that at least one
  criterium be specified; an exception will be raised when the server
  returns an error.

  Example:

\begin{verbatim}
# M is a connected IMAP4 instance...
msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
msgnums = M.search(None, '(FROM "LDJ")')
\end{verbatim}
\end{methoddesc}

\begin{methoddesc}{select}{\optional{mailbox\optional{, readonly}}}
  Select a mailbox. Returned data is the count of messages in
  \var{mailbox} (\samp{EXISTS} response).  The default \var{mailbox}
  is \code{'INBOX'}.  If the \var{readonly} flag is set, modifications
  to the mailbox are not allowed.
\end{methoddesc}

\begin{methoddesc}{socket}{}
  Returns socket instance used to connect to server. 
\end{methoddesc}

\begin{methoddesc}{status}{mailbox, names}
  Request named status conditions for \var{mailbox}. 
\end{methoddesc}

\begin{methoddesc}{store}{message_set, command, flag_list}
  Alters flag dispositions for messages in mailbox.
\end{methoddesc}

\begin{methoddesc}{subscribe}{mailbox}
  Subscribe to new mailbox.
\end{methoddesc}

\begin{methoddesc}{uid}{command, arg\optional{, ...}}
  Execute command args with messages identified by UID, rather than
  message number.  Returns response appropriate to command.  At least
  one argument must be supplied; if none are provided, the server will
  return an error and an exception will be raised.
\end{methoddesc}

\begin{methoddesc}{unsubscribe}{mailbox}
  Unsubscribe from old mailbox.
\end{methoddesc}

\begin{methoddesc}{xatom}{name\optional{, arg\optional{, ...}}}
  Allow simple extension commands notified by server in
  \samp{CAPABILITY} response.
\end{methoddesc}


The following attributes are defined on instances of \class{IMAP4}:


\begin{memberdesc}{PROTOCOL_VERSION}
The most recent supported protocol in the
\samp{CAPABILITY} response from the server.
\end{memberdesc}

\begin{memberdesc}{debug}
Integer value to control debugging output.  The initialize value is
taken from the module variable \code{Debug}.  Values greater than
three trace each command.
\end{memberdesc}


\subsection{IMAP4 Example \label{imap4-example}}

Here is a minimal example (without error checking) that opens a
mailbox and retrieves and prints all messages:

\begin{verbatim}
import getpass, imaplib, string

M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in string.split(data[0]):
    typ, data = M.fetch(num, '(RFC822)')
    print 'Message %s\n%s\n' % (num, data[0][1])
M.logout()
\end{verbatim}