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