PageRenderTime 709ms CodeModel.GetById 232ms app.highlight 137ms RepoModel.GetById 246ms app.codeStats 0ms

/Doc/library/poplib.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 197 lines | 115 code | 82 blank | 0 comment | 0 complexity | ef8d1836e77759e7d51c6e04e4a509f8 MD5 | raw file
  1
  2:mod:`poplib` --- POP3 protocol client
  3======================================
  4
  5.. module:: poplib
  6   :synopsis: POP3 protocol client (requires sockets).
  7.. sectionauthor:: Andrew T. Csillag
  8.. revised by ESR, January 2000
  9
 10.. index:: pair: POP3; protocol
 11
 12This module defines a class, :class:`POP3`, which encapsulates a connection to a
 13POP3 server and implements the protocol as defined in :rfc:`1725`.  The
 14:class:`POP3` class supports both the minimal and optional command sets.
 15Additionally, this module provides a class :class:`POP3_SSL`, which provides
 16support for connecting to POP3 servers that use SSL as an underlying protocol
 17layer.
 18
 19Note that POP3, though widely supported, is obsolescent.  The implementation
 20quality of POP3 servers varies widely, and too many are quite poor. If your
 21mailserver supports IMAP, you would be better off using the
 22:class:`imaplib.IMAP4` class, as IMAP servers tend to be better implemented.
 23
 24A single class is provided by the :mod:`poplib` module:
 25
 26
 27.. class:: POP3(host[, port[, timeout]])
 28
 29   This class implements the actual POP3 protocol.  The connection is created when
 30   the instance is initialized. If *port* is omitted, the standard POP3 port (110)
 31   is used. The optional *timeout* parameter specifies a timeout in seconds for the
 32   connection attempt (if not specified, the global default timeout setting will
 33   be used).
 34
 35   .. versionchanged:: 2.6
 36      *timeout* was added.
 37
 38
 39.. class:: POP3_SSL(host[, port[, keyfile[, certfile]]])
 40
 41   This is a subclass of :class:`POP3` that connects to the server over an SSL
 42   encrypted socket.  If *port* is not specified, 995, the standard POP3-over-SSL
 43   port is used.  *keyfile* and *certfile* are also optional - they can contain a
 44   PEM formatted private key and certificate chain file for the SSL connection.
 45
 46   .. versionadded:: 2.4
 47
 48One exception is defined as an attribute of the :mod:`poplib` module:
 49
 50
 51.. exception:: error_proto
 52
 53   Exception raised on any errors from this module (errors from :mod:`socket`
 54   module are not caught). The reason for the exception is passed to the
 55   constructor as a string.
 56
 57
 58.. seealso::
 59
 60   Module :mod:`imaplib`
 61      The standard Python IMAP module.
 62
 63   `Frequently Asked Questions About Fetchmail <http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html>`_
 64      The FAQ for the :program:`fetchmail` POP/IMAP client collects information on
 65      POP3 server variations and RFC noncompliance that may be useful if you need to
 66      write an application based on the POP protocol.
 67
 68
 69.. _pop3-objects:
 70
 71POP3 Objects
 72------------
 73
 74All POP3 commands are represented by methods of the same name, in lower-case;
 75most return the response text sent by the server.
 76
 77An :class:`POP3` instance has the following methods:
 78
 79
 80.. method:: POP3.set_debuglevel(level)
 81
 82   Set the instance's debugging level.  This controls the amount of debugging
 83   output printed.  The default, ``0``, produces no debugging output.  A value of
 84   ``1`` produces a moderate amount of debugging output, generally a single line
 85   per request.  A value of ``2`` or higher produces the maximum amount of
 86   debugging output, logging each line sent and received on the control connection.
 87
 88
 89.. method:: POP3.getwelcome()
 90
 91   Returns the greeting string sent by the POP3 server.
 92
 93
 94.. method:: POP3.user(username)
 95
 96   Send user command, response should indicate that a password is required.
 97
 98
 99.. method:: POP3.pass_(password)
100
101   Send password, response includes message count and mailbox size. Note: the
102   mailbox on the server is locked until :meth:`quit` is called.
103
104
105.. method:: POP3.apop(user, secret)
106
107   Use the more secure APOP authentication to log into the POP3 server.
108
109
110.. method:: POP3.rpop(user)
111
112   Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
113
114
115.. method:: POP3.stat()
116
117   Get mailbox status.  The result is a tuple of 2 integers: ``(message count,
118   mailbox size)``.
119
120
121.. method:: POP3.list([which])
122
123   Request message list, result is in the form ``(response, ['mesg_num octets',
124   ...], octets)``. If *which* is set, it is the message to list.
125
126
127.. method:: POP3.retr(which)
128
129   Retrieve whole message number *which*, and set its seen flag. Result is in form
130   ``(response, ['line', ...], octets)``.
131
132
133.. method:: POP3.dele(which)
134
135   Flag message number *which* for deletion.  On most servers deletions are not
136   actually performed until QUIT (the major exception is Eudora QPOP, which
137   deliberately violates the RFCs by doing pending deletes on any disconnect).
138
139
140.. method:: POP3.rset()
141
142   Remove any deletion marks for the mailbox.
143
144
145.. method:: POP3.noop()
146
147   Do nothing.  Might be used as a keep-alive.
148
149
150.. method:: POP3.quit()
151
152   Signoff:  commit changes, unlock mailbox, drop connection.
153
154
155.. method:: POP3.top(which, howmuch)
156
157   Retrieves the message header plus *howmuch* lines of the message after the
158   header of message number *which*. Result is in form ``(response, ['line', ...],
159   octets)``.
160
161   The POP3 TOP command this method uses, unlike the RETR command, doesn't set the
162   message's seen flag; unfortunately, TOP is poorly specified in the RFCs and is
163   frequently broken in off-brand servers. Test this method by hand against the
164   POP3 servers you will use before trusting it.
165
166
167.. method:: POP3.uidl([which])
168
169   Return message digest (unique id) list. If *which* is specified, result contains
170   the unique id for that message in the form ``'response mesgnum uid``, otherwise
171   result is list ``(response, ['mesgnum uid', ...], octets)``.
172
173Instances of :class:`POP3_SSL` have no additional methods. The interface of this
174subclass is identical to its parent.
175
176
177.. _pop3-example:
178
179POP3 Example
180------------
181
182Here is a minimal example (without error checking) that opens a mailbox and
183retrieves and prints all messages::
184
185   import getpass, poplib
186
187   M = poplib.POP3('localhost')
188   M.user(getpass.getuser())
189   M.pass_(getpass.getpass())
190   numMessages = len(M.list()[1])
191   for i in range(numMessages):
192       for j in M.retr(i+1)[1]:
193           print j
194
195At the end of the module, there is a test section that contains a more extensive
196example of usage.
197