added details of new IMAP4_stream class; emphasised meaning of data part of command results; added proxyauth command description
diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex
index ba7667e..1edbff7 100644
--- a/Doc/lib/libimaplib.tex
+++ b/Doc/lib/libimaplib.tex
@@ -3,24 +3,26 @@
\declaremodule{standard}{imaplib}
\modulesynopsis{IMAP4 protocol client (requires sockets).}
-\moduleauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}
-\sectionauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}
+\moduleauthor{Piers Lauder}{piers@communitysolutions.com.au}
+\sectionauthor{Piers Lauder}{piers@communitysolutions.com.au}
-% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
+% Based on HTML documentation by Piers Lauder <piers@communitysolutions.com.au>;
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
% Revised by ESR, January 2000.
% Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
+% Changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>, November 2002
\indexii{IMAP4}{protocol}
\indexii{IMAP4_SSL}{protocol}
+\indexii{IMAP4_stream}{protocol}
-This module defines two classes, \class{IMAP4} and \class{IMAP4_SSL}, which encapsulate a
+This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL} and \class{IMAP4_stream}, which encapsulate a
connection to an IMAP4 server and implement a large subset of 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.
-Two classes are provided by the \module{imaplib} module, \class{IMAP4} is the base class:
+Three classes are provided by the \module{imaplib} module, \class{IMAP4} is the base class:
\begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
This class implements the actual IMAP4 protocol. The connection is
@@ -30,7 +32,7 @@
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:
+Three 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
@@ -61,6 +63,13 @@
private key and certificate chain file for the SSL connection.
\end{classdesc}
+The second subclass allows for connections created by a child process:
+
+\begin{classdesc}{IMAP4_stream}{command}
+This is a subclass derived from \class{IMAP4} that connects
+to the \code{stdin/stdout} file descriptors created by passing \var{command} to \code{os.popen2()}.
+\end{classdesc}
+
The following utility functions are defined:
\begin{funcdesc}{Internaldate2tuple}{datestr}
@@ -119,7 +128,10 @@
Each command returns a tuple: \code{(\var{type}, [\var{data},
...])} 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.
+mandated results from the command. Each \var{data}
+is either a string, or a tuple. If a tuple, then the first part
+is the header of the response, and the second part contains
+the data (ie: 'literal' value).
An \class{IMAP4} instance has the following methods:
@@ -198,6 +210,11 @@
The \var{password} will be quoted.
\end{methoddesc}
+\begin{methoddesc}{login_cram_md5}{user, password}
+ Force use of \samp{CRAM-MD5} authentication when identifying the client to protect the password.
+ Will only work if the server \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}.
+\end{methoddesc}
+
\begin{methoddesc}{logout}{}
Shutdown connection to server. Returns server \samp{BYE} response.
\end{methoddesc}
@@ -225,6 +242,11 @@
Returned data is a tuple of message part envelope and data.
\end{methoddesc}
+\begin{methoddesc}{proxyauth}{user}
+ Assume authentication as \var{user}.
+ Allows an authorised administrator to proxy into any user's mailbox.
+\end{methoddesc}
+
\begin{methoddesc}{read}{size}
Reads \var{size} bytes from the remote server.
You may override this method.