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 

    12 This module defines a class, :class:`POP3`, which encapsulates a connection to a

    13 POP3 server and implements the protocol as defined in :rfc:`1725`.  The

    14 :class:`POP3` class supports both the minimal and optional command sets.

    15 Additionally, this module provides a class :class:`POP3_SSL`, which provides

    16 support for connecting to POP3 servers that use SSL as an underlying protocol

    17 layer.

    18 

    19 Note that POP3, though widely supported, is obsolescent.  The implementation

    20 quality of POP3 servers varies widely, and too many are quite poor. If your

    21 mailserver supports IMAP, you would be better off using the

    22 :class:`imaplib.IMAP4` class, as IMAP servers tend to be better implemented.

    23 

    24 A 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 

    48 One 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 

    71 POP3 Objects

    72 ------------

    73 

    74 All POP3 commands are represented by methods of the same name, in lower-case;

    75 most return the response text sent by the server.

    76 

    77 An :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 

   173 Instances of :class:`POP3_SSL` have no additional methods. The interface of this

   174 subclass is identical to its parent.

   175 

   176 

   177 .. _pop3-example:

   178 

   179 POP3 Example

   180 ------------

   181 

   182 Here is a minimal example (without error checking) that opens a mailbox and

   183 retrieves 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 

   195 At the end of the module, there is a test section that contains a more extensive

   196 example of usage.

   197