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