diff options
| -rw-r--r-- | Doc/lib/libimaplib.tex | 15 | ||||
| -rw-r--r-- | Doc/lib/libpoplib.tex | 25 |
2 files changed, 31 insertions, 9 deletions
diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex index 8fdc359..4f11fb0 100644 --- a/Doc/lib/libimaplib.tex +++ b/Doc/lib/libimaplib.tex @@ -8,14 +8,15 @@ % Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>; % converted by Fred L. Drake, Jr. <fdrake@acm.org>. +% Revised by ESR, January 2000. \indexii{IMAP4}{protocol} 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. +connection to an IMAP4 server and implements 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. A single class is provided by the \module{imaplib} module: @@ -71,8 +72,10 @@ The following utility functions are defined: \end{funcdesc} -Note that IMAP4 message numbers change as the mailbox changes, so it -is highly advisable to use UIDs instead, with the UID command. +Note that IMAP4 message numbers change as the mailbox changes; in +particular, after an \samp{EXPUNGE} command performs deletions the +remaining messages are renumbered. 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. diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex index d75e6da..7e3780b 100644 --- a/Doc/lib/libpoplib.tex +++ b/Doc/lib/libpoplib.tex @@ -8,6 +8,7 @@ %Even though I put it into LaTeX, I cannot really claim that I wrote %it since I just stole most of it from the poplib.py source code and %the imaplib ``chapter''. +%Revised by ESR, January 2000 \indexii{POP3}{protocol} @@ -16,6 +17,12 @@ connection to an POP3 server and implements protocol as defined in \rfc{1725}. The \class{POP3} class supports both the minimal and optional command sets. +Note that POP3, though widely supported, is obsolescent. The +implementation quality of POP3 servers varies widely, and too many are +quite poor. If your mailserver supports IMAP, you would be better off +using the \refmodule{IMAP} class, as IMAP servers tend to be better +implemented. + A single class is provided by the \module{poplib} module: \begin{classdesc}{POP3}{host\optional{, port}} @@ -75,12 +82,15 @@ set, it is the message to list. \end{methoddesc} \begin{methoddesc}{retr}{which} -Retrieve whole message number \var{which}. Result is in form -\code{(\var{response}, ['line', ...], \var{octets})}. +Retrieve whole message number \var{which}, and set its seen flag. +Result is in form \code{(\var{response}, ['line', ...], \var{octets})}. \end{methoddesc} \begin{methoddesc}{dele}{which} -Delete message number \var{which}. +Flag message number \var{which} for deletion. On most servers +deletions are not actually performed until QUIT (the major exception is +Eudora QPOP, which deliberately violates the RFCs by doing pending +deletes on any disconnect). \end{methoddesc} \begin{methoddesc}{rset}{} @@ -99,6 +109,12 @@ Signoff: commit changes, unlock mailbox, drop connection. Retrieves the message header plus \var{howmuch} lines of the message after the header of message number \var{which}. Result is in form \code{(\var{response}, ['line', ...], \var{octets})}. + +The POP3 TOP command this method uses, unlike the RETR command, +doesn't set the message's seen flag; unfortunately, TOP is poorly +specified in the RFCs and is frequently broken in off-brand servers. +Test this method by hand against the POP3 servers you will use before +trusting it. \end{methoddesc} \begin{methoddesc}{uidl}{\optional{which}} @@ -109,6 +125,9 @@ otherwise result is list \code{(\var{response}, ['mesgnum uid', ...], \var{octets})}. \end{methoddesc} +\begin{seealso} + \seemodule{imap}{The standard Python IMAP module.} +\end{seealso} \subsection{POP3 Example \label{pop3-example}} |