Doc/lib/libpoplib.tex

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