diff options
| -rw-r--r-- | Doc/lib/libimaplib.tex | 228 | ||||
| -rw-r--r-- | Doc/libimaplib.tex | 228 |
2 files changed, 456 insertions, 0 deletions
diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex new file mode 100644 index 0000000..7cb4bb3 --- /dev/null +++ b/Doc/lib/libimaplib.tex @@ -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} diff --git a/Doc/libimaplib.tex b/Doc/libimaplib.tex new file mode 100644 index 0000000..7cb4bb3 --- /dev/null +++ b/Doc/libimaplib.tex @@ -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} |