traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

added details of new IMAP4_stream class; emphasised meaning of data part of command results; added proxyauth command description

This commit is contained in:
Piers Lauder 2002-11-22 05:47:39 +00:00
parent f7aba23644
commit d3c821ee71
1 changed files with 29 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
Doc/lib/libimaplib.tex
View File

@ -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{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.