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