Added a section for the poplib module, contributed by Drew Csillag.

1 files changed, 131 insertions, 0 deletions

diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex
new file mode 100644
index 0000000..12882e9
--- /dev/null
+++ b/Doc/lib/libpoplib.tex
@@ -0,0 +1,131 @@
+%By Andrew T. Csillag
+%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''.
+
+\section{Standard Module \module{poplib}}
+\stmodindex{poplib}
+\label{module-poplib}
+\indexii{POP3}{protocol}
+
+This module defines a class, \class{POP3}, which encapsulates a
+connection to an POP3 server and implements protocol as defined in
+\rfc{1725}.  The \class{POP3} class supports both the minmal and
+optional command sets.
+
+A single class is provided by the \module{poplib} module:
+
+\begin{classdesc}{POP3}{host\optional{, port}}
+This class implements the actual POP3 protocol.  The connection is
+created when the instance is initialized.
+If \var{port} is omitted, the standard POP3 port (110) is used.
+\end{classdesc}
+
+One exception is defined as attributes of the \module{poplib} module:
+
+\begin{excdesc}{error_proto}
+Exception raised on any errors.  The reason for the exception is
+passed to the constructor as a string.
+\end{excdesc}
+
+
+\subsection{POP3 Objects}
+\label{pop3-objects}
+
+All POP3 commands are represented by methods of the same name,
+in lower-case.
+
+Most commands return the response text sent by the server.
+
+An \class{POP3} instance has the following methods:
+
+
+\begin{methoddesc}{getwelcome}{}
+Returns the greeting string sent by the POP3 server.
+\end{methoddesc}
+
+
+\begin{methoddesc}{user}{username}
+Send user commad, response should indicate that a password is required.
+\end{methoddesc}
+
+\begin{methoddesc}{pass_}{password}
+Send password, response includes message count and mailbox size.
+Note: the mailbox on the server is locked until \method{quit()} is
+called.
+\end{methoddesc}
+
+\begin{methoddesc}{apop}{user, secret}
+Use the more secure APOP authentication to log into the POP3 server.
+\end{methoddesc}
+
+\begin{methoddesc}{rpop}{user}
+Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
+\end{methoddesc}
+
+\begin{methoddesc}{stat}{}
+Get mailbox status.  The result is a tuple of 2 integers:
+\code{(\var{message count}, \var{mailbox size})}.
+\end{methoddesc}
+
+\begin{methoddesc}{list}{\optional{which}}
+Request message list, result is in the form
+\code{['response', ['mesg_num octets', ...]]}.  If \var{which} is
+set, it is the message to list.
+\end{methoddesc}
+
+\begin{methoddesc}{retr}{which}
+Retrieve whole message number \var{which}.  Result is in form 
+\code{['response', ['line', ...], octets]}.
+\end{methoddesc}
+
+\begin{methoddesc}{dele}{which}
+Delete message number \var{which}.
+\end{methoddesc}
+
+\begin{methoddesc}{rset}{}
+Remove any deletion marks for the mailbox.
+\end{methoddesc}
+
+\begin{methoddesc}{noop}{}
+Do nothing.  Might be used as a keep-alive.
+\end{methoddesc}
+
+\begin{methoddesc}{quit}{}
+Signoff:  commit changes, unlock mailbox, drop connection.
+\end{methoddesc}
+
+\begin{methoddesc}{top}{which, howmuch}
+Retrieves the message header plus \var{howmuch} lines of the message
+after the header of message number \var{which}. Result is in form 
+\code{['response', ['line', ...], octets]}.
+\end{methoddesc}
+
+\begin{methoddesc}{uidl}{\optional{which}}
+Return message digest (unique id) list.
+If \var{which} is specified, result contains unique id for that
+message, otherwise result is list \code{['response',
+['mesgnum uid', ...], octets]}.
+\end{methoddesc}
+
+
+\subsection{POP3 Example}
+\label{pop3-example}
+
+Here is a minimal example (without error checking) that opens a
+mailbox and retrieves and prints all messages:
+
+\begin{verbatim}
+import getpass, poplib, string
+
+M = poplib.POP3('localhost')
+M.user(getpass.getuser())
+M.pass(getpass.getpass())
+numMessages = len(M.list()[1])
+for i in range(numMessages):
+    for j in M.retr(i+1)[1]:
+        sys.stdout.write(j)
+\end{verbatim}
+
+At the end of the module, there is a test section that contains a more
+extensive example of usage.