| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="imap4-example.html" /> |
| 13 | <link rel="prev" href="module-imaplib.html" /> |
| 14 | <link rel="parent" href="module-imaplib.html" /> |
| 15 | <link rel="next" href="imap4-example.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>11.10.1 IMAP4 Objects </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="11.10 imaplib " |
| 25 | href="module-imaplib.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="11.10 imaplib " |
| 28 | href="module-imaplib.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="11.10.2 IMAP4 Example" |
| 31 | href="imap4-example.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="module-imaplib.html">11.10 imaplib </A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="module-imaplib.html">11.10 imaplib </A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="imap4-example.html">11.10.2 IMAP4 Example</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION00131010000000000000000"></A><A NAME="imap4-objects"></A> |
| 56 | <BR> |
| 57 | 11.10.1 IMAP4 Objects |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | All IMAP4rev1 commands are represented by methods of the same name, |
| 62 | either upper-case or lower-case. |
| 63 | |
| 64 | <P> |
| 65 | All arguments to commands are converted to strings, except for |
| 66 | "<tt class="samp">AUTHENTICATE</tt>", and the last argument to "<tt class="samp">APPEND</tt>" which is |
| 67 | passed as an IMAP4 literal. If necessary (the string contains IMAP4 |
| 68 | protocol-sensitive characters and isn't enclosed with either |
| 69 | parentheses or double quotes) each string is quoted. However, the |
| 70 | <var>password</var> argument to the "<tt class="samp">LOGIN</tt>" command is always quoted. |
| 71 | If you want to avoid having an argument string quoted |
| 72 | (eg: the <var>flags</var> argument to "<tt class="samp">STORE</tt>") then enclose the string in |
| 73 | parentheses (eg: <code>r'(\Deleted)'</code>). |
| 74 | |
| 75 | <P> |
| 76 | Each command returns a tuple: <code>(<var>type</var>, [<var>data</var>, |
| 77 | ...])</code> where <var>type</var> is usually <code>'OK'</code> or <code>'NO'</code>, |
| 78 | and <var>data</var> is either the text from the command response, or |
| 79 | mandated results from the command. Each <var>data</var> |
| 80 | is either a string, or a tuple. If a tuple, then the first part |
| 81 | is the header of the response, and the second part contains |
| 82 | the data (ie: 'literal' value). |
| 83 | |
| 84 | <P> |
| 85 | The <var>message_set</var> options to commands below is a string specifying one |
| 86 | or more messages to be acted upon. It may be a simple message number |
| 87 | (<code>'1'</code>), a range of message numbers (<code>'2:4'</code>), or a group of |
| 88 | non-contiguous ranges separated by commas (<code>'1:3,6:9'</code>). A range |
| 89 | can contain an asterisk to indicate an infinite upper bound |
| 90 | (<code>'3:*'</code>). |
| 91 | |
| 92 | <P> |
| 93 | An <tt class="class">IMAP4</tt> instance has the following methods: |
| 94 | |
| 95 | <P> |
| 96 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 97 | <td><nobr><b><tt id='l2h-3405' xml:id='l2h-3405' class="method">append</tt></b>(</nobr></td> |
| 98 | <td><var>mailbox, flags, date_time, message</var>)</td></tr></table></dt> |
| 99 | <dd> |
| 100 | Append <var>message</var> to named mailbox. |
| 101 | </dl> |
| 102 | |
| 103 | <P> |
| 104 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 105 | <td><nobr><b><tt id='l2h-3406' xml:id='l2h-3406' class="method">authenticate</tt></b>(</nobr></td> |
| 106 | <td><var>mechanism, authobject</var>)</td></tr></table></dt> |
| 107 | <dd> |
| 108 | Authenticate command -- requires response processing. |
| 109 | |
| 110 | <P> |
| 111 | <var>mechanism</var> specifies which authentication mechanism is to be |
| 112 | used - it should appear in the instance variable <code>capabilities</code> |
| 113 | in the form <code>AUTH=mechanism</code>. |
| 114 | |
| 115 | <P> |
| 116 | <var>authobject</var> must be a callable object: |
| 117 | |
| 118 | <P> |
| 119 | <div class="verbatim"><pre> |
| 120 | data = authobject(response) |
| 121 | </pre></div> |
| 122 | |
| 123 | <P> |
| 124 | It will be called to process server continuation responses. |
| 125 | It should return <code>data</code> that will be encoded and sent to server. |
| 126 | It should return <code>None</code> if the client abort response "<tt class="samp">*</tt>" should |
| 127 | be sent instead. |
| 128 | </dl> |
| 129 | |
| 130 | <P> |
| 131 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 132 | <td><nobr><b><tt id='l2h-3407' xml:id='l2h-3407' class="method">check</tt></b>(</nobr></td> |
| 133 | <td><var></var>)</td></tr></table></dt> |
| 134 | <dd> |
| 135 | Checkpoint mailbox on server. |
| 136 | </dl> |
| 137 | |
| 138 | <P> |
| 139 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 140 | <td><nobr><b><tt id='l2h-3408' xml:id='l2h-3408' class="method">close</tt></b>(</nobr></td> |
| 141 | <td><var></var>)</td></tr></table></dt> |
| 142 | <dd> |
| 143 | Close currently selected mailbox. Deleted messages are removed from |
| 144 | writable mailbox. This is the recommended command before |
| 145 | "<tt class="samp">LOGOUT</tt>". |
| 146 | </dl> |
| 147 | |
| 148 | <P> |
| 149 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 150 | <td><nobr><b><tt id='l2h-3409' xml:id='l2h-3409' class="method">copy</tt></b>(</nobr></td> |
| 151 | <td><var>message_set, new_mailbox</var>)</td></tr></table></dt> |
| 152 | <dd> |
| 153 | Copy <var>message_set</var> messages onto end of <var>new_mailbox</var>. |
| 154 | </dl> |
| 155 | |
| 156 | <P> |
| 157 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 158 | <td><nobr><b><tt id='l2h-3410' xml:id='l2h-3410' class="method">create</tt></b>(</nobr></td> |
| 159 | <td><var>mailbox</var>)</td></tr></table></dt> |
| 160 | <dd> |
| 161 | Create new mailbox named <var>mailbox</var>. |
| 162 | </dl> |
| 163 | |
| 164 | <P> |
| 165 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 166 | <td><nobr><b><tt id='l2h-3411' xml:id='l2h-3411' class="method">delete</tt></b>(</nobr></td> |
| 167 | <td><var>mailbox</var>)</td></tr></table></dt> |
| 168 | <dd> |
| 169 | Delete old mailbox named <var>mailbox</var>. |
| 170 | </dl> |
| 171 | |
| 172 | <P> |
| 173 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 174 | <td><nobr><b><tt id='l2h-3412' xml:id='l2h-3412' class="method">deleteacl</tt></b>(</nobr></td> |
| 175 | <td><var>mailbox, who</var>)</td></tr></table></dt> |
| 176 | <dd> |
| 177 | Delete the ACLs (remove any rights) set for who on mailbox. |
| 178 | |
| 179 | <span class="versionnote">New in version 2.4.</span> |
| 180 | |
| 181 | </dl> |
| 182 | |
| 183 | <P> |
| 184 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 185 | <td><nobr><b><tt id='l2h-3413' xml:id='l2h-3413' class="method">expunge</tt></b>(</nobr></td> |
| 186 | <td><var></var>)</td></tr></table></dt> |
| 187 | <dd> |
| 188 | Permanently remove deleted items from selected mailbox. Generates an |
| 189 | "<tt class="samp">EXPUNGE</tt>" response for each deleted message. Returned data |
| 190 | contains a list of "<tt class="samp">EXPUNGE</tt>" message numbers in order |
| 191 | received. |
| 192 | </dl> |
| 193 | |
| 194 | <P> |
| 195 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 196 | <td><nobr><b><tt id='l2h-3414' xml:id='l2h-3414' class="method">fetch</tt></b>(</nobr></td> |
| 197 | <td><var>message_set, message_parts</var>)</td></tr></table></dt> |
| 198 | <dd> |
| 199 | Fetch (parts of) messages. <var>message_parts</var> should be |
| 200 | a string of message part names enclosed within parentheses, |
| 201 | eg: "<tt class="samp">"(UID BODY[TEXT])"</tt>". Returned data are tuples |
| 202 | of message part envelope and data. |
| 203 | </dl> |
| 204 | |
| 205 | <P> |
| 206 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 207 | <td><nobr><b><tt id='l2h-3415' xml:id='l2h-3415' class="method">getacl</tt></b>(</nobr></td> |
| 208 | <td><var>mailbox</var>)</td></tr></table></dt> |
| 209 | <dd> |
| 210 | Get the "<tt class="samp">ACL</tt>"s for <var>mailbox</var>. |
| 211 | The method is non-standard, but is supported by the "<tt class="samp">Cyrus</tt>" server. |
| 212 | </dl> |
| 213 | |
| 214 | <P> |
| 215 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 216 | <td><nobr><b><tt id='l2h-3416' xml:id='l2h-3416' class="method">getquota</tt></b>(</nobr></td> |
| 217 | <td><var>root</var>)</td></tr></table></dt> |
| 218 | <dd> |
| 219 | Get the "<tt class="samp">quota</tt>" <var>root</var>'s resource usage and limits. |
| 220 | This method is part of the IMAP4 QUOTA extension defined in rfc2087. |
| 221 | |
| 222 | <span class="versionnote">New in version 2.3.</span> |
| 223 | |
| 224 | </dl> |
| 225 | |
| 226 | <P> |
| 227 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 228 | <td><nobr><b><tt id='l2h-3417' xml:id='l2h-3417' class="method">getquotaroot</tt></b>(</nobr></td> |
| 229 | <td><var>mailbox</var>)</td></tr></table></dt> |
| 230 | <dd> |
| 231 | Get the list of "<tt class="samp">quota</tt>" "<tt class="samp">roots</tt>" for the named <var>mailbox</var>. |
| 232 | This method is part of the IMAP4 QUOTA extension defined in rfc2087. |
| 233 | |
| 234 | <span class="versionnote">New in version 2.3.</span> |
| 235 | |
| 236 | </dl> |
| 237 | |
| 238 | <P> |
| 239 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 240 | <td><nobr><b><tt id='l2h-3418' xml:id='l2h-3418' class="method">list</tt></b>(</nobr></td> |
| 241 | <td><var></var><big>[</big><var>directory</var><big>[</big><var>, pattern</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 242 | <dd> |
| 243 | List mailbox names in <var>directory</var> matching |
| 244 | <var>pattern</var>. <var>directory</var> defaults to the top-level mail |
| 245 | folder, and <var>pattern</var> defaults to match anything. Returned data |
| 246 | contains a list of "<tt class="samp">LIST</tt>" responses. |
| 247 | </dl> |
| 248 | |
| 249 | <P> |
| 250 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 251 | <td><nobr><b><tt id='l2h-3419' xml:id='l2h-3419' class="method">login</tt></b>(</nobr></td> |
| 252 | <td><var>user, password</var>)</td></tr></table></dt> |
| 253 | <dd> |
| 254 | Identify the client using a plaintext password. |
| 255 | The <var>password</var> will be quoted. |
| 256 | </dl> |
| 257 | |
| 258 | <P> |
| 259 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 260 | <td><nobr><b><tt id='l2h-3420' xml:id='l2h-3420' class="method">login_cram_md5</tt></b>(</nobr></td> |
| 261 | <td><var>user, password</var>)</td></tr></table></dt> |
| 262 | <dd> |
| 263 | Force use of "<tt class="samp">CRAM-MD5</tt>" authentication when identifying the |
| 264 | client to protect the password. Will only work if the server |
| 265 | "<tt class="samp">CAPABILITY</tt>" response includes the phrase "<tt class="samp">AUTH=CRAM-MD5</tt>". |
| 266 | |
| 267 | <span class="versionnote">New in version 2.3.</span> |
| 268 | |
| 269 | </dl> |
| 270 | |
| 271 | <P> |
| 272 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 273 | <td><nobr><b><tt id='l2h-3421' xml:id='l2h-3421' class="method">logout</tt></b>(</nobr></td> |
| 274 | <td><var></var>)</td></tr></table></dt> |
| 275 | <dd> |
| 276 | Shutdown connection to server. Returns server "<tt class="samp">BYE</tt>" response. |
| 277 | </dl> |
| 278 | |
| 279 | <P> |
| 280 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 281 | <td><nobr><b><tt id='l2h-3422' xml:id='l2h-3422' class="method">lsub</tt></b>(</nobr></td> |
| 282 | <td><var></var><big>[</big><var>directory</var><big>[</big><var>, pattern</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 283 | <dd> |
| 284 | List subscribed mailbox names in directory matching pattern. |
| 285 | <var>directory</var> defaults to the top level directory and |
| 286 | <var>pattern</var> defaults to match any mailbox. |
| 287 | Returned data are tuples of message part envelope and data. |
| 288 | </dl> |
| 289 | |
| 290 | <P> |
| 291 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 292 | <td><nobr><b><tt id='l2h-3423' xml:id='l2h-3423' class="method">myrights</tt></b>(</nobr></td> |
| 293 | <td><var>mailbox</var>)</td></tr></table></dt> |
| 294 | <dd> |
| 295 | Show my ACLs for a mailbox (i.e. the rights that I have on mailbox). |
| 296 | |
| 297 | <span class="versionnote">New in version 2.4.</span> |
| 298 | |
| 299 | </dl> |
| 300 | |
| 301 | <P> |
| 302 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 303 | <td><nobr><b><tt id='l2h-3424' xml:id='l2h-3424' class="method">namespace</tt></b>(</nobr></td> |
| 304 | <td><var></var>)</td></tr></table></dt> |
| 305 | <dd> |
| 306 | Returns IMAP namespaces as defined in RFC2342. |
| 307 | |
| 308 | <span class="versionnote">New in version 2.3.</span> |
| 309 | |
| 310 | </dl> |
| 311 | |
| 312 | <P> |
| 313 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 314 | <td><nobr><b><tt id='l2h-3425' xml:id='l2h-3425' class="method">noop</tt></b>(</nobr></td> |
| 315 | <td><var></var>)</td></tr></table></dt> |
| 316 | <dd> |
| 317 | Send "<tt class="samp">NOOP</tt>" to server. |
| 318 | </dl> |
| 319 | |
| 320 | <P> |
| 321 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 322 | <td><nobr><b><tt id='l2h-3426' xml:id='l2h-3426' class="method">open</tt></b>(</nobr></td> |
| 323 | <td><var>host, port</var>)</td></tr></table></dt> |
| 324 | <dd> |
| 325 | Opens socket to <var>port</var> at <var>host</var>. |
| 326 | The connection objects established by this method |
| 327 | will be used in the <code>read</code>, <code>readline</code>, <code>send</code>, and |
| 328 | <code>shutdown</code> methods. |
| 329 | You may override this method. |
| 330 | </dl> |
| 331 | |
| 332 | <P> |
| 333 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 334 | <td><nobr><b><tt id='l2h-3427' xml:id='l2h-3427' class="method">partial</tt></b>(</nobr></td> |
| 335 | <td><var>message_num, message_part, start, length</var>)</td></tr></table></dt> |
| 336 | <dd> |
| 337 | Fetch truncated part of a message. |
| 338 | Returned data is a tuple of message part envelope and data. |
| 339 | </dl> |
| 340 | |
| 341 | <P> |
| 342 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 343 | <td><nobr><b><tt id='l2h-3428' xml:id='l2h-3428' class="method">proxyauth</tt></b>(</nobr></td> |
| 344 | <td><var>user</var>)</td></tr></table></dt> |
| 345 | <dd> |
| 346 | Assume authentication as <var>user</var>. |
| 347 | Allows an authorised administrator to proxy into any user's mailbox. |
| 348 | |
| 349 | <span class="versionnote">New in version 2.3.</span> |
| 350 | |
| 351 | </dl> |
| 352 | |
| 353 | <P> |
| 354 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 355 | <td><nobr><b><tt id='l2h-3429' xml:id='l2h-3429' class="method">read</tt></b>(</nobr></td> |
| 356 | <td><var>size</var>)</td></tr></table></dt> |
| 357 | <dd> |
| 358 | Reads <var>size</var> bytes from the remote server. |
| 359 | You may override this method. |
| 360 | </dl> |
| 361 | |
| 362 | <P> |
| 363 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 364 | <td><nobr><b><tt id='l2h-3430' xml:id='l2h-3430' class="method">readline</tt></b>(</nobr></td> |
| 365 | <td><var></var>)</td></tr></table></dt> |
| 366 | <dd> |
| 367 | Reads one line from the remote server. |
| 368 | You may override this method. |
| 369 | </dl> |
| 370 | |
| 371 | <P> |
| 372 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 373 | <td><nobr><b><tt id='l2h-3431' xml:id='l2h-3431' class="method">recent</tt></b>(</nobr></td> |
| 374 | <td><var></var>)</td></tr></table></dt> |
| 375 | <dd> |
| 376 | Prompt server for an update. Returned data is <code>None</code> if no new |
| 377 | messages, else value of "<tt class="samp">RECENT</tt>" response. |
| 378 | </dl> |
| 379 | |
| 380 | <P> |
| 381 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 382 | <td><nobr><b><tt id='l2h-3432' xml:id='l2h-3432' class="method">rename</tt></b>(</nobr></td> |
| 383 | <td><var>oldmailbox, newmailbox</var>)</td></tr></table></dt> |
| 384 | <dd> |
| 385 | Rename mailbox named <var>oldmailbox</var> to <var>newmailbox</var>. |
| 386 | </dl> |
| 387 | |
| 388 | <P> |
| 389 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 390 | <td><nobr><b><tt id='l2h-3433' xml:id='l2h-3433' class="method">response</tt></b>(</nobr></td> |
| 391 | <td><var>code</var>)</td></tr></table></dt> |
| 392 | <dd> |
| 393 | Return data for response <var>code</var> if received, or |
| 394 | <code>None</code>. Returns the given code, instead of the usual type. |
| 395 | </dl> |
| 396 | |
| 397 | <P> |
| 398 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 399 | <td><nobr><b><tt id='l2h-3434' xml:id='l2h-3434' class="method">search</tt></b>(</nobr></td> |
| 400 | <td><var>charset, criterion</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt> |
| 401 | <dd> |
| 402 | Search mailbox for matching messages. <var>charset</var> may be |
| 403 | <code>None</code>, in which case no "<tt class="samp">CHARSET</tt>" will be specified in the |
| 404 | request to the server. The IMAP protocol requires that at least one |
| 405 | criterion be specified; an exception will be raised when the server |
| 406 | returns an error. |
| 407 | |
| 408 | <P> |
| 409 | Example: |
| 410 | |
| 411 | <P> |
| 412 | <div class="verbatim"><pre> |
| 413 | # M is a connected IMAP4 instance... |
| 414 | typ, msgnums = M.search(None, 'FROM', '"LDJ"') |
| 415 | |
| 416 | # or: |
| 417 | typ, msgnums = M.search(None, '(FROM "LDJ")') |
| 418 | </pre></div> |
| 419 | </dl> |
| 420 | |
| 421 | <P> |
| 422 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 423 | <td><nobr><b><tt id='l2h-3435' xml:id='l2h-3435' class="method">select</tt></b>(</nobr></td> |
| 424 | <td><var></var><big>[</big><var>mailbox</var><big>[</big><var>, readonly</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 425 | <dd> |
| 426 | Select a mailbox. Returned data is the count of messages in |
| 427 | <var>mailbox</var> ("<tt class="samp">EXISTS</tt>" response). The default <var>mailbox</var> |
| 428 | is <code>'INBOX'</code>. If the <var>readonly</var> flag is set, modifications |
| 429 | to the mailbox are not allowed. |
| 430 | </dl> |
| 431 | |
| 432 | <P> |
| 433 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 434 | <td><nobr><b><tt id='l2h-3436' xml:id='l2h-3436' class="method">send</tt></b>(</nobr></td> |
| 435 | <td><var>data</var>)</td></tr></table></dt> |
| 436 | <dd> |
| 437 | Sends <code>data</code> to the remote server. |
| 438 | You may override this method. |
| 439 | </dl> |
| 440 | |
| 441 | <P> |
| 442 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 443 | <td><nobr><b><tt id='l2h-3437' xml:id='l2h-3437' class="method">setacl</tt></b>(</nobr></td> |
| 444 | <td><var>mailbox, who, what</var>)</td></tr></table></dt> |
| 445 | <dd> |
| 446 | Set an "<tt class="samp">ACL</tt>" for <var>mailbox</var>. |
| 447 | The method is non-standard, but is supported by the "<tt class="samp">Cyrus</tt>" server. |
| 448 | </dl> |
| 449 | |
| 450 | <P> |
| 451 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 452 | <td><nobr><b><tt id='l2h-3438' xml:id='l2h-3438' class="method">setquota</tt></b>(</nobr></td> |
| 453 | <td><var>root, limits</var>)</td></tr></table></dt> |
| 454 | <dd> |
| 455 | Set the "<tt class="samp">quota</tt>" <var>root</var>'s resource <var>limits</var>. |
| 456 | This method is part of the IMAP4 QUOTA extension defined in rfc2087. |
| 457 | |
| 458 | <span class="versionnote">New in version 2.3.</span> |
| 459 | |
| 460 | </dl> |
| 461 | |
| 462 | <P> |
| 463 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 464 | <td><nobr><b><tt id='l2h-3439' xml:id='l2h-3439' class="method">shutdown</tt></b>(</nobr></td> |
| 465 | <td><var></var>)</td></tr></table></dt> |
| 466 | <dd> |
| 467 | Close connection established in <code>open</code>. |
| 468 | You may override this method. |
| 469 | </dl> |
| 470 | |
| 471 | <P> |
| 472 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 473 | <td><nobr><b><tt id='l2h-3440' xml:id='l2h-3440' class="method">socket</tt></b>(</nobr></td> |
| 474 | <td><var></var>)</td></tr></table></dt> |
| 475 | <dd> |
| 476 | Returns socket instance used to connect to server. |
| 477 | </dl> |
| 478 | |
| 479 | <P> |
| 480 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 481 | <td><nobr><b><tt id='l2h-3441' xml:id='l2h-3441' class="method">sort</tt></b>(</nobr></td> |
| 482 | <td><var>sort_criteria, charset, search_criterion</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt> |
| 483 | <dd> |
| 484 | The <code>sort</code> command is a variant of <code>search</code> with sorting |
| 485 | semantics for the results. Returned data contains a space separated |
| 486 | list of matching message numbers. |
| 487 | |
| 488 | <P> |
| 489 | Sort has two arguments before the <var>search_criterion</var> |
| 490 | argument(s); a parenthesized list of <var>sort_criteria</var>, and the |
| 491 | searching <var>charset</var>. Note that unlike <code>search</code>, the |
| 492 | searching <var>charset</var> argument is mandatory. There is also a |
| 493 | <code>uid sort</code> command which corresponds to <code>sort</code> the way |
| 494 | that <code>uid search</code> corresponds to <code>search</code>. The |
| 495 | <code>sort</code> command first searches the mailbox for messages that |
| 496 | match the given searching criteria using the charset argument for |
| 497 | the interpretation of strings in the searching criteria. It then |
| 498 | returns the numbers of matching messages. |
| 499 | |
| 500 | <P> |
| 501 | This is an "<tt class="samp">IMAP4rev1</tt>" extension command. |
| 502 | </dl> |
| 503 | |
| 504 | <P> |
| 505 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 506 | <td><nobr><b><tt id='l2h-3442' xml:id='l2h-3442' class="method">status</tt></b>(</nobr></td> |
| 507 | <td><var>mailbox, names</var>)</td></tr></table></dt> |
| 508 | <dd> |
| 509 | Request named status conditions for <var>mailbox</var>. |
| 510 | </dl> |
| 511 | |
| 512 | <P> |
| 513 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 514 | <td><nobr><b><tt id='l2h-3443' xml:id='l2h-3443' class="method">store</tt></b>(</nobr></td> |
| 515 | <td><var>message_set, command, flag_list</var>)</td></tr></table></dt> |
| 516 | <dd> |
| 517 | Alters flag dispositions for messages in mailbox. <var>command</var> is |
| 518 | specified by section 6.4.6 of <a class="rfc" id='rfcref-90259' xml:id='rfcref-90259' |
| 519 | href="http://www.faqs.org/rfcs/rfc2060.html">RFC 2060</a> as being one of "FLAGS", "+FLAGS", |
| 520 | or "-FLAGS", optionally with a suffix of ".SILENT". |
| 521 | |
| 522 | <P> |
| 523 | For example, to set the delete flag on all messages: |
| 524 | |
| 525 | <P> |
| 526 | <div class="verbatim"><pre> |
| 527 | typ, data = M.search(None, 'ALL') |
| 528 | for num in data[0].split(): |
| 529 | M.store(num, '+FLAGS', '\\Deleted') |
| 530 | M.expunge() |
| 531 | </pre></div> |
| 532 | </dl> |
| 533 | |
| 534 | <P> |
| 535 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 536 | <td><nobr><b><tt id='l2h-3444' xml:id='l2h-3444' class="method">subscribe</tt></b>(</nobr></td> |
| 537 | <td><var>mailbox</var>)</td></tr></table></dt> |
| 538 | <dd> |
| 539 | Subscribe to new mailbox. |
| 540 | </dl> |
| 541 | |
| 542 | <P> |
| 543 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 544 | <td><nobr><b><tt id='l2h-3445' xml:id='l2h-3445' class="method">thread</tt></b>(</nobr></td> |
| 545 | <td><var>threading_algorithm, charset, |
| 546 | search_criterion</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt> |
| 547 | <dd> |
| 548 | The <code>thread</code> command is a variant of <code>search</code> with |
| 549 | threading semantics for the results. Returned data contains a space |
| 550 | separated list of thread members. |
| 551 | |
| 552 | <P> |
| 553 | Thread members consist of zero or more messages numbers, delimited |
| 554 | by spaces, indicating successive parent and child. |
| 555 | |
| 556 | <P> |
| 557 | Thread has two arguments before the <var>search_criterion</var> |
| 558 | argument(s); a <var>threading_algorithm</var>, and the searching |
| 559 | <var>charset</var>. Note that unlike <code>search</code>, the searching |
| 560 | <var>charset</var> argument is mandatory. There is also a <code>uid |
| 561 | thread</code> command which corresponds to <code>thread</code> the way that |
| 562 | <code>uid search</code> corresponds to <code>search</code>. The <code>thread</code> |
| 563 | command first searches the mailbox for messages that match the given |
| 564 | searching criteria using the charset argument for the interpretation |
| 565 | of strings in the searching criteria. It then returns the matching |
| 566 | messages threaded according to the specified threading algorithm. |
| 567 | |
| 568 | <P> |
| 569 | This is an "<tt class="samp">IMAP4rev1</tt>" extension command. |
| 570 | <span class="versionnote">New in version 2.4.</span> |
| 571 | |
| 572 | </dl> |
| 573 | |
| 574 | <P> |
| 575 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 576 | <td><nobr><b><tt id='l2h-3446' xml:id='l2h-3446' class="method">uid</tt></b>(</nobr></td> |
| 577 | <td><var>command, arg</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt> |
| 578 | <dd> |
| 579 | Execute command args with messages identified by UID, rather than |
| 580 | message number. Returns response appropriate to command. At least |
| 581 | one argument must be supplied; if none are provided, the server will |
| 582 | return an error and an exception will be raised. |
| 583 | </dl> |
| 584 | |
| 585 | <P> |
| 586 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 587 | <td><nobr><b><tt id='l2h-3447' xml:id='l2h-3447' class="method">unsubscribe</tt></b>(</nobr></td> |
| 588 | <td><var>mailbox</var>)</td></tr></table></dt> |
| 589 | <dd> |
| 590 | Unsubscribe from old mailbox. |
| 591 | </dl> |
| 592 | |
| 593 | <P> |
| 594 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 595 | <td><nobr><b><tt id='l2h-3448' xml:id='l2h-3448' class="method">xatom</tt></b>(</nobr></td> |
| 596 | <td><var>name</var><big>[</big><var>, arg</var><big>[</big><var>, ...</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 597 | <dd> |
| 598 | Allow simple extension commands notified by server in |
| 599 | "<tt class="samp">CAPABILITY</tt>" response. |
| 600 | </dl> |
| 601 | |
| 602 | <P> |
| 603 | Instances of <tt class="class">IMAP4_SSL</tt> have just one additional method: |
| 604 | |
| 605 | <P> |
| 606 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 607 | <td><nobr><b><tt id='l2h-3449' xml:id='l2h-3449' class="method">ssl</tt></b>(</nobr></td> |
| 608 | <td><var></var>)</td></tr></table></dt> |
| 609 | <dd> |
| 610 | Returns SSLObject instance used for the secure connection with the server. |
| 611 | </dl> |
| 612 | |
| 613 | <P> |
| 614 | The following attributes are defined on instances of <tt class="class">IMAP4</tt>: |
| 615 | |
| 616 | <P> |
| 617 | <dl><dt><b><tt id='l2h-3450' xml:id='l2h-3450' class="member">PROTOCOL_VERSION</tt></b></dt> |
| 618 | <dd> |
| 619 | The most recent supported protocol in the |
| 620 | "<tt class="samp">CAPABILITY</tt>" response from the server. |
| 621 | </dl> |
| 622 | |
| 623 | <P> |
| 624 | <dl><dt><b><tt id='l2h-3451' xml:id='l2h-3451' class="member">debug</tt></b></dt> |
| 625 | <dd> |
| 626 | Integer value to control debugging output. The initialize value is |
| 627 | taken from the module variable <code>Debug</code>. Values greater than |
| 628 | three trace each command. |
| 629 | </dl> |
| 630 | |
| 631 | <P> |
| 632 | |
| 633 | <DIV CLASS="navigation"> |
| 634 | <div class='online-navigation'> |
| 635 | <p></p><hr /> |
| 636 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 637 | <tr> |
| 638 | <td class='online-navigation'><a rel="prev" title="11.10 imaplib " |
| 639 | href="module-imaplib.html"><img src='../icons/previous.png' |
| 640 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 641 | <td class='online-navigation'><a rel="parent" title="11.10 imaplib " |
| 642 | href="module-imaplib.html"><img src='../icons/up.png' |
| 643 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 644 | <td class='online-navigation'><a rel="next" title="11.10.2 IMAP4 Example" |
| 645 | href="imap4-example.html"><img src='../icons/next.png' |
| 646 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 647 | <td align="center" width="100%">Python Library Reference</td> |
| 648 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 649 | href="contents.html"><img src='../icons/contents.png' |
| 650 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 651 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 652 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 653 | <td class='online-navigation'><a rel="index" title="Index" |
| 654 | href="genindex.html"><img src='../icons/index.png' |
| 655 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 656 | </tr></table> |
| 657 | <div class='online-navigation'> |
| 658 | <b class="navlabel">Previous:</b> |
| 659 | <a class="sectref" rel="prev" href="module-imaplib.html">11.10 imaplib </A> |
| 660 | <b class="navlabel">Up:</b> |
| 661 | <a class="sectref" rel="parent" href="module-imaplib.html">11.10 imaplib </A> |
| 662 | <b class="navlabel">Next:</b> |
| 663 | <a class="sectref" rel="next" href="imap4-example.html">11.10.2 IMAP4 Example</A> |
| 664 | </div> |
| 665 | </div> |
| 666 | <hr /> |
| 667 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 668 | </DIV> |
| 669 | <!--End of Navigation Panel--> |
| 670 | <ADDRESS> |
| 671 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 672 | </ADDRESS> |
| 673 | </BODY> |
| 674 | </HTML> |