First cut at documentation for imaplib. Based on original documentation by
Piers Lauders.
This commit is contained in:
Fred Drake
parent
756a9e87b1
commit
89de314cfc
|
|
@ -0,0 +1,228 @@
|
||||||
|
% Based on HTML documentation by Piers Lauders <piers@staff.cs.usyd.edu.au>;
|
||||||
|
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
|
||||||
|
%
|
||||||
|
% The imaplib module was written by Piers Lauders.
|
||||||
|
|
||||||
|
\section{Standard Module \module{imaplib}}
|
||||||
|
\stmodindex{imaplib}
|
||||||
|
\label{module-imaplib}
|
||||||
|
|
||||||
|
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}
|
||||||
|
|
||||||
|
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}{directory='""', pattern='*'}
|
||||||
|
List mailbox names in directory matching pattern. 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}{directory='""', pattern='*'}
|
||||||
|
List subscribed mailbox names in directory matching
|
||||||
|
pattern. 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}
|
||||||
|
|
||||||
|
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}
|
||||||
|
|
@ -0,0 +1,228 @@
|
||||||
|
% Based on HTML documentation by Piers Lauders <piers@staff.cs.usyd.edu.au>;
|
||||||
|
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
|
||||||
|
%
|
||||||
|
% The imaplib module was written by Piers Lauders.
|
||||||
|
|
||||||
|
\section{Standard Module \module{imaplib}}
|
||||||
|
\stmodindex{imaplib}
|
||||||
|
\label{module-imaplib}
|
||||||
|
|
||||||
|
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}
|
||||||
|
|
||||||
|
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}{directory='""', pattern='*'}
|
||||||
|
List mailbox names in directory matching pattern. 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}{directory='""', pattern='*'}
|
||||||
|
List subscribed mailbox names in directory matching
|
||||||
|
pattern. 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}
|
||||||
|
|
||||||
|
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}
|
||||||
Loading…
Reference in New Issue