| \section{\module{poplib} --- |
| POP3 protocol client} |
| |
| \declaremodule{standard}{poplib} |
| \modulesynopsis{POP3 protocol client (requires sockets).} |
| |
| %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''. |
| |
| \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 minimal 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 an attribute 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 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 command, 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{(\var{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{(\var{response}, ['line', ...], \var{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{(\var{response}, ['line', ...], \var{octets})}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{uidl}{\optional{which}} |
| Return message digest (unique id) list. |
| If \var{which} is specified, result contains the unique id for that |
| message in the form \code{'\var{response}\ \var{mesgnum}\ \var{uid}}, |
| otherwise result is list \code{(\var{response}, ['mesgnum uid', ...], |
| \var{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 |
| |
| 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]: |
| print j |
| \end{verbatim} |
| |
| At the end of the module, there is a test section that contains a more |
| extensive example of usage. |