← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.2-docs-html/_sources/library/poplib.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

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