Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

re-wrap paragraphs containing long lines

This commit is contained in:
Fred Drake 2004-07-30 19:12:38 +00:00
parent 69013d070e
commit 63a5d0b1cf
1 changed files with 56 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
Doc/lib/libimaplib.tex
View File

@ -6,23 +6,27 @@
\moduleauthor{Piers Lauder}{piers@communitysolutions.com.au} \moduleauthor{Piers Lauder}{piers@communitysolutions.com.au}
\sectionauthor{Piers Lauder}{piers@communitysolutions.com.au} \sectionauthor{Piers Lauder}{piers@communitysolutions.com.au}
% Based on HTML documentation by Piers Lauder <piers@communitysolutions.com.au>; % Based on HTML documentation by Piers Lauder
% <piers@communitysolutions.com.au>;
% converted by Fred L. Drake, Jr. <fdrake@acm.org>. % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
% Revised by ESR, January 2000. % Revised by ESR, January 2000.
% Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002 % 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 % Changes for IMAP4_stream by Piers Lauder
% <piers@communitysolutions.com.au>, November 2002
\indexii{IMAP4}{protocol} \indexii{IMAP4}{protocol}
\indexii{IMAP4_SSL}{protocol} \indexii{IMAP4_SSL}{protocol}
\indexii{IMAP4_stream}{protocol} \indexii{IMAP4_stream}{protocol}
This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL} and \class{IMAP4_stream}, 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 connection to an IMAP4 server and implement a large subset of the
IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward
compatible with IMAP4 (\rfc{1730}) servers, but note that the compatible with IMAP4 (\rfc{1730}) servers, but note that the
\samp{STATUS} command is not supported in IMAP4. \samp{STATUS} command is not supported in IMAP4.
Three 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}}} \begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
This class implements the actual IMAP4 protocol. The connection is This class implements the actual IMAP4 protocol. The connection is
@ -47,19 +51,23 @@ exception.
\end{excdesc} \end{excdesc}
\begin{excdesc}{IMAP4.readonly} \begin{excdesc}{IMAP4.readonly}
This exception is raised when a writable mailbox has its status changed by the server. This is a This exception is raised when a writable mailbox has its status
sub-class of \exception{IMAP4.error}. Some other client now has write permission, changed by the server. This is a sub-class of
and the mailbox will need to be re-opened to re-obtain write permission. \exception{IMAP4.error}. Some other client now has write permission,
and the mailbox will need to be re-opened to re-obtain write
permission.
\end{excdesc} \end{excdesc}
There's also a subclass for secure connections: There's also a subclass for secure connections:
\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{, keyfile\optional{, certfile}}}}} \begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{,
This is a subclass derived from \class{IMAP4} that connects over an SSL encrypted socket keyfile\optional{, certfile}}}}}
(to use this class you need a socket module that was compiled with SSL support). This is a subclass derived from \class{IMAP4} that connects over an
If \var{host} is not specified, \code{''} (the local host) is used. SSL encrypted socket (to use this class you need a socket module that
If \var{port} is omitted, the standard IMAP4-over-SSL port (993) is used. was compiled with SSL support). If \var{host} is not specified,
\var{keyfile} and \var{certfile} are also optional - they can contain a PEM formatted \code{''} (the local host) is used. If \var{port} is omitted, the
standard IMAP4-over-SSL port (993) is used. \var{keyfile} and
\var{certfile} are also optional - they can contain a PEM formatted
private key and certificate chain file for the SSL connection. private key and certificate chain file for the SSL connection.
\end{classdesc} \end{classdesc}
@ -67,7 +75,8 @@ The second subclass allows for connections created by a child process:
\begin{classdesc}{IMAP4_stream}{command} \begin{classdesc}{IMAP4_stream}{command}
This is a subclass derived from \class{IMAP4} that connects 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()}. to the \code{stdin/stdout} file descriptors created by passing
\var{command} to \code{os.popen2()}.
\versionadded{2.3} \versionadded{2.3}
\end{classdesc} \end{classdesc}
@ -144,9 +153,9 @@ An \class{IMAP4} instance has the following methods:
\begin{methoddesc}{authenticate}{mechanism, authobject} \begin{methoddesc}{authenticate}{mechanism, authobject}
Authenticate command --- requires response processing. Authenticate command --- requires response processing.
\var{mechanism} specifies which authentication mechanism is to \var{mechanism} specifies which authentication mechanism is to be
be used - it should appear in the instance variable \code{capabilities} in the used - it should appear in the instance variable \code{capabilities}
form \code{AUTH=mechanism}. in the form \code{AUTH=mechanism}.
\var{authobject} must be a callable object: \var{authobject} must be a callable object:
@ -231,8 +240,9 @@ data = authobject(response)
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{login_cram_md5}{user, password} \begin{methoddesc}{login_cram_md5}{user, password}
Force use of \samp{CRAM-MD5} authentication when identifying the client to protect the password. Force use of \samp{CRAM-MD5} authentication when identifying the
Will only work if the server \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}. client to protect the password. Will only work if the server
\samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}.
\versionadded{2.3} \versionadded{2.3}
\end{methoddesc} \end{methoddesc}
@ -264,7 +274,8 @@ data = authobject(response)
\begin{methoddesc}{open}{host, port} \begin{methoddesc}{open}{host, port}
Opens socket to \var{port} at \var{host}. Opens socket to \var{port} at \var{host}.
The connection objects established by this method The connection objects established by this method
will be used in the \code{read}, \code{readline}, \code{send}, and \code{shutdown} methods. will be used in the \code{read}, \code{readline}, \code{send}, and
\code{shutdown} methods.
You may override this method. You may override this method.
\end{methoddesc} \end{methoddesc}
@ -355,16 +366,17 @@ msgnums = M.search(None, '(FROM "LDJ")')
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{sort}{sort_criteria, charset, search_criterion\optional{, ...}} \begin{methoddesc}{sort}{sort_criteria, charset, search_criterion\optional{, ...}}
The \code{sort} command is a variant of \code{search} with sorting semantics for The \code{sort} command is a variant of \code{search} with sorting
the results. Returned data contains a space semantics for the results. Returned data contains a space separated
separated list of matching message numbers. list of matching message numbers.
Sort has two arguments before the \var{search_criterion} Sort has two arguments before the \var{search_criterion}
argument(s); a parenthesized list of \var{sort_criteria}, and the searching \var{charset}. argument(s); a parenthesized list of \var{sort_criteria}, and the
Note that unlike \code{search}, the searching \var{charset} argument is mandatory. searching \var{charset}. Note that unlike \code{search}, the
There is also a \code{uid sort} command which corresponds to \code{sort} the way searching \var{charset} argument is mandatory. There is also a
that \code{uid search} corresponds to \code{search}. \code{uid sort} command which corresponds to \code{sort} the way
The \code{sort} command first searches the mailbox for messages that that \code{uid search} corresponds to \code{search}. The
\code{sort} command first searches the mailbox for messages that
match the given searching criteria using the charset argument for match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It then the interpretation of strings in the searching criteria. It then
returns the numbers of matching messages. returns the numbers of matching messages.
@ -384,24 +396,25 @@ msgnums = M.search(None, '(FROM "LDJ")')
Subscribe to new mailbox. Subscribe to new mailbox.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{thread}{threading_algorithm, charset, search_criterion\optional{, ...}} \begin{methoddesc}{thread}{threading_algorithm, charset,
The \code{thread} command is a variant of \code{search} with threading semantics for search_criterion\optional{, ...}}
the results. Returned data contains a space The \code{thread} command is a variant of \code{search} with
threading semantics for the results. Returned data contains a space
separated list of thread members. separated list of thread members.
Thread members consist of zero or more messages numbers, delimited by spaces, Thread members consist of zero or more messages numbers, delimited
indicating successive parent and child. by spaces, indicating successive parent and child.
Thread has two arguments before the \var{search_criterion} Thread has two arguments before the \var{search_criterion}
argument(s); a \var{threading_algorithm}, and the searching \var{charset}. argument(s); a \var{threading_algorithm}, and the searching
Note that unlike \code{search}, the searching \var{charset} argument is mandatory. \var{charset}. Note that unlike \code{search}, the searching
There is also a \code{uid thread} command which corresponds to \code{thread} the way \var{charset} argument is mandatory. There is also a \code{uid
that \code{uid search} corresponds to \code{search}. thread} command which corresponds to \code{thread} the way that
The \code{thread} command first searches the mailbox for messages that \code{uid search} corresponds to \code{search}. The \code{thread}
match the given searching criteria using the charset argument for command first searches the mailbox for messages that match the given
the interpretation of strings in the searching criteria. It thren searching criteria using the charset argument for the interpretation
returns the matching messages threaded according to the specified of strings in the searching criteria. It thren returns the matching
threading algorithm. messages threaded according to the specified threading algorithm.
This is an \samp{IMAP4rev1} extension command. \versionadded{2.4} This is an \samp{IMAP4rev1} extension command. \versionadded{2.4}
\end{methoddesc} \end{methoddesc}