Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-imaplib.html
CommitLineData
86530b38
AT
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="module-nntplib.html" />
13<link rel="prev" href="module-poplib.html" />
14<link rel="parent" href="internet.html" />
15<link rel="next" href="imap4-objects.html" />
16<meta name='aesop' content='information' />
17<title>11.10 imaplib -- IMAP4 protocol client</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.9.2 POP3 Example"
25 href="pop3-example.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. Internet Protocols and"
28 href="internet.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.1 IMAP4 Objects"
31 href="imap4-objects.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="pop3-example.html">11.9.2 POP3 Example</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="imap4-objects.html">11.10.1 IMAP4 Objects</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION00131000000000000000000">
5611.10 <tt class="module">imaplib</tt> --
57 IMAP4 protocol client</A>
58</H1>
59
60<P>
61<A NAME="module-imaplib"></A>
62
63<P>
64<a id='l2h-3392' xml:id='l2h-3392'></a><a id='l2h-3393' xml:id='l2h-3393'></a><a id='l2h-3394' xml:id='l2h-3394'></a>
65<P>
66This module defines three classes, <tt class="class">IMAP4</tt>, <tt class="class">IMAP4_SSL</tt>
67and <tt class="class">IMAP4_stream</tt>, which encapsulate a
68connection to an IMAP4 server and implement a large subset of the
69IMAP4rev1 client protocol as defined in <a class="rfc" id='rfcref-90207' xml:id='rfcref-90207'
70href="http://www.faqs.org/rfcs/rfc2060.html">RFC 2060</a>. It is backward
71compatible with IMAP4 (<a class="rfc" id='rfcref-90209' xml:id='rfcref-90209'
72href="http://www.faqs.org/rfcs/rfc1730.html">RFC 1730</a>) servers, but note that the
73"<tt class="samp">STATUS</tt>" command is not supported in IMAP4.
74
75<P>
76Three classes are provided by the <tt class="module">imaplib</tt> module,
77<tt class="class">IMAP4</tt> is the base class:
78
79<P>
80<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
81 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3395' xml:id='l2h-3395' class="class">IMAP4</tt></b>(</nobr></td>
82 <td><var></var><big>[</big><var>host</var><big>[</big><var>, port</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
83<dd>
84This class implements the actual IMAP4 protocol. The connection is
85created and protocol version (IMAP4 or IMAP4rev1) is determined when
86the instance is initialized.
87If <var>host</var> is not specified, <code>''</code> (the local host) is used.
88If <var>port</var> is omitted, the standard IMAP4 port (143) is used.
89</dl>
90
91<P>
92Three exceptions are defined as attributes of the <tt class="class">IMAP4</tt> class:
93
94<P>
95<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-3396' xml:id='l2h-3396' class="exception">IMAP4.error</tt></b></dt>
96<dd>
97Exception raised on any errors. The reason for the exception is
98passed to the constructor as a string.
99</dd></dl>
100
101<P>
102<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-3397' xml:id='l2h-3397' class="exception">IMAP4.abort</tt></b></dt>
103<dd>
104IMAP4 server errors cause this exception to be raised. This is a
105sub-class of <tt class="exception">IMAP4.error</tt>. Note that closing the instance
106and instantiating a new one will usually allow recovery from this
107exception.
108</dd></dl>
109
110<P>
111<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-3398' xml:id='l2h-3398' class="exception">IMAP4.readonly</tt></b></dt>
112<dd>
113This exception is raised when a writable mailbox has its status
114changed by the server. This is a sub-class of
115<tt class="exception">IMAP4.error</tt>. Some other client now has write permission,
116and the mailbox will need to be re-opened to re-obtain write
117permission.
118</dd></dl>
119
120<P>
121There's also a subclass for secure connections:
122
123<P>
124<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
125 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3399' xml:id='l2h-3399' class="class">IMAP4_SSL</tt></b>(</nobr></td>
126 <td><var></var><big>[</big><var>host</var><big>[</big><var>, port</var><big>[</big><var>,
127 keyfile</var><big>[</big><var>, certfile</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
128<dd>
129This is a subclass derived from <tt class="class">IMAP4</tt> that connects over an
130SSL encrypted socket (to use this class you need a socket module that
131was compiled with SSL support). If <var>host</var> is not specified,
132<code>''</code> (the local host) is used. If <var>port</var> is omitted, the
133standard IMAP4-over-SSL port (993) is used. <var>keyfile</var> and
134<var>certfile</var> are also optional - they can contain a PEM formatted
135private key and certificate chain file for the SSL connection.
136</dl>
137
138<P>
139The second subclass allows for connections created by a child process:
140
141<P>
142<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
143 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3400' xml:id='l2h-3400' class="class">IMAP4_stream</tt></b>(</nobr></td>
144 <td><var>command</var>)</td></tr></table></dt>
145<dd>
146This is a subclass derived from <tt class="class">IMAP4</tt> that connects
147to the <code>stdin/stdout</code> file descriptors created by passing
148<var>command</var> to <code>os.popen2()</code>.
149
150<span class="versionnote">New in version 2.3.</span>
151
152</dl>
153
154<P>
155The following utility functions are defined:
156
157<P>
158<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
159 <td><nobr><b><tt id='l2h-3401' xml:id='l2h-3401' class="function">Internaldate2tuple</tt></b>(</nobr></td>
160 <td><var>datestr</var>)</td></tr></table></dt>
161<dd>
162 Converts an IMAP4 INTERNALDATE string to Coordinated Universal
163 Time. Returns a <tt class="module"><a href="module-time.html">time</a></tt> module tuple.
164</dl>
165
166<P>
167<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
168 <td><nobr><b><tt id='l2h-3402' xml:id='l2h-3402' class="function">Int2AP</tt></b>(</nobr></td>
169 <td><var>num</var>)</td></tr></table></dt>
170<dd>
171 Converts an integer into a string representation using characters
172 from the set [<code>A</code> .. <code>P</code>].
173</dl>
174
175<P>
176<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
177 <td><nobr><b><tt id='l2h-3403' xml:id='l2h-3403' class="function">ParseFlags</tt></b>(</nobr></td>
178 <td><var>flagstr</var>)</td></tr></table></dt>
179<dd>
180 Converts an IMAP4 "<tt class="samp">FLAGS</tt>" response to a tuple of individual
181 flags.
182</dl>
183
184<P>
185<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
186 <td><nobr><b><tt id='l2h-3404' xml:id='l2h-3404' class="function">Time2Internaldate</tt></b>(</nobr></td>
187 <td><var>date_time</var>)</td></tr></table></dt>
188<dd>
189 Converts a <tt class="module"><a href="module-time.html">time</a></tt> module tuple to an IMAP4
190 "<tt class="samp">INTERNALDATE</tt>" representation. Returns a string in the form:
191 <code>"DD-Mmm-YYYY HH:MM:SS +HHMM"</code> (including double-quotes).
192</dl>
193
194<P>
195Note that IMAP4 message numbers change as the mailbox changes; in
196particular, after an "<tt class="samp">EXPUNGE</tt>" command performs deletions the
197remaining messages are renumbered. So it is highly advisable to use
198UIDs instead, with the UID command.
199
200<P>
201At the end of the module, there is a test section that contains a more
202extensive example of usage.
203
204<P>
205<div class="seealso">
206 <p class="heading">See Also:</p>
207
208 <div class="seetext"><p>Documents describing the protocol, and sources and binaries
209 for servers implementing it, can all be found at the
210 University of Washington's <em>IMAP Information Center</em>
211 (<a class="url" href="http://www.cac.washington.edu/imap/">http://www.cac.washington.edu/imap/</a>).</p></div>
212</div>
213
214<P>
215
216<p><br /></p><hr class='online-navigation' />
217<div class='online-navigation'>
218<!--Table of Child-Links-->
219<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
220
221<UL CLASS="ChildLinks">
222<LI><A href="imap4-objects.html">11.10.1 IMAP4 Objects</a>
223<LI><A href="imap4-example.html">11.10.2 IMAP4 Example</a>
224</ul>
225<!--End of Table of Child-Links-->
226</div>
227
228<DIV CLASS="navigation">
229<div class='online-navigation'>
230<p></p><hr />
231<table align="center" width="100%" cellpadding="0" cellspacing="2">
232<tr>
233<td class='online-navigation'><a rel="prev" title="11.9.2 POP3 Example"
234 href="pop3-example.html"><img src='../icons/previous.png'
235 border='0' height='32' alt='Previous Page' width='32' /></A></td>
236<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
237 href="internet.html"><img src='../icons/up.png'
238 border='0' height='32' alt='Up One Level' width='32' /></A></td>
239<td class='online-navigation'><a rel="next" title="11.10.1 IMAP4 Objects"
240 href="imap4-objects.html"><img src='../icons/next.png'
241 border='0' height='32' alt='Next Page' width='32' /></A></td>
242<td align="center" width="100%">Python Library Reference</td>
243<td class='online-navigation'><a rel="contents" title="Table of Contents"
244 href="contents.html"><img src='../icons/contents.png'
245 border='0' height='32' alt='Contents' width='32' /></A></td>
246<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
247 border='0' height='32' alt='Module Index' width='32' /></a></td>
248<td class='online-navigation'><a rel="index" title="Index"
249 href="genindex.html"><img src='../icons/index.png'
250 border='0' height='32' alt='Index' width='32' /></A></td>
251</tr></table>
252<div class='online-navigation'>
253<b class="navlabel">Previous:</b>
254<a class="sectref" rel="prev" href="pop3-example.html">11.9.2 POP3 Example</A>
255<b class="navlabel">Up:</b>
256<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
257<b class="navlabel">Next:</b>
258<a class="sectref" rel="next" href="imap4-objects.html">11.10.1 IMAP4 Objects</A>
259</div>
260</div>
261<hr />
262<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
263</DIV>
264<!--End of Navigation Panel-->
265<ADDRESS>
266See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
267</ADDRESS>
268</BODY>
269</HTML>