20.10. 映射库 — IMAP4 协议客户端

源代码： :source:`Lib/imaplib.py`

该模块定义了三个类，IMAP4、IMAP4_SSL 和 IMAP4_stream，它们封装了到 IMAP4 服务器的连接并实现了 IMAP4rev1 客户端协议的一个很大的子集。在 RFC 2060 中。它向后兼容 IMAP4 (RFC 1730) 服务器，但请注意 IMAP4 不支持 STATUS 命令。

imaplib模块提供了三个类，IMAP4是基类：

class imaplib.IMAP4([host[, port]]): 这个类实现了实际的 IMAP4 协议。在实例初始化时创建连接并确定协议版本（IMAP4 或 IMAP4rev1）。如果未指定 host，则使用 （本地主机）。如果省略 port，则使用标准 IMAP4 端口 (143)。

三个例外被定义为 IMAP4 类的属性：

exception IMAP4.error: 出现任何错误的异常。异常的原因作为字符串传递给构造函数。

exception IMAP4.abort: IMAP4 服务器错误导致引发此异常。这是 IMAP4.error 的子类。请注意，关闭实例并实例化一个新实例通常会允许从此异常中恢复。

exception IMAP4.readonly: 当服务器更改可写邮箱的状态时，会引发此异常。这是 IMAP4.error 的子类。其他一些客户端现在有写权限，需要重新打开邮箱才能重新获得写权限。

还有一个用于安全连接的子类：

class imaplib.IMAP4_SSL([host[, port[, keyfile[, certfile]]]]): 这是从 IMAP4 派生的子类，它通过 SSL 加密套接字进行连接（要使用此类，您需要使用 SSL 支持编译的套接字模块）。如果未指定 host，则使用 （本地主机）。如果省略 port，则使用标准的 IMAP4-over-SSL 端口 (993)。 keyfile 和 certfile 也是可选的 - 它们可以包含用于 SSL 连接的 PEM 格式的私钥和证书链文件。

第二个子类允许由子进程创建的连接：

class imaplib.IMAP4_stream(command): 这是从 IMAP4 派生的子类，它连接到通过将 command 传递给 os.popen2() 创建的 stdin/stdout 文件描述符。

2.3 版中的新功能。

定义了以下实用函数：

imaplib.Internaldate2tuple(datestr): 解析一个 IMAP4 INTERNALDATE 字符串并返回对应的本地时间。如果字符串格式错误，则返回值是 time.struct_time 实例或 None。

imaplib.Int2AP(num): 使用集合 [A .. 中的字符将整数转换为字符串表示形式。 P]。

imaplib.ParseFlags(flagstr): 将 IMAP4 FLAGS 响应转换为单个标志的元组。

imaplib.Time2Internaldate(date_time): 将 date_time 转换为 IMAP4 INTERNALDATE 表示。返回值是一个字符串，格式为："DD-Mmm-YYYY HH:MM:SS +HHMM"（包括双引号）。 date_time 参数可以是一个数字（int 或 float），表示自纪元以来的秒数（由 time.time() 返回），一个 9 元组，表示本地时间（由time.localtime()) 或双引号字符串。在最后一种情况下，假定已经采用正确的格式。

请注意，IMAP4 消息编号会随着邮箱的变化而变化；特别是，在 EXPUNGE 命令执行删除后，剩余的消息将重新编号。因此，强烈建议使用 UID 代替 UID 命令。

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

也可以看看

描述该协议的文档，以及实现它的服务器的源代码和二进制文件，都可以在华盛顿大学的 IMAP 信息中心 (https://www.washington.edu/imap/ ]）。

20.10.1。 IMAP4 对象

所有 IMAP4rev1 命令都由大写或小写的同名方法表示。

命令的所有参数都转换为字符串，除了 AUTHENTICATE 和作为 IMAP4 文字传递的 APPEND 的最后一个参数。如有必要（该字符串包含 IMAP4 协议敏感字符且未用括号或双引号括起来）每个字符串都被引用。但是，始终引用 LOGIN 命令的 password 参数。如果您想避免引用参数字符串（例如：STORE 的 flags 参数），则将该字符串括在括号中（例如：r'(\Deleted)'）。

每个命令返回一个元组： (type, [data, ...]) 其中 type 通常是 'OK' 或 'NO'，而 data 是来自命令响应，或命令的强制结果。每个 data 要么是一个字符串，要么是一个元组。如果是元组，则第一部分是响应的标头，第二部分包含数据（即：“文字”值）。

下面命令的 message_set 选项是一个字符串，指定要对其执行的一个或多个消息。它可能是一个简单的消息号 ('1')、一个消息号范围 ('2:4') 或一组由逗号分隔的非连续范围 ('1:3,6:9')。一个范围可以包含一个星号来表示一个无限的上限 ('3:*')。

IMAP4 实例具有以下方法：

IMAP4.append(mailbox, flags, date_time, message): 将 message 附加到命名邮箱。

IMAP4.authenticate(mechanism, authobject)

验证命令 - 需要响应处理。

mechanism 指定要使用的身份验证机制 - 它应该以 AUTH=mechanism 的形式出现在实例变量 capabilities 中。

authobject 必须是可调用对象：

data = authobject(response)

它将被调用以处理服务器继续响应。它应该返回将被编码并发送到服务器的 data。如果应该发送客户端中止响应 *，它应该返回 None。

IMAP4.check(): 服务器上的检查点邮箱。

IMAP4.close(): 关闭当前选择的邮箱。已删除的邮件将从可写邮箱中删除。这是LOGOUT之前的推荐命令。

IMAP4.copy(message_set, new_mailbox): 将 message_set 消息复制到 new_mailbox 的末尾。

IMAP4.create(mailbox): 创建名为 mailbox 的新邮箱。

IMAP4.delete(mailbox): 删除名为 mailbox 的旧邮箱。

IMAP4.deleteacl(mailbox, who): 删除为邮箱上的 who 设置的 ACL（删除任何权限）。

2.4 版中的新功能。

IMAP4.expunge(): 从选定的邮箱中永久删除已删除的项目。为每个已删除的消息生成 EXPUNGE 响应。返回的数据包含按接收顺序排列的 EXPUNGE 消息编号列表。

IMAP4.fetch(message_set, message_parts): 获取（部分）消息。 message_parts 应该是括号内的消息部分名称字符串，例如："(UID BODY[TEXT])"。返回的数据是消息部分信封和数据的元组。

IMAP4.getacl(mailbox): 获取邮箱的 ACL。该方法是非标准的，但受 Cyrus 服务器支持。

IMAP4.getannotation(mailbox, entry, attribute): 为 mailbox 检索指定的 ANNOTATION。该方法是非标准的，但受 Cyrus 服务器支持。

2.5 版中的新功能。

IMAP4.getquota(root): 获取 quota root 的资源使用和限制。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。

2.3 版中的新功能。

IMAP4.getquotaroot(mailbox): 获取命名为邮箱的 quota roots 列表。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。

2.3 版中的新功能。

IMAP4.list([directory[, pattern]]): 列出目录中匹配模式的邮箱名称。 directory 默认为顶级邮件文件夹，pattern 默认匹配任何内容。返回的数据包含 LIST 响应列表。

IMAP4.login(user, password): 使用明文密码识别客户端。 password 将被引用。

IMAP4.login_cram_md5(user, password): 识别客户端时强制使用 CRAM-MD5 身份验证以保护密码。仅当服务器 CAPABILITY 响应包含短语 AUTH=CRAM-MD5 时才有效。

2.3 版中的新功能。

IMAP4.logout(): 关闭与服务器的连接。返回服务器 BYE 响应。

IMAP4.lsub([directory[, pattern]]): 以目录匹配模式列出订阅的邮箱名称。 directory 默认为顶级目录，pattern 默认匹配任何邮箱。返回的数据是消息部分信封和数据的元组。

IMAP4.myrights(mailbox): 显示我的邮箱 ACL（即我对邮箱拥有的权利）。

2.4 版中的新功能。

IMAP4.namespace(): 返回 RFC2342 中定义的 IMAP 命名空间。

2.3 版中的新功能。

IMAP4.noop(): 将 NOOP 发送到服务器。

IMAP4.open(host, port): 在主机打开到端口的套接字。此方法由 IMAP4 构造函数隐式调用。该方法建立的连接对象将在IMAP4.read()、IMAP4.readline()、IMAP4.send()、中使用147]IMAP4.shutdown() 方法。您可以覆盖此方法。

IMAP4.partial(message_num, message_part, start, length): 获取消息的截断部分。返回的数据是消息部分信封和数据的元组。

IMAP4.proxyauth(user): 假设身份验证为用户。允许授权管理员代理进入任何用户的邮箱。

2.3 版中的新功能。

IMAP4.read(size): 从远程服务器读取 size 个字节。您可以覆盖此方法。

IMAP4.readline(): 从远程服务器读取一行。您可以覆盖此方法。

IMAP4.recent(): 提示服务器更新。如果没有新消息，返回的数据为 None，否则为 RECENT 响应的值。

IMAP4.rename(oldmailbox, newmailbox): 将名为 oldmailbox 的邮箱重命名为 newmailbox。

IMAP4.response(code): 如果接收到响应 code 或 None，则返回数据。返回给定的代码，而不是通常的类型。

IMAP4.search(charset, criterion[, ...])

在邮箱中搜索匹配的消息。 charset 可能是 None，在这种情况下，不会在对服务器的请求中指定 CHARSET。 IMAP 协议要求至少指定一个标准；当服务器返回错误时将引发异常。

例子：

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select([mailbox[, readonly]]): 选择一个邮箱。返回的数据是 mailbox（EXISTS 响应）中的消息计数。默认的邮箱是 'INBOX'。如果设置了 readonly 标志，则不允许修改邮箱。

IMAP4.send(data): 将 data 发送到远程服务器。您可以覆盖此方法。

IMAP4.setacl(mailbox, who, what): 为邮箱设置一个ACL。该方法是非标准的，但受 Cyrus 服务器支持。

IMAP4.setannotation(mailbox, entry, attribute[, ...]): 为邮箱设置 ANNOTATION。该方法是非标准的，但受 Cyrus 服务器支持。

2.5 版中的新功能。

IMAP4.setquota(root, limits): 设置quota root的资源限制。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。

2.3 版中的新功能。

IMAP4.shutdown(): 关闭在 open 中建立的连接。这个方法被IMAP4.logout()隐式调用。您可以覆盖此方法。

IMAP4.socket(): 返回用于连接到服务器的套接字实例。

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

sort 命令是 search 的变体，具有结果的排序语义。返回的数据包含一个空格分隔的匹配消息号列表。

Sort 在 search_criterion 参数之前有两个参数； sort_criteria 和搜索 charset 的括号列表。请注意，与 search 不同，搜索 charset 参数是强制性的。还有一个uid sort命令对应sort，就像uid search对应search一样。 sort 命令首先使用 charset 参数在邮箱中搜索与给定搜索条件匹配的邮件，以解释搜索条件中的字符串。然后它返回匹配消息的数量。

这是一个 IMAP4rev1 扩展命令。

IMAP4.status(mailbox, names): 请求邮箱的命名状态条件。

IMAP4.store(message_set, command, flag_list)

更改邮箱中邮件的标志处置。 command 由 RFC 2060 的第 6.4.6 节指定为“FLAGS”、“+FLAGS”或“-FLAGS”之一，可选地“.SILENT”的后缀。

例如，要在所有消息上设置删除标志：

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

IMAP4.subscribe(mailbox): 订阅新邮箱。

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

thread 命令是 search 的变体，具有结果的线程语义。返回的数据包含一个以空格分隔的线程成员列表。

线程成员由零个或多个消息号组成，以空格分隔，表示连续的父子节点。

线程在 search_criterion 参数之前有两个参数； threading_algorithm 和搜索 charset。请注意，与 search 不同，搜索 charset 参数是强制性的。还有一个uid thread命令对应thread，就像uid search对应search一样。 thread 命令首先使用 charset 参数在邮箱中搜索与给定搜索条件匹配的邮件，以解释搜索条件中的字符串。然后它返回根据指定线程算法线程化的匹配消息。

这是一个 IMAP4rev1 扩展命令。

2.4 版中的新功能。

IMAP4.uid(command, arg[, ...]): 使用由 UID 而非消息编号标识的消息执行命令参数。返回适合命令的响应。必须至少提供一个参数；如果没有提供，服务器将返回错误并引发异常。

IMAP4.unsubscribe(mailbox): 退订旧邮箱。

IMAP4.xatom(name[, arg[, ...]]): 允许服务器在 CAPABILITY 响应中通知的简单扩展命令。

IMAP4_SSL 的实例只有一种附加方法：

IMAP4_SSL.ssl(): 返回用于与服务器的安全连接的 SSLObject 实例。

IMAP4 的实例定义了以下属性：

IMAP4.PROTOCOL_VERSION: 来自服务器的 CAPABILITY 响应中最新支持的协议。

IMAP4.debug: 控制调试输出的整数值。初始化值取自模块变量 Debug。大于三个的值跟踪每个命令。

20.10.2. IMAP4 示例

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

import getpass, imaplib

M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print 'Message %s\n%s\n' % (num, data[0][1])
M.close()
M.logout()

20.10. imaplib — IMAP4 协议客户端 — Python 文档

20.10. 映射库 — IMAP4 协议客户端

20.10.1。 IMAP4 对象

20.10.2. IMAP4 示例