Python/docs/3.9/library/poplib

poplib — POP3 协议客户端

源代码： :source:`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 协议。 连接是在实例初始化时创建的。 如果省略 port，则使用标准 POP3 端口 (110)。 可选的 timeout 参数指定连接尝试的超时时间（如果未指定，将使用全局默认超时设置）。

在 3.9 版更改： 如果 timeout 参数设置为零，则会引发 ValueError 以防止创建非阻塞套接字。

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

这是 POP3 的子类，它通过 SSL 加密套接字连接到服务器。 如果未指定 port，则为 995，则使用标准的 POP3-over-SSL 端口。 timeout 在 POP3 构造函数中工作。 context 是一个可选的 ssl.SSLContext 对象，它允许将 SSL 配置选项、证书和私钥捆绑到一个（可能是长期存在的）结构中。 请阅读 安全注意事项 以获得最佳实践。

keyfile 和 certfile 是 context 的传统替代方案 - 它们可以分别指向 PEM 格式的私钥和证书链文件，用于 SSL 连接。

在 3.2 版更改：添加了 context 参数。

3.4 版更改： 该类现在支持使用 ssl.SSLContext.check_hostname 和 服务器名称指示 进行主机名检查（请参阅 ssl.HAS_SNI ）。

自 3.6 版起已弃用：keyfile 和 certfile 已弃用，取而代之的是 context。 请改用 ssl.SSLContext.load_cert_chain()，或让 ssl.create_default_context() 为您选择系统的可信 CA 证书。

在 3.9 版更改： 如果 timeout 参数设置为零，则会引发 ValueError 以防止创建非阻塞套接字。

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

exception poplib.error_proto

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

也可以看看

模块 imaplib

标准 Python IMAP 模块。

关于 Fetchmail 的常见问题

fetchmail POP/IMAP 客户端的 FAQ 收集了有关 POP3 服务器变体和 RFC 不合规性的信息，如果您需要编写基于 POP 协议的应用程序，这些信息可能会很有用。

POP3 对象

所有 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-commands）登录到 POP3 服务器。

POP3.stat()

获取邮箱状态。 结果是 2 个整数的元组：(message count, mailbox size)。

POP3.list([which])

请求消息列表，结果格式为(response, ['mesg_num octets', ...], octets)。 如果设置了which，就是要列出的消息。

POP3.retr(which)

检索整个消息号 which，并设置其已见标志。 结果采用 (response, ['line', ...], octets) 形式。

POP3.dele(which)

标记消息号 which 用于删除。 在大多数服务器上，直到 QUIT 才会真正执行删除（主要的例外是 Eudora QPOP，它通过在任何断开连接时执行挂起删除来故意违反 RFC）。

POP3.rset()

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

POP3.noop()

没做什么。 可以用作保活。

POP3.quit()

签收：提交更改、解锁邮箱、断开连接。

POP3.top(which, howmuch)

在消息号 which 的头之后检索消息头加上消息的 howmuch 行。 结果采用 (response, ['line', ...], octets) 形式。

此方法使用的 POP3 TOP 命令与 RETR 命令不同，它不设置邮件的已查看标志； 不幸的是，TOP 在 RFC 中没有详细说明，并且经常在非品牌服务器中被破坏。 在信任此方法之前，请针对您将使用的 POP3 服务器手动测试此方法。

POP3.uidl(which=None)

返回消息摘要（唯一 ID）列表。 如果指定了 which，则结果以 'response mesgnum uid 的形式包含该消息的唯一 ID，否则结果是列表 (response, ['mesgnum uid', ...], octets)。

POP3.utf8()

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

3.5 版中的新功能。

POP3.stls(context=None)

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

context 参数是一个 ssl.SSLContext 对象，它允许将 SSL 配置选项、证书和私钥捆绑到一个（可能是长期存在的）结构中。 请阅读 安全注意事项 以获得最佳实践。

此方法支持通过 ssl.SSLContext.check_hostname 和 Server Name Indication 进行主机名检查（请参阅 ssl.HAS_SNI）。

3.4 版中的新功能。

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

POP3 示例

这是一个最小的例子（没有错误检查），它打开一个邮箱并检索和打印所有消息：

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)

Copy

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