poplib — POP3 协议客户端 — Python 文档

来自菜鸟教程
Python/docs/3.8/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 参数指定连接尝试的超时时间(如果未指定,将使用全局默认超时设置)。
class poplib.POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)

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

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

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

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

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

一个例外被定义为 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_hostnameServer 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)

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