Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame^] | 1 | % Based on HTML documentation by Piers Lauders <piers@staff.cs.usyd.edu.au>; |
| 2 | % converted by Fred L. Drake, Jr. <fdrake@acm.org>. |
| 3 | % |
| 4 | % The imaplib module was written by Piers Lauders. |
| 5 | |
| 6 | \section{Standard Module \module{imaplib}} |
| 7 | \stmodindex{imaplib} |
| 8 | \label{module-imaplib} |
| 9 | |
| 10 | This module defines a class, \class{IMAP4}, which encapsulates a |
| 11 | connection to an IMAP4 server and implements the IMAP4rev1 client |
| 12 | protocol as defined in \rfc{2060}. It is backward compatible with |
| 13 | IMAP4 (\rfc{1730}) servers, but note that the \samp{STATUS} command is |
| 14 | not supported in IMAP4. |
| 15 | |
| 16 | A single class is provided by the \code{imaplib} module: |
| 17 | |
| 18 | \begin{classdesc}{IMAP4}{\optional{host\optional{, port}}} |
| 19 | This class implements the actual IMAP4 protocol. The connection is |
| 20 | created and protocol version (IMAP4 or IMAP4rev1) is determined when |
| 21 | the instance is initialized. |
| 22 | If \var{host} is not specified, \code{''} (the local host) is used. |
| 23 | If \var{port} is omitted, the standard IMAP4 port (143) is used. |
| 24 | \end{classdesc} |
| 25 | |
| 26 | Two exceptions are defined as attributes of the \class{IMAP4} class: |
| 27 | |
| 28 | \begin{excdesc}{IMAP4.error} |
| 29 | Exception raised on any errors. The reason for the exception is |
| 30 | passed to the constructor as a string. |
| 31 | \end{excdesc} |
| 32 | |
| 33 | \begin{excdesc}{IMAP4.abort} |
| 34 | IMAP4 server errors cause this exception to be raised. This is a |
| 35 | sub-class of \exception{IMAP4.error}. Note that closing the instance |
| 36 | and instantiating a new one will usually allow recovery from this |
| 37 | exception. |
| 38 | \end{excdesc} |
| 39 | |
| 40 | The following utility functions are defined: |
| 41 | |
| 42 | \begin{funcdesc}{Internaldate2tuple}{datestr} |
| 43 | Converts an IMAP4 INTERNALDATE string to Coordinated Universal |
| 44 | Time. Returns a \module{time} module tuple. |
| 45 | \end{funcdesc} |
| 46 | |
| 47 | \begin{funcdesc}{Int2AP}{num} |
| 48 | Converts an integer into a string representation using characters |
| 49 | from the set [\code{A} .. \code{P}]. |
| 50 | \end{funcdesc} |
| 51 | |
| 52 | \begin{funcdesc}{ParseFlags}{flagstr} |
| 53 | Converts an IMAP4 \samp{FLAGS} response to a tuple of individual |
| 54 | flags. |
| 55 | \end{funcdesc} |
| 56 | |
| 57 | \begin{funcdesc}{Time2Internaldate}{date_time} |
| 58 | Converts a \module{time} module tuple to an IMAP4 |
| 59 | \samp{INTERNALDATE} representation. Returns a string in the form: |
| 60 | \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes). |
| 61 | \end{funcdesc} |
| 62 | |
| 63 | |
| 64 | \subsection{IMAP4 Objects} |
| 65 | |
| 66 | All IMAP4rev1 commands are represented by methods of the same name, |
| 67 | either upper-case or lower-case. |
| 68 | |
| 69 | Each command returns a tuple: \code{(}\var{type}, \code{[}\var{data}, |
| 70 | ...\code{])} where \var{type} is usually \code{'OK'} or \code{'NO'}, |
| 71 | and \var{data} is either the text from the command response, or |
| 72 | mandated results from the command. |
| 73 | |
| 74 | An \class{IMAP4} instance has the following methods: |
| 75 | |
| 76 | |
| 77 | \begin{methoddesc}{append}{mailbox, flags, date_time, message} |
| 78 | Append message to named mailbox. |
| 79 | \end{methoddesc} |
| 80 | |
| 81 | \begin{methoddesc}{authenticate}{func} |
| 82 | Authenticate command --- requires response processing. This is |
| 83 | currently unimplemented, and raises an exception. |
| 84 | \end{methoddesc} |
| 85 | |
| 86 | \begin{methoddesc}{check}{} |
| 87 | Checkpoint mailbox on server. |
| 88 | \end{methoddesc} |
| 89 | |
| 90 | \begin{methoddesc}{close}{} |
| 91 | Close currently selected mailbox. Deleted messages are removed from |
| 92 | writable mailbox. This is the recommended command before |
| 93 | \samp{LOGOUT}. |
| 94 | \end{methoddesc} |
| 95 | |
| 96 | \begin{methoddesc}{copy}{message_set, new_mailbox} |
| 97 | Copy \var{message_set} messages onto end of \var{new_mailbox}. |
| 98 | \end{methoddesc} |
| 99 | |
| 100 | \begin{methoddesc}{create}{mailbox} |
| 101 | Create new mailbox named \var{mailbox}. |
| 102 | \end{methoddesc} |
| 103 | |
| 104 | \begin{methoddesc}{delete}{mailbox} |
| 105 | Delete old mailbox named \var{mailbox}. |
| 106 | \end{methoddesc} |
| 107 | |
| 108 | \begin{methoddesc}{expunge}{} |
| 109 | Permanently remove deleted items from selected mailbox. Generates an |
| 110 | \samp{EXPUNGE} response for each deleted message. Returned data |
| 111 | contains a list of \samp{EXPUNGE} message numbers in order |
| 112 | received. |
| 113 | \end{methoddesc} |
| 114 | |
| 115 | \begin{methoddesc}{fetch}{message_set, message_parts} |
| 116 | Fetch (parts of) messages. Returned data are tuples of message part |
| 117 | envelope and data. |
| 118 | \end{methoddesc} |
| 119 | |
| 120 | \begin{methoddesc}{list}{directory='""', pattern='*'} |
| 121 | List mailbox names in directory matching pattern. Returned data contains a |
| 122 | list of \samp{LIST} responses. |
| 123 | \end{methoddesc} |
| 124 | |
| 125 | \begin{methoddesc}{login}{user, password} |
| 126 | Identify the client using a plaintext password. |
| 127 | \end{methoddesc} |
| 128 | |
| 129 | \begin{methoddesc}{logout}{} |
| 130 | Shutdown connection to server. Returns server \samp{BYE} response. |
| 131 | \end{methoddesc} |
| 132 | |
| 133 | \begin{methoddesc}{lsub}{directory='""', pattern='*'} |
| 134 | List subscribed mailbox names in directory matching |
| 135 | pattern. Returned data are tuples of message part envelope and data. |
| 136 | \end{methoddesc} |
| 137 | |
| 138 | \begin{methoddesc}{recent}{} |
| 139 | Prompt server for an update. Returned data is \code{None} if no new |
| 140 | messages, else value of \samp{RECENT} response. |
| 141 | \end{methoddesc} |
| 142 | |
| 143 | \begin{methoddesc}{rename}{oldmailbox, newmailbox} |
| 144 | Rename mailbox named \var{oldmailbox} to \var{newmailbox}. |
| 145 | \end{methoddesc} |
| 146 | |
| 147 | \begin{methoddesc}{response}{code} |
| 148 | Return data for response \var{code} if received, or |
| 149 | \code{None}. Returns the given code, instead of the usual type. |
| 150 | \end{methoddesc} |
| 151 | |
| 152 | \begin{methoddesc}{search}{charset, criteria} |
| 153 | Search mailbox for matching messages. Returned data contains a space |
| 154 | separated list of matching message numbers. |
| 155 | \end{methoddesc} |
| 156 | |
| 157 | \begin{methoddesc}{select}{\optional{mailbox\optional{, readonly}}} |
| 158 | Select a mailbox. Returned data is the count of messages in |
| 159 | \var{mailbox} (\samp{EXISTS} response). The default \var{mailbox} |
| 160 | is \code{'INBOX'}. If the \var{readonly} flag is set, modifications |
| 161 | to the mailbox are not allowed. |
| 162 | \end{methoddesc} |
| 163 | |
| 164 | \begin{methoddesc}{status}{mailbox, names} |
| 165 | Request named status conditions for \var{mailbox}. |
| 166 | \end{methoddesc} |
| 167 | |
| 168 | \begin{methoddesc}{store}{message_set, command, flag_list} |
| 169 | Alters flag dispositions for messages in mailbox. |
| 170 | \end{methoddesc} |
| 171 | |
| 172 | \begin{methoddesc}{subscribe}{mailbox} |
| 173 | Subscribe to new mailbox. |
| 174 | \end{methoddesc} |
| 175 | |
| 176 | \begin{methoddesc}{uid}{command, args} |
| 177 | Execute command args with messages identified by UID, rather than |
| 178 | message number. Returns response appropriate to command. |
| 179 | \end{methoddesc} |
| 180 | |
| 181 | \begin{methoddesc}{unsubscribe}{mailbox} |
| 182 | Unsubscribe from old mailbox. |
| 183 | \end{methoddesc} |
| 184 | |
| 185 | \begin{methoddesc}{xatom}{name\optional{, arg1\optional{, arg2}}} |
| 186 | Allow simple extension commands notified by server in |
| 187 | \samp{CAPABILITY} response. |
| 188 | \end{methoddesc} |
| 189 | |
| 190 | |
| 191 | \class{IMAP4} instances have a variable \member{PROTOCOL_VERSION} that |
| 192 | is set to the most recent supported protocol in the \samp{CAPABILITY} |
| 193 | response. |
| 194 | |
| 195 | Finally, \class{IMAP4} instances have a variable debug which can be |
| 196 | set to an integer to turn on debugging. Values greater than 3 trace |
| 197 | each command. |
| 198 | |
| 199 | |
| 200 | \subsection{IMAP4 Example} |
| 201 | |
| 202 | Here is a minimal example (without error checking) that opens a |
| 203 | mailbox and retrieves and prints all messages: |
| 204 | |
| 205 | \begin{verbatim} |
| 206 | import getpass, imaplib, string |
| 207 | M = imaplib.IMAP4() |
| 208 | M.LOGIN(getpass.getuser(), getpass.getpass()) |
| 209 | M.SELECT() |
| 210 | typ, data = M.SEARCH(None, 'ALL') |
| 211 | for num in string.split(data[0]): |
| 212 | typ, data - M.FETCH(num, '(RFC822)') |
| 213 | print 'Message %s\n%s\n' % (num, data[0][1]) |
| 214 | M.LOGOUT() |
| 215 | \end{verbatim} |
| 216 | |
| 217 | Note that IMAP4 message numbers change as the mailbox changes, so it |
| 218 | is highly advisable to use UIDs instead, with the UID command. |
| 219 | |
| 220 | At the end of the module, there is a test section that contains a more |
| 221 | extensive example of usage. |
| 222 | |
| 223 | \begin{seealso} |
| 224 | \seetext{Documents describing the protocol, and sources and binaries |
| 225 | for servers implementing it, can all be found at the University of |
| 226 | Washington's \emph{IMAP Information Center} |
| 227 | (\url{http://www.cac.washington.edu/imap/}).} |
| 228 | \end{seealso} |