1:mod:`poplib` --- POP3 protocol client 2====================================== 3 4.. module:: poplib 5 :synopsis: POP3 protocol client (requires sockets). 6.. sectionauthor:: Andrew T. Csillag 7.. revised by ESR, January 2000 8 9.. index:: pair: POP3; protocol 10 11**Source code:** :source:`Lib/poplib.py` 12 13-------------- 14 15This module defines a class, :class:`POP3`, which encapsulates a connection to a 16POP3 server and implements the protocol as defined in :rfc:`1725`. The 17:class:`POP3` class supports both the minimal and optional command sets. 18Additionally, this module provides a class :class:`POP3_SSL`, which provides 19support for connecting to POP3 servers that use SSL as an underlying protocol 20layer. 21 22Note that POP3, though widely supported, is obsolescent. The implementation 23quality of POP3 servers varies widely, and too many are quite poor. If your 24mailserver supports IMAP, you would be better off using the 25:class:`imaplib.IMAP4` class, as IMAP servers tend to be better implemented. 26 27The :mod:`poplib` module provides two classes: 28 29 30.. class:: POP3(host[, port[, timeout]]) 31 32 This class implements the actual POP3 protocol. The connection is created when 33 the instance is initialized. If *port* is omitted, the standard POP3 port (110) 34 is used. The optional *timeout* parameter specifies a timeout in seconds for the 35 connection attempt (if not specified, the global default timeout setting will 36 be used). 37 38 .. versionchanged:: 2.6 39 *timeout* was added. 40 41 42.. class:: POP3_SSL(host[, port[, keyfile[, certfile]]]) 43 44 This is a subclass of :class:`POP3` that connects to the server over an SSL 45 encrypted socket. If *port* is not specified, 995, the standard POP3-over-SSL 46 port is used. *keyfile* and *certfile* are also optional - they can contain a 47 PEM formatted private key and certificate chain file for the SSL connection. 48 49 .. versionadded:: 2.4 50 51One exception is defined as an attribute of the :mod:`poplib` module: 52 53 54.. exception:: error_proto 55 56 Exception raised on any errors from this module (errors from :mod:`socket` 57 module are not caught). The reason for the exception is passed to the 58 constructor as a string. 59 60 61.. seealso:: 62 63 Module :mod:`imaplib` 64 The standard Python IMAP module. 65 66 `Frequently Asked Questions About Fetchmail <http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html>`_ 67 The FAQ for the :program:`fetchmail` POP/IMAP client collects information on 68 POP3 server variations and RFC noncompliance that may be useful if you need to 69 write an application based on the POP protocol. 70 71 72.. _pop3-objects: 73 74POP3 Objects 75------------ 76 77All POP3 commands are represented by methods of the same name, in lower-case; 78most return the response text sent by the server. 79 80An :class:`POP3` instance has the following methods: 81 82 83.. method:: POP3.set_debuglevel(level) 84 85 Set the instance's debugging level. This controls the amount of debugging 86 output printed. The default, ``0``, produces no debugging output. A value of 87 ``1`` produces a moderate amount of debugging output, generally a single line 88 per request. A value of ``2`` or higher produces the maximum amount of 89 debugging output, logging each line sent and received on the control connection. 90 91 92.. method:: POP3.getwelcome() 93 94 Returns the greeting string sent by the POP3 server. 95 96 97.. method:: POP3.user(username) 98 99 Send user command, response should indicate that a password is required. 100 101 102.. method:: POP3.pass_(password) 103 104 Send password, response includes message count and mailbox size. Note: the 105 mailbox on the server is locked until :meth:`~poplib.quit` is called. 106 107 108.. method:: POP3.apop(user, secret) 109 110 Use the more secure APOP authentication to log into the POP3 server. 111 112 113.. method:: POP3.rpop(user) 114 115 Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server. 116 117 118.. method:: POP3.stat() 119 120 Get mailbox status. The result is a tuple of 2 integers: ``(message count, 121 mailbox size)``. 122 123 124.. method:: POP3.list([which]) 125 126 Request message list, result is in the form ``(response, ['mesg_num octets', 127 ...], octets)``. If *which* is set, it is the message to list. 128 129 130.. method:: POP3.retr(which) 131 132 Retrieve whole message number *which*, and set its seen flag. Result is in form 133 ``(response, ['line', ...], octets)``. 134 135 136.. method:: POP3.dele(which) 137 138 Flag message number *which* for deletion. On most servers deletions are not 139 actually performed until QUIT (the major exception is Eudora QPOP, which 140 deliberately violates the RFCs by doing pending deletes on any disconnect). 141 142 143.. method:: POP3.rset() 144 145 Remove any deletion marks for the mailbox. 146 147 148.. method:: POP3.noop() 149 150 Do nothing. Might be used as a keep-alive. 151 152 153.. method:: POP3.quit() 154 155 Signoff: commit changes, unlock mailbox, drop connection. 156 157 158.. method:: POP3.top(which, howmuch) 159 160 Retrieves the message header plus *howmuch* lines of the message after the 161 header of message number *which*. Result is in form ``(response, ['line', ...], 162 octets)``. 163 164 The POP3 TOP command this method uses, unlike the RETR command, doesn't set the 165 message's seen flag; unfortunately, TOP is poorly specified in the RFCs and is 166 frequently broken in off-brand servers. Test this method by hand against the 167 POP3 servers you will use before trusting it. 168 169 170.. method:: POP3.uidl([which]) 171 172 Return message digest (unique id) list. If *which* is specified, result contains 173 the unique id for that message in the form ``'response mesgnum uid``, otherwise 174 result is list ``(response, ['mesgnum uid', ...], octets)``. 175 176Instances of :class:`POP3_SSL` have no additional methods. The interface of this 177subclass is identical to its parent. 178 179 180.. _pop3-example: 181 182POP3 Example 183------------ 184 185Here is a minimal example (without error checking) that opens a mailbox and 186retrieves and prints all messages:: 187 188 import getpass, poplib 189 190 M = poplib.POP3('localhost') 191 M.user(getpass.getuser()) 192 M.pass_(getpass.getpass()) 193 numMessages = len(M.list()[1]) 194 for i in range(numMessages): 195 for j in M.retr(i+1)[1]: 196 print j 197 198At the end of the module, there is a test section that contains a more extensive 199example of usage. 200 201