Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{imaplib} --- |
Fred Drake | b774550 | 1999-04-22 16:46:18 +0000 | [diff] [blame] | 2 | IMAP4 protocol client} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{imaplib} |
Fred Drake | b774550 | 1999-04-22 16:46:18 +0000 | [diff] [blame] | 5 | \modulesynopsis{IMAP4 protocol client (requires sockets).} |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 6 | \moduleauthor{Piers Lauder}{piers@communitysolutions.com.au} |
| 7 | \sectionauthor{Piers Lauder}{piers@communitysolutions.com.au} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 8 | |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 9 | % Based on HTML documentation by Piers Lauder <piers@communitysolutions.com.au>; |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 10 | % converted by Fred L. Drake, Jr. <fdrake@acm.org>. |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 11 | % Revised by ESR, January 2000. |
Piers Lauder | a4f8313 | 2002-03-08 01:53:24 +0000 | [diff] [blame] | 12 | % Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002 |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 13 | % Changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>, November 2002 |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 14 | |
Fred Drake | e5cf53a | 1998-04-11 05:02:45 +0000 | [diff] [blame] | 15 | \indexii{IMAP4}{protocol} |
Piers Lauder | a4f8313 | 2002-03-08 01:53:24 +0000 | [diff] [blame] | 16 | \indexii{IMAP4_SSL}{protocol} |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 17 | \indexii{IMAP4_stream}{protocol} |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 18 | |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 19 | This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL} and \class{IMAP4_stream}, which encapsulate a |
Piers Lauder | a4f8313 | 2002-03-08 01:53:24 +0000 | [diff] [blame] | 20 | connection to an IMAP4 server and implement a large subset of the |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 21 | IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward |
| 22 | compatible with IMAP4 (\rfc{1730}) servers, but note that the |
| 23 | \samp{STATUS} command is not supported in IMAP4. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 24 | |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 25 | Three classes are provided by the \module{imaplib} module, \class{IMAP4} is the base class: |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 26 | |
| 27 | \begin{classdesc}{IMAP4}{\optional{host\optional{, port}}} |
| 28 | This class implements the actual IMAP4 protocol. The connection is |
| 29 | created and protocol version (IMAP4 or IMAP4rev1) is determined when |
| 30 | the instance is initialized. |
| 31 | If \var{host} is not specified, \code{''} (the local host) is used. |
| 32 | If \var{port} is omitted, the standard IMAP4 port (143) is used. |
| 33 | \end{classdesc} |
| 34 | |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 35 | Three exceptions are defined as attributes of the \class{IMAP4} class: |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 36 | |
| 37 | \begin{excdesc}{IMAP4.error} |
| 38 | Exception raised on any errors. The reason for the exception is |
| 39 | passed to the constructor as a string. |
| 40 | \end{excdesc} |
| 41 | |
| 42 | \begin{excdesc}{IMAP4.abort} |
| 43 | IMAP4 server errors cause this exception to be raised. This is a |
| 44 | sub-class of \exception{IMAP4.error}. Note that closing the instance |
| 45 | and instantiating a new one will usually allow recovery from this |
| 46 | exception. |
| 47 | \end{excdesc} |
| 48 | |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 49 | \begin{excdesc}{IMAP4.readonly} |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 50 | This exception is raised when a writable mailbox has its status changed by the server. This is a |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 51 | sub-class of \exception{IMAP4.error}. Some other client now has write permission, |
| 52 | and the mailbox will need to be re-opened to re-obtain write permission. |
| 53 | \end{excdesc} |
| 54 | |
Piers Lauder | a4f8313 | 2002-03-08 01:53:24 +0000 | [diff] [blame] | 55 | There's also a subclass for secure connections: |
| 56 | |
| 57 | \begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{, keyfile\optional{, certfile}}}}} |
| 58 | This is a subclass derived from \class{IMAP4} that connects over an SSL encrypted socket |
| 59 | (to use this class you need a socket module that was compiled with SSL support). |
| 60 | If \var{host} is not specified, \code{''} (the local host) is used. |
| 61 | If \var{port} is omitted, the standard IMAP4-over-SSL port (993) is used. |
| 62 | \var{keyfile} and \var{certfile} are also optional - they can contain a PEM formatted |
| 63 | private key and certificate chain file for the SSL connection. |
| 64 | \end{classdesc} |
| 65 | |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 66 | The second subclass allows for connections created by a child process: |
| 67 | |
| 68 | \begin{classdesc}{IMAP4_stream}{command} |
| 69 | This is a subclass derived from \class{IMAP4} that connects |
| 70 | to the \code{stdin/stdout} file descriptors created by passing \var{command} to \code{os.popen2()}. |
Neal Norwitz | e149798 | 2003-01-02 15:32:00 +0000 | [diff] [blame] | 71 | \versionadded{2.3} |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 72 | \end{classdesc} |
| 73 | |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 74 | The following utility functions are defined: |
| 75 | |
| 76 | \begin{funcdesc}{Internaldate2tuple}{datestr} |
| 77 | Converts an IMAP4 INTERNALDATE string to Coordinated Universal |
Fred Drake | b774550 | 1999-04-22 16:46:18 +0000 | [diff] [blame] | 78 | Time. Returns a \refmodule{time} module tuple. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 79 | \end{funcdesc} |
| 80 | |
| 81 | \begin{funcdesc}{Int2AP}{num} |
| 82 | Converts an integer into a string representation using characters |
| 83 | from the set [\code{A} .. \code{P}]. |
| 84 | \end{funcdesc} |
| 85 | |
| 86 | \begin{funcdesc}{ParseFlags}{flagstr} |
| 87 | Converts an IMAP4 \samp{FLAGS} response to a tuple of individual |
| 88 | flags. |
| 89 | \end{funcdesc} |
| 90 | |
| 91 | \begin{funcdesc}{Time2Internaldate}{date_time} |
Fred Drake | b774550 | 1999-04-22 16:46:18 +0000 | [diff] [blame] | 92 | Converts a \refmodule{time} module tuple to an IMAP4 |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 93 | \samp{INTERNALDATE} representation. Returns a string in the form: |
| 94 | \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes). |
| 95 | \end{funcdesc} |
| 96 | |
| 97 | |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 98 | Note that IMAP4 message numbers change as the mailbox changes; in |
| 99 | particular, after an \samp{EXPUNGE} command performs deletions the |
| 100 | remaining messages are renumbered. So it is highly advisable to use |
| 101 | UIDs instead, with the UID command. |
Fred Drake | 363d67c | 1999-07-07 13:42:56 +0000 | [diff] [blame] | 102 | |
| 103 | At the end of the module, there is a test section that contains a more |
| 104 | extensive example of usage. |
| 105 | |
| 106 | \begin{seealso} |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 107 | \seetext{Documents describing the protocol, and sources and binaries |
| 108 | for servers implementing it, can all be found at the |
| 109 | University of Washington's \emph{IMAP Information Center} |
| 110 | (\url{http://www.cac.washington.edu/imap/}).} |
Fred Drake | 363d67c | 1999-07-07 13:42:56 +0000 | [diff] [blame] | 111 | \end{seealso} |
| 112 | |
| 113 | |
| 114 | \subsection{IMAP4 Objects \label{imap4-objects}} |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 115 | |
| 116 | All IMAP4rev1 commands are represented by methods of the same name, |
| 117 | either upper-case or lower-case. |
| 118 | |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 119 | All arguments to commands are converted to strings, except for |
Fred Drake | d16b5ab | 1999-12-13 23:34:42 +0000 | [diff] [blame] | 120 | \samp{AUTHENTICATE}, and the last argument to \samp{APPEND} which is |
| 121 | passed as an IMAP4 literal. If necessary (the string contains IMAP4 |
| 122 | protocol-sensitive characters and isn't enclosed with either |
| 123 | parentheses or double quotes) each string is quoted. However, the |
| 124 | \var{password} argument to the \samp{LOGIN} command is always quoted. |
Fred Drake | 99d707a | 2000-05-26 04:08:37 +0000 | [diff] [blame] | 125 | If you want to avoid having an argument string quoted |
| 126 | (eg: the \var{flags} argument to \samp{STORE}) then enclose the string in |
| 127 | parentheses (eg: \code{r'(\e Deleted)'}). |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 128 | |
Fred Drake | b774550 | 1999-04-22 16:46:18 +0000 | [diff] [blame] | 129 | Each command returns a tuple: \code{(\var{type}, [\var{data}, |
| 130 | ...])} where \var{type} is usually \code{'OK'} or \code{'NO'}, |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 131 | and \var{data} is either the text from the command response, or |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 132 | mandated results from the command. Each \var{data} |
| 133 | is either a string, or a tuple. If a tuple, then the first part |
| 134 | is the header of the response, and the second part contains |
| 135 | the data (ie: 'literal' value). |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 136 | |
| 137 | An \class{IMAP4} instance has the following methods: |
| 138 | |
| 139 | |
| 140 | \begin{methoddesc}{append}{mailbox, flags, date_time, message} |
Piers Lauder | 8bc81fc | 2004-05-20 12:12:58 +0000 | [diff] [blame] | 141 | Append \var{message} to named mailbox. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 142 | \end{methoddesc} |
| 143 | |
Piers Lauder | 8bc81fc | 2004-05-20 12:12:58 +0000 | [diff] [blame] | 144 | \begin{methoddesc}{authenticate}{mechanism, authobject} |
| 145 | Authenticate command --- requires response processing. |
| 146 | |
| 147 | \var{mechanism} specifies which authentication mechanism is to |
| 148 | be used - it should appear in the instance variable \code{capabilities} in the |
| 149 | form \code{AUTH=mechanism}. |
| 150 | |
| 151 | \var{authobject} must be a callable object: |
| 152 | |
| 153 | \begin{verbatim} |
| 154 | data = authobject(response) |
| 155 | \end{verbatim} |
| 156 | |
| 157 | It will be called to process server continuation responses. |
| 158 | It should return \code{data} that will be encoded and sent to server. |
| 159 | It should return \code{None} if the client abort response \samp{*} should |
| 160 | be sent instead. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 161 | \end{methoddesc} |
| 162 | |
| 163 | \begin{methoddesc}{check}{} |
| 164 | Checkpoint mailbox on server. |
| 165 | \end{methoddesc} |
| 166 | |
| 167 | \begin{methoddesc}{close}{} |
| 168 | Close currently selected mailbox. Deleted messages are removed from |
| 169 | writable mailbox. This is the recommended command before |
| 170 | \samp{LOGOUT}. |
| 171 | \end{methoddesc} |
| 172 | |
| 173 | \begin{methoddesc}{copy}{message_set, new_mailbox} |
| 174 | Copy \var{message_set} messages onto end of \var{new_mailbox}. |
| 175 | \end{methoddesc} |
| 176 | |
| 177 | \begin{methoddesc}{create}{mailbox} |
| 178 | Create new mailbox named \var{mailbox}. |
| 179 | \end{methoddesc} |
| 180 | |
| 181 | \begin{methoddesc}{delete}{mailbox} |
| 182 | Delete old mailbox named \var{mailbox}. |
| 183 | \end{methoddesc} |
| 184 | |
| 185 | \begin{methoddesc}{expunge}{} |
| 186 | Permanently remove deleted items from selected mailbox. Generates an |
| 187 | \samp{EXPUNGE} response for each deleted message. Returned data |
| 188 | contains a list of \samp{EXPUNGE} message numbers in order |
| 189 | received. |
| 190 | \end{methoddesc} |
| 191 | |
| 192 | \begin{methoddesc}{fetch}{message_set, message_parts} |
Fred Drake | 99d707a | 2000-05-26 04:08:37 +0000 | [diff] [blame] | 193 | Fetch (parts of) messages. \var{message_parts} should be |
| 194 | a string of message part names enclosed within parentheses, |
| 195 | eg: \samp{"(UID BODY[TEXT])"}. Returned data are tuples |
| 196 | of message part envelope and data. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 197 | \end{methoddesc} |
| 198 | |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 199 | \begin{methoddesc}{getacl}{mailbox} |
| 200 | Get the \samp{ACL}s for \var{mailbox}. |
| 201 | The method is non-standard, but is supported by the \samp{Cyrus} server. |
| 202 | \end{methoddesc} |
| 203 | |
Piers Lauder | 3fca291 | 2002-06-17 07:07:20 +0000 | [diff] [blame] | 204 | \begin{methoddesc}{getquota}{root} |
| 205 | Get the \samp{quota} \var{root}'s resource usage and limits. |
| 206 | This method is part of the IMAP4 QUOTA extension defined in rfc2087. |
Neal Norwitz | 1cfcafc | 2002-07-20 00:46:12 +0000 | [diff] [blame] | 207 | \versionadded{2.3} |
Piers Lauder | 3fca291 | 2002-06-17 07:07:20 +0000 | [diff] [blame] | 208 | \end{methoddesc} |
| 209 | |
| 210 | \begin{methoddesc}{getquotaroot}{mailbox} |
| 211 | Get the list of \samp{quota} \samp{roots} for the named \var{mailbox}. |
| 212 | This method is part of the IMAP4 QUOTA extension defined in rfc2087. |
Neal Norwitz | 1cfcafc | 2002-07-20 00:46:12 +0000 | [diff] [blame] | 213 | \versionadded{2.3} |
Piers Lauder | 3fca291 | 2002-06-17 07:07:20 +0000 | [diff] [blame] | 214 | \end{methoddesc} |
| 215 | |
Fred Drake | e5cf53a | 1998-04-11 05:02:45 +0000 | [diff] [blame] | 216 | \begin{methoddesc}{list}{\optional{directory\optional{, pattern}}} |
| 217 | List mailbox names in \var{directory} matching |
| 218 | \var{pattern}. \var{directory} defaults to the top-level mail |
| 219 | folder, and \var{pattern} defaults to match anything. Returned data |
| 220 | contains a list of \samp{LIST} responses. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 221 | \end{methoddesc} |
| 222 | |
| 223 | \begin{methoddesc}{login}{user, password} |
| 224 | Identify the client using a plaintext password. |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 225 | The \var{password} will be quoted. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 226 | \end{methoddesc} |
| 227 | |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 228 | \begin{methoddesc}{login_cram_md5}{user, password} |
| 229 | Force use of \samp{CRAM-MD5} authentication when identifying the client to protect the password. |
| 230 | Will only work if the server \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}. |
Neal Norwitz | e149798 | 2003-01-02 15:32:00 +0000 | [diff] [blame] | 231 | \versionadded{2.3} |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 232 | \end{methoddesc} |
| 233 | |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 234 | \begin{methoddesc}{logout}{} |
| 235 | Shutdown connection to server. Returns server \samp{BYE} response. |
| 236 | \end{methoddesc} |
| 237 | |
Fred Drake | e5cf53a | 1998-04-11 05:02:45 +0000 | [diff] [blame] | 238 | \begin{methoddesc}{lsub}{\optional{directory\optional{, pattern}}} |
| 239 | List subscribed mailbox names in directory matching pattern. |
| 240 | \var{directory} defaults to the top level directory and |
| 241 | \var{pattern} defaults to match any mailbox. |
| 242 | Returned data are tuples of message part envelope and data. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 243 | \end{methoddesc} |
| 244 | |
Piers Lauder | 8bc81fc | 2004-05-20 12:12:58 +0000 | [diff] [blame] | 245 | \begin{methoddesc}{namespace}{} |
| 246 | Returns IMAP namespaces as defined in RFC2342. |
| 247 | \versionadded{2.3} |
| 248 | \end{methoddesc} |
| 249 | |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 250 | \begin{methoddesc}{noop}{} |
Fred Drake | d16b5ab | 1999-12-13 23:34:42 +0000 | [diff] [blame] | 251 | Send \samp{NOOP} to server. |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 252 | \end{methoddesc} |
| 253 | |
| 254 | \begin{methoddesc}{open}{host, port} |
| 255 | Opens socket to \var{port} at \var{host}. |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 256 | The connection objects established by this method |
Piers Lauder | 3fca291 | 2002-06-17 07:07:20 +0000 | [diff] [blame] | 257 | will be used in the \code{read}, \code{readline}, \code{send}, and \code{shutdown} methods. |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 258 | You may override this method. |
| 259 | \end{methoddesc} |
| 260 | |
| 261 | \begin{methoddesc}{partial}{message_num, message_part, start, length} |
| 262 | Fetch truncated part of a message. |
| 263 | Returned data is a tuple of message part envelope and data. |
| 264 | \end{methoddesc} |
| 265 | |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 266 | \begin{methoddesc}{proxyauth}{user} |
| 267 | Assume authentication as \var{user}. |
| 268 | Allows an authorised administrator to proxy into any user's mailbox. |
Neal Norwitz | e149798 | 2003-01-02 15:32:00 +0000 | [diff] [blame] | 269 | \versionadded{2.3} |
Piers Lauder | d3c821e | 2002-11-22 05:47:39 +0000 | [diff] [blame] | 270 | \end{methoddesc} |
| 271 | |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 272 | \begin{methoddesc}{read}{size} |
| 273 | Reads \var{size} bytes from the remote server. |
| 274 | You may override this method. |
| 275 | \end{methoddesc} |
| 276 | |
| 277 | \begin{methoddesc}{readline}{} |
| 278 | Reads one line from the remote server. |
| 279 | You may override this method. |
| 280 | \end{methoddesc} |
| 281 | |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 282 | \begin{methoddesc}{recent}{} |
| 283 | Prompt server for an update. Returned data is \code{None} if no new |
| 284 | messages, else value of \samp{RECENT} response. |
| 285 | \end{methoddesc} |
| 286 | |
| 287 | \begin{methoddesc}{rename}{oldmailbox, newmailbox} |
| 288 | Rename mailbox named \var{oldmailbox} to \var{newmailbox}. |
| 289 | \end{methoddesc} |
| 290 | |
| 291 | \begin{methoddesc}{response}{code} |
| 292 | Return data for response \var{code} if received, or |
| 293 | \code{None}. Returns the given code, instead of the usual type. |
| 294 | \end{methoddesc} |
| 295 | |
Martin v. Löwis | 3ae0f7a | 2003-03-27 16:59:38 +0000 | [diff] [blame] | 296 | \begin{methoddesc}{search}{charset, criterion\optional{, ...}} |
Fred Drake | 99d707a | 2000-05-26 04:08:37 +0000 | [diff] [blame] | 297 | Search mailbox for matching messages. Returned data contains a space |
| 298 | separated list of matching message numbers. \var{charset} may be |
| 299 | \code{None}, in which case no \samp{CHARSET} will be specified in the |
| 300 | request to the server. The IMAP protocol requires that at least one |
Martin v. Löwis | 3ae0f7a | 2003-03-27 16:59:38 +0000 | [diff] [blame] | 301 | criterion be specified; an exception will be raised when the server |
Fred Drake | 99d707a | 2000-05-26 04:08:37 +0000 | [diff] [blame] | 302 | returns an error. |
| 303 | |
| 304 | Example: |
| 305 | |
| 306 | \begin{verbatim} |
| 307 | # M is a connected IMAP4 instance... |
| 308 | msgnums = M.search(None, 'FROM', '"LDJ"') |
| 309 | |
| 310 | # or: |
| 311 | msgnums = M.search(None, '(FROM "LDJ")') |
| 312 | \end{verbatim} |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 313 | \end{methoddesc} |
| 314 | |
| 315 | \begin{methoddesc}{select}{\optional{mailbox\optional{, readonly}}} |
| 316 | Select a mailbox. Returned data is the count of messages in |
| 317 | \var{mailbox} (\samp{EXISTS} response). The default \var{mailbox} |
| 318 | is \code{'INBOX'}. If the \var{readonly} flag is set, modifications |
| 319 | to the mailbox are not allowed. |
| 320 | \end{methoddesc} |
| 321 | |
Piers Lauder | 3fca291 | 2002-06-17 07:07:20 +0000 | [diff] [blame] | 322 | \begin{methoddesc}{send}{data} |
| 323 | Sends \code{data} to the remote server. |
| 324 | You may override this method. |
| 325 | \end{methoddesc} |
| 326 | |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 327 | \begin{methoddesc}{setacl}{mailbox, who, what} |
| 328 | Set an \samp{ACL} for \var{mailbox}. |
| 329 | The method is non-standard, but is supported by the \samp{Cyrus} server. |
| 330 | \end{methoddesc} |
| 331 | |
Piers Lauder | 3fca291 | 2002-06-17 07:07:20 +0000 | [diff] [blame] | 332 | \begin{methoddesc}{setquota}{root, limits} |
| 333 | Set the \samp{quota} \var{root}'s resource \var{limits}. |
| 334 | This method is part of the IMAP4 QUOTA extension defined in rfc2087. |
Neal Norwitz | 1cfcafc | 2002-07-20 00:46:12 +0000 | [diff] [blame] | 335 | \versionadded{2.3} |
Piers Lauder | 3fca291 | 2002-06-17 07:07:20 +0000 | [diff] [blame] | 336 | \end{methoddesc} |
| 337 | |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 338 | \begin{methoddesc}{shutdown}{} |
| 339 | Close connection established in \code{open}. |
| 340 | You may override this method. |
| 341 | \end{methoddesc} |
| 342 | |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 343 | \begin{methoddesc}{socket}{} |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 344 | Returns socket instance used to connect to server. |
| 345 | \end{methoddesc} |
| 346 | |
Martin v. Löwis | 3ae0f7a | 2003-03-27 16:59:38 +0000 | [diff] [blame] | 347 | \begin{methoddesc}{sort}{sort_criteria, charset, search_criterion\optional{, ...}} |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 348 | The \code{sort} command is a variant of \code{search} with sorting semantics for |
| 349 | the results. Returned data contains a space |
| 350 | separated list of matching message numbers. |
| 351 | |
Martin v. Löwis | 3ae0f7a | 2003-03-27 16:59:38 +0000 | [diff] [blame] | 352 | Sort has two arguments before the \var{search_criterion} |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 353 | argument(s); a parenthesized list of \var{sort_criteria}, and the searching \var{charset}. |
| 354 | Note that unlike \code{search}, the searching \var{charset} argument is mandatory. |
| 355 | There is also a \code{uid sort} command which corresponds to \code{sort} the way |
| 356 | that \code{uid search} corresponds to \code{search}. |
| 357 | The \code{sort} command first searches the mailbox for messages that |
| 358 | match the given searching criteria using the charset argument for |
| 359 | the interpretation of strings in the searching criteria. It then |
| 360 | returns the numbers of matching messages. |
| 361 | |
| 362 | This is an \samp{IMAP4rev1} extension command. |
Guido van Rossum | 5f7a28c | 1999-12-13 23:29:39 +0000 | [diff] [blame] | 363 | \end{methoddesc} |
| 364 | |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 365 | \begin{methoddesc}{status}{mailbox, names} |
| 366 | Request named status conditions for \var{mailbox}. |
| 367 | \end{methoddesc} |
| 368 | |
| 369 | \begin{methoddesc}{store}{message_set, command, flag_list} |
| 370 | Alters flag dispositions for messages in mailbox. |
| 371 | \end{methoddesc} |
| 372 | |
| 373 | \begin{methoddesc}{subscribe}{mailbox} |
| 374 | Subscribe to new mailbox. |
| 375 | \end{methoddesc} |
| 376 | |
Martin v. Löwis | d892137 | 2003-11-10 06:44:44 +0000 | [diff] [blame] | 377 | \begin{methoddesc}{thread}{threading_algorithm, charset, search_criterion\optional{, ...}} |
| 378 | The \code{thread} command is a variant of \code{search} with threading semantics for |
| 379 | the results. Returned data contains a space |
| 380 | separated list of thread members. |
| 381 | |
| 382 | Thread members consist of zero or more messages numbers, delimited by spaces, |
| 383 | indicating successive parent and child. |
| 384 | |
| 385 | Thread has two arguments before the \var{search_criterion} |
| 386 | argument(s); a \var{threading_algorithm}, and the searching \var{charset}. |
| 387 | Note that unlike \code{search}, the searching \var{charset} argument is mandatory. |
| 388 | There is also a \code{uid thread} command which corresponds to \code{thread} the way |
| 389 | that \code{uid search} corresponds to \code{search}. |
| 390 | The \code{thread} command first searches the mailbox for messages that |
| 391 | match the given searching criteria using the charset argument for |
| 392 | the interpretation of strings in the searching criteria. It thren |
| 393 | returns the matching messages threaded according to the specified |
| 394 | threading algorithm. |
| 395 | |
| 396 | This is an \samp{IMAP4rev1} extension command. \versionadded{2.4} |
| 397 | \end{methoddesc} |
| 398 | |
Fred Drake | 99d707a | 2000-05-26 04:08:37 +0000 | [diff] [blame] | 399 | \begin{methoddesc}{uid}{command, arg\optional{, ...}} |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 400 | Execute command args with messages identified by UID, rather than |
Fred Drake | 99d707a | 2000-05-26 04:08:37 +0000 | [diff] [blame] | 401 | message number. Returns response appropriate to command. At least |
| 402 | one argument must be supplied; if none are provided, the server will |
| 403 | return an error and an exception will be raised. |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 404 | \end{methoddesc} |
| 405 | |
| 406 | \begin{methoddesc}{unsubscribe}{mailbox} |
| 407 | Unsubscribe from old mailbox. |
| 408 | \end{methoddesc} |
| 409 | |
Fred Drake | 99d707a | 2000-05-26 04:08:37 +0000 | [diff] [blame] | 410 | \begin{methoddesc}{xatom}{name\optional{, arg\optional{, ...}}} |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 411 | Allow simple extension commands notified by server in |
| 412 | \samp{CAPABILITY} response. |
| 413 | \end{methoddesc} |
| 414 | |
| 415 | |
Piers Lauder | a4f8313 | 2002-03-08 01:53:24 +0000 | [diff] [blame] | 416 | Instances of \class{IMAP4_SSL} have just one additional method: |
| 417 | |
| 418 | \begin{methoddesc}{ssl}{} |
| 419 | Returns SSLObject instance used for the secure connection with the server. |
| 420 | \end{methoddesc} |
| 421 | |
| 422 | |
Fred Drake | 8f6b958 | 1998-04-11 15:11:55 +0000 | [diff] [blame] | 423 | The following attributes are defined on instances of \class{IMAP4}: |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 424 | |
Fred Drake | 8f6b958 | 1998-04-11 15:11:55 +0000 | [diff] [blame] | 425 | |
| 426 | \begin{memberdesc}{PROTOCOL_VERSION} |
Fred Drake | b774550 | 1999-04-22 16:46:18 +0000 | [diff] [blame] | 427 | The most recent supported protocol in the |
| 428 | \samp{CAPABILITY} response from the server. |
Fred Drake | 8f6b958 | 1998-04-11 15:11:55 +0000 | [diff] [blame] | 429 | \end{memberdesc} |
| 430 | |
| 431 | \begin{memberdesc}{debug} |
| 432 | Integer value to control debugging output. The initialize value is |
| 433 | taken from the module variable \code{Debug}. Values greater than |
| 434 | three trace each command. |
| 435 | \end{memberdesc} |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 436 | |
| 437 | |
Fred Drake | 363d67c | 1999-07-07 13:42:56 +0000 | [diff] [blame] | 438 | \subsection{IMAP4 Example \label{imap4-example}} |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 439 | |
| 440 | Here is a minimal example (without error checking) that opens a |
| 441 | mailbox and retrieves and prints all messages: |
| 442 | |
| 443 | \begin{verbatim} |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 444 | import getpass, imaplib |
Fred Drake | 363d67c | 1999-07-07 13:42:56 +0000 | [diff] [blame] | 445 | |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 446 | M = imaplib.IMAP4() |
Fred Drake | 363d67c | 1999-07-07 13:42:56 +0000 | [diff] [blame] | 447 | M.login(getpass.getuser(), getpass.getpass()) |
| 448 | M.select() |
| 449 | typ, data = M.search(None, 'ALL') |
Piers Lauder | a3a1668 | 2001-07-20 11:04:19 +0000 | [diff] [blame] | 450 | for num in data[0].split(): |
Fred Drake | 363d67c | 1999-07-07 13:42:56 +0000 | [diff] [blame] | 451 | typ, data = M.fetch(num, '(RFC822)') |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 452 | print 'Message %s\n%s\n' % (num, data[0][1]) |
Fred Drake | 363d67c | 1999-07-07 13:42:56 +0000 | [diff] [blame] | 453 | M.logout() |
Fred Drake | 89de314 | 1998-04-11 04:19:04 +0000 | [diff] [blame] | 454 | \end{verbatim} |