Doc/lib/libpoplib.tex

%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{\module{poplib} ---
         POP3 protocol client.}
\declaremodule{standard}{poplib}

\modulesynopsis{POP3 protocol client (requires sockets).}

\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.