1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
%
% The imaplib module was written by Piers Lauder.
\section{Standard Module \module{imaplib}}
\stmodindex{imaplib}
\label{module-imaplib}
\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 \code{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}
The following utility functions are defined:
\begin{funcdesc}{Internaldate2tuple}{datestr}
Converts an IMAP4 INTERNALDATE string to Coordinated Universal
Time. Returns a \module{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 \module{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}
\subsection{IMAP4 Objects}
\label{imap4-objects}
All IMAP4rev1 commands are represented by methods of the same name,
either upper-case or lower-case.
Each command returns a tuple: \code{(}\var{type}, \code{[}\var{data},
...\code{])} 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. 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.
\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}{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, criteria}
Search mailbox for matching messages. Returned data contains a space
separated list of matching message numbers.
\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}{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, args}
Execute command args with messages identified by UID, rather than
message number. Returns response appropriate to command.
\end{methoddesc}
\begin{methoddesc}{unsubscribe}{mailbox}
Unsubscribe from old mailbox.
\end{methoddesc}
\begin{methoddesc}{xatom}{name\optional{, arg1\optional{, arg2}}}
Allow simple extension commands notified by server in
\samp{CAPABILITY} response.
\end{methoddesc}
\class{IMAP4} instances have a variable \member{PROTOCOL_VERSION} that
is set to the most recent supported protocol in the \samp{CAPABILITY}
response.
Finally, \class{IMAP4} instances have a variable debug which can be
set to an integer to turn on debugging. Values greater than 3 trace
each command.
\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}
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}
|
