From d3c821ee71b6eeb79357469e52976913b847c616 Mon Sep 17 00:00:00 2001 From: Piers Lauder Date: Fri, 22 Nov 2002 05:47:39 +0000 Subject: [PATCH] added details of new IMAP4_stream class; emphasised meaning of data part of command results; added proxyauth command description --- Doc/lib/libimaplib.tex | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex index ba7667edaa0..1edbff7ab93 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 ; +% Based on HTML documentation by Piers Lauder ; % converted by Fred L. Drake, Jr. . % Revised by ESR, January 2000. % Changes for IMAP4_SSL by Tino Lange , March 2002 +% Changes for IMAP4_stream by Piers Lauder , 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{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: +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 @@ If \var{port} is omitted, the standard IMAP4-over-SSL port (993) is used. 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 @@ parentheses (eg: \code{r'(\e Deleted)'}). 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 @@ An \class{IMAP4} instance has the following methods: 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 @@ An \class{IMAP4} instance has the following methods: 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.