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