| \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>. |
| |
| \indexii{IMAP4}{protocol} |
| |
| This module defines a class, \class{IMAP4}, which encapsulates a |
| connection to an IMAP4 server and implements 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, 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} |