Debian Codegraph @

Doc/library/poplib.rst

raw
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 .. include:: ../includes/wasm-notavail.rst
32
33 The :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
89 One 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
112 POP3 Objects
113 ------------
114
115 All POP3 commands are represented by methods of the same name, in lowercase;
116 most return the response text sent by the server.
117
118 A :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
248 Instances of :class:`POP3_SSL` have no additional methods. The interface of this
249 subclass is identical to its parent.
250
251
252 .. _pop3-example:
253
254 POP3 Example
255 ------------
256
257 Here is a minimal example (without error checking) that opens a mailbox and
258 retrieves 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
270 At the end of the module, there is a test section that contains a more extensive
271 example of usage.