# 21.14. `poplib` - POP3协议客户端

源代码： Lib / poplib.py

此模块定义了一个类`POP3`，它封装了到POP3服务器的连接，并实现了 RFC 1939中定义的协议。`POP3`类支持 RFC 1939的最小和可选命令集。`POP3`类还支持在 RFC 2595中引入的`STLS`命令，以在已建立的连接上启用加密通信。

此外，此模块还提供了一个类`POP3_SSL`，它支持连接到使用SSL作为基础协议层的POP3服务器。

请注意，虽然广泛支持，POP3是过时的。POP3服务器的实现质量差异很大，太多的都相当差。如果您的邮件服务器支持IMAP，则最好使用`imaplib.IMAP4`类，因为IMAP服务器往往会更好地实现。

`poplib`模块提供了两个类：

class `poplib.``POP3`(host, port=POP3_PORT[, timeout])

  这个类实现了实际的POP3协议。当实例初始化时创建连接。如果省略端口，则使用标准POP3端口（110）。可选的timeout参数指定连接尝试的超时（以秒为单位）（如果未指定，将使用全局默认超时设置）。

class `poplib.``POP3_SSL`(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)

  这是`POP3`的子类，通过SSL加密的套接字连接到服务器。如果未指定端口，则使用标准的POP3 over SSL端口。超时的工作方式与`POP3`构造函数中的相同。上下文是可选的`ssl.SSLContext`对象，允许将SSL配置选项，证书和私钥捆绑到单个（可能长期）结构中。有关最佳做法，请参阅Security considerations。

  键文件和certfile是上下文的传统替代方式 - 它们可以分别指向SSL的PEM格式的私钥和证书链文件连接。

  在版本3.2中更改： 上下文参数添加。

  在版本3.4中更改：此类现在支持使用`ssl.SSLContext.check_hostname`和服务器名称指示（请参阅`ssl.HAS_SNI`）。

一个例外被定义为`poplib`模块的属性：

exception `poplib.``error_proto`

  对此模块的任何错误引发的异常（未捕获来自`socket`模块的错误）。异常的原因作为字符串传递给构造函数。

也可以看看

模块`imaplib`
  标准的Python IMAP模块。
关于Fetchmail的常见问题
  fetchmail POP / IMAP客户端的常见问题解答收集有关POP3服务器变体和RFC不符合的信息，如果您需要基于POP协议编写应用程序，这些信息可能很有用。

## 21.14.1. POP3 Objects

所有POP3命令由相同名称的方法表示，小写；最多返回服务器发送的响应文本。

`POP3`实例具有以下方法：

`POP3.``set_debuglevel`(level)

  设置实例的调试级别。这控制打印的调试输出量。默认值`0`不产生调试输出。值`1`产生适量的调试输出，通常每个请求都有一行。值`2`或更高会产生最大调试输出量，记录在控制连接上发送和接收的每行。

`POP3.``getwelcome`()

  返回由POP3服务器发送的问候字符串。

`POP3.``capa`()

  查询 RFC 2449中指定的服务器功能。以`{'name'： ['param'...]}`的形式返回字典。

  版本3.4中的新功能。

`POP3.``user`(username)

  发送用户命令，响应应该指示需要密码。

`POP3.``pass_`(password)

  发送密码，响应包括邮件数量和邮箱大小。注意：服务器上的邮箱被锁定，直到调用`quit()`。

`POP3.``apop`(user, secret)

  使用更安全的APOP身份验证登录POP3服务器。

`POP3.``rpop`(user)

  使用RPOP认证（类似于UNIX r命令）登录到POP3服务器。

`POP3.``stat`()

  获取邮箱状态。结果是2个整数的元组：`（message count， mailbox size） t0 >。`

`POP3.``list`([which])

  请求消息列表，结果为`（响应， ['mesg_num octets'， ...] octets）`。如果其中设置，它是要列出的消息。

`POP3.``retr`(which)

  检索整个消息号其中，并设置其看到的标志。结果为`（响应， ['line'， ...]， 八位字节）` 。

`POP3.``dele`(which)

  标志消息号其中用于删除。在大多数服务器上，删除实际上不执行，直到QUIT（主要例外是Eudora QPOP，故意违反RFC通过在任何断开连接进行挂起删除）。

`POP3.``rset`()

  删除邮箱的所有删除标记。

`POP3.``noop`()

  没做什么。可能用作保持活动。

`POP3.``quit`()

  注销：提交更改，解锁邮箱，删除连接。

`POP3.``top`(which, howmuch)

  检索邮件标头>之后的邮件标头和howmuch行。结果为`（响应， ['line'， ...]， 八位字节）` 。

  与RETR命令不同，此方法使用的POP3 TOP命令不设置消息的见过标志；不幸的是，TOP在RFC中指定不好，并且经常在非品牌服务器上断开。手动测试此方法对您将使用的POP3服务器在信任它之前。

`POP3.``uidl`(which=None)

  返回消息摘要（唯一ID）列表。If which is specified, result contains the unique id for that message in the form `'response mesgnum uid`, otherwise result is list `(response, ['mesgnum uid', ...], octets)`.

`POP3.``utf8`()

  尝试切换到UTF-8模式。如果成功，返回服务器响应，如果不成功，则引发`error_proto`。在 RFC 6856中指定。

  版本3.5中的新功能。

`POP3.``stls`(context=None)

  按照 RFC 2595中指定的在活动连接上启动TLS会话。这只有在用户身份验证之前才允许

  上下文参数是一个`ssl.SSLContext`对象，它允许将SSL配置选项，证书和私钥捆绑到单个（可能长期）结构中。有关最佳做法，请参阅Security considerations。

  此方法支持通过`ssl.SSLContext.check_hostname`和服务器名称指示（请参阅`ssl.HAS_SNI`）进行主机名检查。

  版本3.4中的新功能。

`POP3_SSL`的实例没有其他方法。此子类的接口与其父类相同。

## 21.14.2. POP3 Example

下面是一个打开邮箱并检索和打印所有邮件的最小示例（无错误检查）：

    import getpass, poplib

    M = poplib.POP3('localhost')
    M.user(getpass.getuser())
    M.pass_(getpass.getpass())
    numMessages = len(M.list()[1])
    for i in range(numMessages):
        for j in M.retr(i+1)[1]:
            print(j)

在模块的结尾，有一个测试部分，其中包含更广泛的使用示例。