Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{poplib} --- |
Fred Drake | e2effbd | 1999-04-22 16:21:09 +0000 | [diff] [blame] | 2 | POP3 protocol client} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | e2effbd | 1999-04-22 16:21:09 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{poplib} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{POP3 protocol client (requires sockets).} |
| 6 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 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''. |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 11 | %Revised by ESR, January 2000 |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 12 | |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 13 | \indexii{POP3}{protocol} |
| 14 | |
| 15 | This module defines a class, \class{POP3}, which encapsulates a |
| 16 | connection to an POP3 server and implements protocol as defined in |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 17 | \rfc{1725}. The \class{POP3} class supports both the minimal and |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 18 | optional command sets. |
| 19 | |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 20 | Note that POP3, though widely supported, is obsolescent. The |
| 21 | implementation quality of POP3 servers varies widely, and too many are |
| 22 | quite poor. If your mailserver supports IMAP, you would be better off |
| 23 | using the \refmodule{IMAP} class, as IMAP servers tend to be better |
| 24 | implemented. |
| 25 | |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 26 | A single class is provided by the \module{poplib} module: |
| 27 | |
| 28 | \begin{classdesc}{POP3}{host\optional{, port}} |
| 29 | This class implements the actual POP3 protocol. The connection is |
| 30 | created when the instance is initialized. |
| 31 | If \var{port} is omitted, the standard POP3 port (110) is used. |
| 32 | \end{classdesc} |
| 33 | |
Fred Drake | e2effbd | 1999-04-22 16:21:09 +0000 | [diff] [blame] | 34 | One exception is defined as an attribute of the \module{poplib} module: |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 35 | |
| 36 | \begin{excdesc}{error_proto} |
| 37 | Exception raised on any errors. The reason for the exception is |
| 38 | passed to the constructor as a string. |
| 39 | \end{excdesc} |
| 40 | |
| 41 | |
Fred Drake | e2effbd | 1999-04-22 16:21:09 +0000 | [diff] [blame] | 42 | \subsection{POP3 Objects \label{pop3-objects}} |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 43 | |
| 44 | All POP3 commands are represented by methods of the same name, |
Fred Drake | e2effbd | 1999-04-22 16:21:09 +0000 | [diff] [blame] | 45 | in lower-case; most return the response text sent by the server. |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 46 | |
| 47 | An \class{POP3} instance has the following methods: |
| 48 | |
| 49 | |
| 50 | \begin{methoddesc}{getwelcome}{} |
| 51 | Returns the greeting string sent by the POP3 server. |
| 52 | \end{methoddesc} |
| 53 | |
| 54 | |
| 55 | \begin{methoddesc}{user}{username} |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 56 | Send user command, response should indicate that a password is required. |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 57 | \end{methoddesc} |
| 58 | |
| 59 | \begin{methoddesc}{pass_}{password} |
| 60 | Send password, response includes message count and mailbox size. |
| 61 | Note: the mailbox on the server is locked until \method{quit()} is |
| 62 | called. |
| 63 | \end{methoddesc} |
| 64 | |
| 65 | \begin{methoddesc}{apop}{user, secret} |
| 66 | Use the more secure APOP authentication to log into the POP3 server. |
| 67 | \end{methoddesc} |
| 68 | |
| 69 | \begin{methoddesc}{rpop}{user} |
| 70 | Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server. |
| 71 | \end{methoddesc} |
| 72 | |
| 73 | \begin{methoddesc}{stat}{} |
| 74 | Get mailbox status. The result is a tuple of 2 integers: |
| 75 | \code{(\var{message count}, \var{mailbox size})}. |
| 76 | \end{methoddesc} |
| 77 | |
| 78 | \begin{methoddesc}{list}{\optional{which}} |
| 79 | Request message list, result is in the form |
Fred Drake | 3a4ceb7 | 1999-07-07 14:04:38 +0000 | [diff] [blame] | 80 | \code{(\var{response}, ['mesg_num octets', ...])}. If \var{which} is |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 81 | set, it is the message to list. |
| 82 | \end{methoddesc} |
| 83 | |
| 84 | \begin{methoddesc}{retr}{which} |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 85 | Retrieve whole message number \var{which}, and set its seen flag. |
| 86 | Result is in form \code{(\var{response}, ['line', ...], \var{octets})}. |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 87 | \end{methoddesc} |
| 88 | |
| 89 | \begin{methoddesc}{dele}{which} |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 90 | Flag message number \var{which} for deletion. On most servers |
| 91 | deletions are not actually performed until QUIT (the major exception is |
| 92 | Eudora QPOP, which deliberately violates the RFCs by doing pending |
| 93 | deletes on any disconnect). |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 94 | \end{methoddesc} |
| 95 | |
| 96 | \begin{methoddesc}{rset}{} |
| 97 | Remove any deletion marks for the mailbox. |
| 98 | \end{methoddesc} |
| 99 | |
| 100 | \begin{methoddesc}{noop}{} |
| 101 | Do nothing. Might be used as a keep-alive. |
| 102 | \end{methoddesc} |
| 103 | |
| 104 | \begin{methoddesc}{quit}{} |
| 105 | Signoff: commit changes, unlock mailbox, drop connection. |
| 106 | \end{methoddesc} |
| 107 | |
| 108 | \begin{methoddesc}{top}{which, howmuch} |
| 109 | Retrieves the message header plus \var{howmuch} lines of the message |
| 110 | after the header of message number \var{which}. Result is in form |
Fred Drake | 3a4ceb7 | 1999-07-07 14:04:38 +0000 | [diff] [blame] | 111 | \code{(\var{response}, ['line', ...], \var{octets})}. |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 112 | |
| 113 | The POP3 TOP command this method uses, unlike the RETR command, |
| 114 | doesn't set the message's seen flag; unfortunately, TOP is poorly |
| 115 | specified in the RFCs and is frequently broken in off-brand servers. |
| 116 | Test this method by hand against the POP3 servers you will use before |
| 117 | trusting it. |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 118 | \end{methoddesc} |
| 119 | |
| 120 | \begin{methoddesc}{uidl}{\optional{which}} |
| 121 | Return message digest (unique id) list. |
Fred Drake | dbc2d08 | 1999-05-13 18:48:14 +0000 | [diff] [blame] | 122 | If \var{which} is specified, result contains the unique id for that |
| 123 | message in the form \code{'\var{response}\ \var{mesgnum}\ \var{uid}}, |
Fred Drake | 3a4ceb7 | 1999-07-07 14:04:38 +0000 | [diff] [blame] | 124 | otherwise result is list \code{(\var{response}, ['mesgnum uid', ...], |
| 125 | \var{octets})}. |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 126 | \end{methoddesc} |
| 127 | |
Eric S. Raymond | 5ac9795 | 2001-01-11 04:19:52 +0000 | [diff] [blame] | 128 | \begin{seealso} |
| 129 | \seemodule{imap}{The standard Python IMAP module.} |
| 130 | \end{seealso} |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 131 | |
Fred Drake | e2effbd | 1999-04-22 16:21:09 +0000 | [diff] [blame] | 132 | \subsection{POP3 Example \label{pop3-example}} |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 133 | |
| 134 | Here is a minimal example (without error checking) that opens a |
| 135 | mailbox and retrieves and prints all messages: |
| 136 | |
| 137 | \begin{verbatim} |
Guido van Rossum | aac399b | 1998-12-08 16:30:10 +0000 | [diff] [blame] | 138 | import getpass, poplib |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 139 | |
| 140 | M = poplib.POP3('localhost') |
| 141 | M.user(getpass.getuser()) |
Guido van Rossum | aac399b | 1998-12-08 16:30:10 +0000 | [diff] [blame] | 142 | M.pass_(getpass.getpass()) |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 143 | numMessages = len(M.list()[1]) |
| 144 | for i in range(numMessages): |
| 145 | for j in M.retr(i+1)[1]: |
Guido van Rossum | aac399b | 1998-12-08 16:30:10 +0000 | [diff] [blame] | 146 | print j |
Fred Drake | a468404 | 1998-04-24 20:49:02 +0000 | [diff] [blame] | 147 | \end{verbatim} |
| 148 | |
| 149 | At the end of the module, there is a test section that contains a more |
| 150 | extensive example of usage. |