Doc/lib/libimaplib.tex

   1 \section{\module{imaplib} ---
   2          IMAP4 protocol client}
   3
   4 \declaremodule{standard}{imaplib}
   5 \modulesynopsis{IMAP4 protocol client (requires sockets).}
   6 \moduleauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}
   7 \sectionauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}
   8
   9 % Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
  10 % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
  11 % Revised by ESR, January 2000.
  12
  13 \indexii{IMAP4}{protocol}
  14
  15 This module defines a class, \class{IMAP4}, which encapsulates a
  16 connection to an IMAP4 server and implements a large subset of the
  17 IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward
  18 compatible with IMAP4 (\rfc{1730}) servers, but note that the
  19 \samp{STATUS} command is not supported in IMAP4.
  20
  21 A single class is provided by the \module{imaplib} module:
  22
  23 \begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
  24 This class implements the actual IMAP4 protocol.  The connection is
  25 created and protocol version (IMAP4 or IMAP4rev1) is determined when
  26 the instance is initialized.
  27 If \var{host} is not specified, \code{''} (the local host) is used.
  28 If \var{port} is omitted, the standard IMAP4 port (143) is used.
  29 \end{classdesc}
  30
  31 Two exceptions are defined as attributes of the \class{IMAP4} class:
  32
  33 \begin{excdesc}{IMAP4.error}
  34 Exception raised on any errors.  The reason for the exception is
  35 passed to the constructor as a string.
  36 \end{excdesc}
  37
  38 \begin{excdesc}{IMAP4.abort}
  39 IMAP4 server errors cause this exception to be raised.  This is a
  40 sub-class of \exception{IMAP4.error}.  Note that closing the instance
  41 and instantiating a new one will usually allow recovery from this
  42 exception.
  43 \end{excdesc}
  44
  45 \begin{excdesc}{IMAP4.readonly}
  46 This exception is raised when a writable mailbox has its status changed by the server.  This is a
  47 sub-class of \exception{IMAP4.error}.  Some other client now has write permission,
  48 and the mailbox will need to be re-opened to re-obtain write permission.
  49 \end{excdesc}
  50
  51 The following utility functions are defined:
  52
  53 \begin{funcdesc}{Internaldate2tuple}{datestr}
  54   Converts an IMAP4 INTERNALDATE string to Coordinated Universal
  55   Time. Returns a \refmodule{time} module tuple.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{Int2AP}{num}
  59   Converts an integer into a string representation using characters
  60   from the set [\code{A} .. \code{P}].
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{ParseFlags}{flagstr}
  64   Converts an IMAP4 \samp{FLAGS} response to a tuple of individual
  65   flags.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{Time2Internaldate}{date_time}
  69   Converts a \refmodule{time} module tuple to an IMAP4
  70   \samp{INTERNALDATE} representation.  Returns a string in the form:
  71   \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes).
  72 \end{funcdesc}
  73
  74
  75 Note that IMAP4 message numbers change as the mailbox changes; in
  76 particular, after an \samp{EXPUNGE} command performs deletions the
  77 remaining messages are renumbered. So it is highly advisable to use
  78 UIDs instead, with the UID command.
  79
  80 At the end of the module, there is a test section that contains a more
  81 extensive example of usage.
  82
  83 \begin{seealso}
  84   \seetext{Documents describing the protocol, and sources and binaries
  85            for servers implementing it, can all be found at the
  86            University of Washington's \emph{IMAP Information Center}
  87            (\url{http://www.cac.washington.edu/imap/}).}
  88 \end{seealso}
  89
  90
  91 \subsection{IMAP4 Objects \label{imap4-objects}}
  92
  93 All IMAP4rev1 commands are represented by methods of the same name,
  94 either upper-case or lower-case.
  95
  96 All arguments to commands are converted to strings, except for
  97 \samp{AUTHENTICATE}, and the last argument to \samp{APPEND} which is
  98 passed as an IMAP4 literal.  If necessary (the string contains IMAP4
  99 protocol-sensitive characters and isn't enclosed with either
 100 parentheses or double quotes) each string is quoted. However, the
 101 \var{password} argument to the \samp{LOGIN} command is always quoted.
 102 If you want to avoid having an argument string quoted
 103 (eg: the \var{flags} argument to \samp{STORE}) then enclose the string in
 104 parentheses (eg: \code{r'(\e Deleted)'}).
 105
 106 Each command returns a tuple: \code{(\var{type}, [\var{data},
 107 ...])} where \var{type} is usually \code{'OK'} or \code{'NO'},
 108 and \var{data} is either the text from the command response, or
 109 mandated results from the command.
 110
 111 An \class{IMAP4} instance has the following methods:
 112
 113
 114 \begin{methoddesc}{append}{mailbox, flags, date_time, message}
 115   Append message to named mailbox.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}{authenticate}{func}
 119   Authenticate command --- requires response processing. This is
 120   currently unimplemented, and raises an exception.
 121 \end{methoddesc}
 122
 123 \begin{methoddesc}{check}{}
 124   Checkpoint mailbox on server.
 125 \end{methoddesc}
 126
 127 \begin{methoddesc}{close}{}
 128   Close currently selected mailbox. Deleted messages are removed from
 129   writable mailbox. This is the recommended command before
 130   \samp{LOGOUT}.
 131 \end{methoddesc}
 132
 133 \begin{methoddesc}{copy}{message_set, new_mailbox}
 134   Copy \var{message_set} messages onto end of \var{new_mailbox}.
 135 \end{methoddesc}
 136
 137 \begin{methoddesc}{create}{mailbox}
 138   Create new mailbox named \var{mailbox}.
 139 \end{methoddesc}
 140
 141 \begin{methoddesc}{delete}{mailbox}
 142   Delete old mailbox named \var{mailbox}.
 143 \end{methoddesc}
 144
 145 \begin{methoddesc}{expunge}{}
 146   Permanently remove deleted items from selected mailbox. Generates an
 147   \samp{EXPUNGE} response for each deleted message. Returned data
 148   contains a list of \samp{EXPUNGE} message numbers in order
 149   received.
 150 \end{methoddesc}
 151
 152 \begin{methoddesc}{fetch}{message_set, message_parts}
 153   Fetch (parts of) messages.  \var{message_parts} should be
 154   a string of message part names enclosed within parentheses,
 155   eg: \samp{"(UID BODY[TEXT])"}.  Returned data are tuples
 156   of message part envelope and data.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}{list}{\optional{directory\optional{, pattern}}}
 160   List mailbox names in \var{directory} matching
 161   \var{pattern}.  \var{directory} defaults to the top-level mail
 162   folder, and \var{pattern} defaults to match anything.  Returned data
 163   contains a list of \samp{LIST} responses.
 164 \end{methoddesc}
 165
 166 \begin{methoddesc}{login}{user, password}
 167   Identify the client using a plaintext password.
 168   The \var{password} will be quoted.
 169 \end{methoddesc}
 170
 171 \begin{methoddesc}{logout}{}
 172   Shutdown connection to server. Returns server \samp{BYE} response.
 173 \end{methoddesc}
 174
 175 \begin{methoddesc}{lsub}{\optional{directory\optional{, pattern}}}
 176   List subscribed mailbox names in directory matching pattern.
 177   \var{directory} defaults to the top level directory and
 178   \var{pattern} defaults to match any mailbox.
 179   Returned data are tuples of message part envelope and data.
 180 \end{methoddesc}
 181
 182 \begin{methoddesc}{noop}{}
 183   Send \samp{NOOP} to server.
 184 \end{methoddesc}
 185
 186 \begin{methoddesc}{open}{host, port}
 187   Opens socket to \var{port} at \var{host}.
 188   You may override this method.
 189 \end{methoddesc}
 190
 191 \begin{methoddesc}{partial}{message_num, message_part, start, length}
 192   Fetch truncated part of a message.
 193   Returned data is a tuple of message part envelope and data.
 194 \end{methoddesc}
 195
 196 \begin{methoddesc}{recent}{}
 197   Prompt server for an update. Returned data is \code{None} if no new
 198   messages, else value of \samp{RECENT} response.
 199 \end{methoddesc}
 200
 201 \begin{methoddesc}{rename}{oldmailbox, newmailbox}
 202   Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
 203 \end{methoddesc}
 204
 205 \begin{methoddesc}{response}{code}
 206   Return data for response \var{code} if received, or
 207   \code{None}. Returns the given code, instead of the usual type.
 208 \end{methoddesc}
 209
 210 \begin{methoddesc}{search}{charset, criterium\optional{, ...}}
 211   Search mailbox for matching messages.  Returned data contains a space
 212   separated list of matching message numbers.  \var{charset} may be
 213   \code{None}, in which case no \samp{CHARSET} will be specified in the
 214   request to the server.  The IMAP protocol requires that at least one
 215   criterium be specified; an exception will be raised when the server
 216   returns an error.
 217
 218   Example:
 219
 220 \begin{verbatim}
 221 # M is a connected IMAP4 instance...
 222 msgnums = M.search(None, 'FROM', '"LDJ"')
 223
 224 # or:
 225 msgnums = M.search(None, '(FROM "LDJ")')
 226 \end{verbatim}
 227 \end{methoddesc}
 228
 229 \begin{methoddesc}{select}{\optional{mailbox\optional{, readonly}}}
 230   Select a mailbox. Returned data is the count of messages in
 231   \var{mailbox} (\samp{EXISTS} response).  The default \var{mailbox}
 232   is \code{'INBOX'}.  If the \var{readonly} flag is set, modifications
 233   to the mailbox are not allowed.
 234 \end{methoddesc}
 235
 236 \begin{methoddesc}{socket}{}
 237   Returns socket instance used to connect to server.
 238 \end{methoddesc}
 239
 240 \begin{methoddesc}{status}{mailbox, names}
 241   Request named status conditions for \var{mailbox}.
 242 \end{methoddesc}
 243
 244 \begin{methoddesc}{store}{message_set, command, flag_list}
 245   Alters flag dispositions for messages in mailbox.
 246 \end{methoddesc}
 247
 248 \begin{methoddesc}{subscribe}{mailbox}
 249   Subscribe to new mailbox.
 250 \end{methoddesc}
 251
 252 \begin{methoddesc}{uid}{command, arg\optional{, ...}}
 253   Execute command args with messages identified by UID, rather than
 254   message number.  Returns response appropriate to command.  At least
 255   one argument must be supplied; if none are provided, the server will
 256   return an error and an exception will be raised.
 257 \end{methoddesc}
 258
 259 \begin{methoddesc}{unsubscribe}{mailbox}
 260   Unsubscribe from old mailbox.
 261 \end{methoddesc}
 262
 263 \begin{methoddesc}{xatom}{name\optional{, arg\optional{, ...}}}
 264   Allow simple extension commands notified by server in
 265   \samp{CAPABILITY} response.
 266 \end{methoddesc}
 267
 268
 269 The following attributes are defined on instances of \class{IMAP4}:
 270
 271
 272 \begin{memberdesc}{PROTOCOL_VERSION}
 273 The most recent supported protocol in the
 274 \samp{CAPABILITY} response from the server.
 275 \end{memberdesc}
 276
 277 \begin{memberdesc}{debug}
 278 Integer value to control debugging output.  The initialize value is
 279 taken from the module variable \code{Debug}.  Values greater than
 280 three trace each command.
 281 \end{memberdesc}
 282
 283
 284 \subsection{IMAP4 Example \label{imap4-example}}
 285
 286 Here is a minimal example (without error checking) that opens a
 287 mailbox and retrieves and prints all messages:
 288
 289 \begin{verbatim}
 290 import getpass, imaplib, string
 291
 292 M = imaplib.IMAP4()
 293 M.login(getpass.getuser(), getpass.getpass())
 294 M.select()
 295 typ, data = M.search(None, 'ALL')
 296 for num in string.split(data[0]):
 297     typ, data = M.fetch(num, '(RFC822)')
 298     print 'Message %s\n%s\n' % (num, data[0][1])
 299 M.logout()
 300 \end{verbatim}