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