Doc/lib/libpoplib.tex

   1 \section{\module{poplib} ---
   2          POP3 protocol client}
   3
   4 \declaremodule{standard}{poplib}
   5 \modulesynopsis{POP3 protocol client (requires sockets).}
   6
   7 %By Andrew T. Csillag
   8 %Even though I put it into LaTeX, I cannot really claim that I wrote
   9 %it since I just stole most of it from the poplib.py source code and
  10 %the imaplib ``chapter''.
  11
  12 \indexii{POP3}{protocol}
  13
  14 This module defines a class, \class{POP3}, which encapsulates a
  15 connection to an POP3 server and implements protocol as defined in
  16 \rfc{1725}.  The \class{POP3} class supports both the minimal and
  17 optional command sets.
  18
  19 A single class is provided by the \module{poplib} module:
  20
  21 \begin{classdesc}{POP3}{host\optional{, port}}
  22 This class implements the actual POP3 protocol.  The connection is
  23 created when the instance is initialized.
  24 If \var{port} is omitted, the standard POP3 port (110) is used.
  25 \end{classdesc}
  26
  27 One exception is defined as an attribute of the \module{poplib} module:
  28
  29 \begin{excdesc}{error_proto}
  30 Exception raised on any errors.  The reason for the exception is
  31 passed to the constructor as a string.
  32 \end{excdesc}
  33
  34
  35 \subsection{POP3 Objects \label{pop3-objects}}
  36
  37 All POP3 commands are represented by methods of the same name,
  38 in lower-case; most return the response text sent by the server.
  39
  40 An \class{POP3} instance has the following methods:
  41
  42
  43 \begin{methoddesc}{getwelcome}{}
  44 Returns the greeting string sent by the POP3 server.
  45 \end{methoddesc}
  46
  47
  48 \begin{methoddesc}{user}{username}
  49 Send user command, response should indicate that a password is required.
  50 \end{methoddesc}
  51
  52 \begin{methoddesc}{pass_}{password}
  53 Send password, response includes message count and mailbox size.
  54 Note: the mailbox on the server is locked until \method{quit()} is
  55 called.
  56 \end{methoddesc}
  57
  58 \begin{methoddesc}{apop}{user, secret}
  59 Use the more secure APOP authentication to log into the POP3 server.
  60 \end{methoddesc}
  61
  62 \begin{methoddesc}{rpop}{user}
  63 Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
  64 \end{methoddesc}
  65
  66 \begin{methoddesc}{stat}{}
  67 Get mailbox status.  The result is a tuple of 2 integers:
  68 \code{(\var{message count}, \var{mailbox size})}.
  69 \end{methoddesc}
  70
  71 \begin{methoddesc}{list}{\optional{which}}
  72 Request message list, result is in the form
  73 \code{(\var{response}, ['mesg_num octets', ...])}.  If \var{which} is
  74 set, it is the message to list.
  75 \end{methoddesc}
  76
  77 \begin{methoddesc}{retr}{which}
  78 Retrieve whole message number \var{which}.  Result is in form
  79 \code{(\var{response}, ['line', ...], \var{octets})}.
  80 \end{methoddesc}
  81
  82 \begin{methoddesc}{dele}{which}
  83 Delete message number \var{which}.
  84 \end{methoddesc}
  85
  86 \begin{methoddesc}{rset}{}
  87 Remove any deletion marks for the mailbox.
  88 \end{methoddesc}
  89
  90 \begin{methoddesc}{noop}{}
  91 Do nothing.  Might be used as a keep-alive.
  92 \end{methoddesc}
  93
  94 \begin{methoddesc}{quit}{}
  95 Signoff:  commit changes, unlock mailbox, drop connection.
  96 \end{methoddesc}
  97
  98 \begin{methoddesc}{top}{which, howmuch}
  99 Retrieves the message header plus \var{howmuch} lines of the message
 100 after the header of message number \var{which}. Result is in form
 101 \code{(\var{response}, ['line', ...], \var{octets})}.
 102 \end{methoddesc}
 103
 104 \begin{methoddesc}{uidl}{\optional{which}}
 105 Return message digest (unique id) list.
 106 If \var{which} is specified, result contains the unique id for that
 107 message in the form \code{'\var{response}\ \var{mesgnum}\ \var{uid}},
 108 otherwise result is list \code{(\var{response}, ['mesgnum uid', ...],
 109 \var{octets})}.
 110 \end{methoddesc}
 111
 112
 113 \subsection{POP3 Example \label{pop3-example}}
 114
 115 Here is a minimal example (without error checking) that opens a
 116 mailbox and retrieves and prints all messages:
 117
 118 \begin{verbatim}
 119 import getpass, poplib
 120
 121 M = poplib.POP3('localhost')
 122 M.user(getpass.getuser())
 123 M.pass_(getpass.getpass())
 124 numMessages = len(M.list()[1])
 125 for i in range(numMessages):
 126     for j in M.retr(i+1)[1]:
 127         print j
 128 \end{verbatim}
 129
 130 At the end of the module, there is a test section that contains a more
 131 extensive example of usage.