21.15. imaplib - IMAP4协议客户端¶
源代码： Lib/imaplib.py
此模块定义了三个类：IMAP4，IMAP4_SSL和IMAP4_stream，它封装与IMAP4服务器的连接并实现IMAP4rev1客户端的大型子集协议，如 RFC 2060中所定义。它与IMAP4（ RFC 1730）服务器向后兼容，但请注意，IMAP4不支持STATUS命令。
- class
imaplib.IMAP4(host='', port=IMAP4_PORT)¶ 此类实现实际的IMAP4协议。创建连接并在实例初始化时确定协议版本（IMAP4或IMAP4rev1）。如果未指定主机，则使用
''（本地主机）。如果省略端口，则使用标准IMAP4端口（143）。IMAP4类支持with语句。如果这样使用，在with语句退出时，自动发出IMAP4LOGOUT命令。例如：>>> from imaplib import IMAP4 >>> with IMAP4("domain.org") as M: ... M.noop() ... ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
在版本3.5中已更改：添加了对
with语句的支持。
有三个异常定义为IMAP4类的属性：
- exception
IMAP4.error¶ 对任何错误引发异常。异常的原因作为字符串传递给构造函数。
- exception
IMAP4.abort¶ IMAP4服务器错误导致引发此异常。这是
IMAP4.error的子类。注意，关闭实例和实例化一个新实例通常将允许从此异常恢复。
- exception
IMAP4.readonly¶ 当可写邮箱的状态由服务器更改时，会引发此异常。这是
IMAP4.error的子类。一些其他客户端现在具有写入权限，并且邮箱将需要重新打开以重新获取写入权限。
还有一个安全连接的子类：
- class
imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None)¶ 这是从
IMAP4派生的子类，通过SSL加密的套接字连接（要使用此类，您需要一个使用SSL支持编译的套接字模块）。如果未指定主机，则使用''（本地主机）。如果省略端口，则使用标准的IMAP4 over SSL端口（993）。ssl_context是一个ssl.SSLContext对象，它允许将SSL配置选项，证书和私钥捆绑到单个（可能长期）结构中。有关最佳做法，请参阅Security considerations。密钥文件和certfile是ssl_context的传统替代品 - 它们可以指向SSL连接的PEM格式的私钥和证书链文件。Note that the keyfile/certfile parameters are mutually exclusive with ssl_context, a
ValueErroris raised if keyfile/certfile is provided along with ssl_context.在版本3.3中已更改： 添加了ssl_context参数。
在版本3.4中更改：此类现在支持使用
ssl.SSLContext.check_hostname和服务器名称指示（请参阅ssl.HAS_SNI）。
第二个子类允许由子进程创建的连接：
- class
imaplib.IMAP4_stream(command)¶ 这是从
IMAP4派生的子类，它连接到通过传递命令创建的stdin/stdout文件描述器到subprocess.Popen()。
定义了以下效用函数：
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” t0>（包括双引号）。date_time参数可以是表示自从epoch（由time.time()返回的秒数）的数字（int或float），表示本地时间的9元组time.struct_time（由time.localtime()返回），一个感知的实例datetime.datetime或双引号字符串。在最后一种情况下，假设它已经是正确的格式。
请注意，IMAP4邮件编号随邮箱更改而变化；特别是在EXPUNGE命令执行删除之后，剩余的消息被重新编号。因此，强烈建议使用UID替代，使用UID命令。
在模块的结尾，有一个测试部分，其中包含更广泛的使用示例。
也可以看看
描述协议以及实施协议的服务器的源和二进制文件的文档都可以在华盛顿大学的IMAP信息中心（https://www.washington.edu/imap/ / t1>）。
21.15.1.IMAP4对象¶
所有IMAP4rev1命令由具有相同名称的方法表示（大写或小写）。
命令的所有参数都转换为字符串，除了AUTHENTICATE和作为IMAP4文字传递的APPEND的最后一个参数。如果需要（字符串包含IMAP4协议敏感字符，不包括括号或双引号），每个字符串都被引用。但是，LOGIN命令的密码参数始终被引用。如果你想避免使用引用的参数字符串（例如：STORE的flags参数），请将字符串括在括号中（例如：r'(\Deleted)'）。
Each command returns a tuple: (type, [data, ...]) where type is usually 'OK' or 'NO', and data is either the text from the command response, or mandated results from the command. 每个数据是字符串或元组。如果是元组，那么第一部分是响应的头部，第二部分包含数据（即：'literal'值）。
下面的命令的message_set选项是一个字符串，指定一个或多个要执行操作的消息。它可以是简单消息号（'1'），消息号范围（'2:4'）或一组由逗号（'1:3,6:9'）。范围可以包含星号以指示无限上界（'3:*'）。
IMAP4实例具有以下方法：
IMAP4.append(mailbox, flags, date_time, message)¶将消息附加到命名邮箱。
IMAP4.authenticate(mechanism, authobject)¶验证命令 - 需要响应处理。
机制指定要使用的认证机制 - 它应该以
AUTH=mechanism的形式出现在实例变量capabilities中。authobject必须是可调用对象：
data = authobject(response)
它将被调用来处理服务器继续响应；传递的响应参数将为
bytes。它应该返回bytesdata，将被base64编码并发送到服务器。如果应发送客户端中止响应*，则应返回None。在3.5版本中已更改：字符串用户名和密码现在已编码为
utf-8，而不限于ASCII。
IMAP4.check()¶服务器上的检查点邮箱。
IMAP4.close()¶关闭当前选定的邮箱。已删除的邮件将从可写邮箱中删除。这是
LOGOUT之前的建议命令。
IMAP4.copy(message_set, new_mailbox)¶将message_set邮件复制到new_mailbox的结尾。
IMAP4.create(mailbox)¶创建名为邮箱的新邮箱。
IMAP4.delete(mailbox)¶删除名为邮箱的旧邮箱。
IMAP4.deleteacl(mailbox, who)¶删除为邮箱上的who设置的ACL（删除任何权限）。
IMAP4.expunge()¶从所选邮箱中永久删除已删除的项目。为每个已删除的邮件生成
EXPUNGE响应。返回的数据包含按顺序接收的EXPUNGE消息编号列表。
IMAP4.fetch(message_set, message_parts)¶提取（部分）邮件。message_parts应为括在括号中的消息部分名称的字符串，例如：
“（UID BODY [TEXT]）” t1>。返回的数据是消息部分包络和数据的元组。
IMAP4.getacl(mailbox)¶获取邮箱的
ACL。该方法是非标准的，但由Cyrus服务器支持。
IMAP4.getannotation(mailbox, entry, attribute)¶检索邮箱的指定
ANNOTATION。该方法是非标准的，但由Cyrus服务器支持。
IMAP4.getquota(root)¶获取
quotaroot的资源使用和限制。此方法是rfc2087中定义的IMAP4 QUOTA扩展的一部分。
IMAP4.getquotaroot(mailbox)¶获取名为邮箱的
quotaroots列表。此方法是rfc2087中定义的IMAP4 QUOTA扩展的一部分。
IMAP4.list([directory[, pattern]])¶在匹配模式的目录中列出邮箱名称。目录默认为顶级邮件文件夹，模式默认为匹配任何内容。返回的数据包含
LIST响应的列表。
IMAP4.login(user, password)¶使用明文密码识别客户端。密码将被引用。
IMAP4.login_cram_md5(user, password)¶在识别客户端以保护密码时强制使用
CRAM-MD5身份验证。仅当服务器CAPABILITY响应包括短语AUTH=CRAM-MD5时才起作用。
IMAP4.logout()¶关闭与服务器的连接。返回服务器
BYE响应。
IMAP4.lsub(directory='""', pattern='*')¶在目录匹配模式中列出预订的邮箱名称。目录默认为顶级目录，模式默认为与任何邮箱匹配。返回的数据是消息部分包络和数据的元组。
IMAP4.myrights(mailbox)¶显示邮箱的ACL（即我对邮箱的权限）。
IMAP4.namespace()¶返回RFC2342中定义的IMAP命名空间。
IMAP4.noop()¶发送
NOOP到服务器。
IMAP4.open(host, port)¶在主机处打开端口的套接字。此方法由
IMAP4构造函数隐式调用。由此方法建立的连接对象将在IMAP4.read()，IMAP4.readline()，IMAP4.send()，和IMAP4.shutdown()方法。您可以覆盖此方法。
IMAP4.partial(message_num, message_part, start, length)¶获取消息的截断部分。返回的数据是消息部分包络和数据的元组。
IMAP4.proxyauth(user)¶假设身份验证为用户。允许授权管理员代理到任何用户的邮箱。
IMAP4.read(size)¶从远程服务器读取大小字节。您可以覆盖此方法。
IMAP4.readline()¶从远程服务器读取一行。您可以覆盖此方法。
IMAP4.recent()¶提示服务器进行更新。返回的数据为
None如果没有新消息，则返回RECENT响应的值。
IMAP4.rename(oldmailbox, newmailbox)¶将名为oldmailbox的邮箱重命名为newmailbox。
IMAP4.response(code)¶返回响应数据代码（如果接收到），或
None。返回给定的代码，而不是通常的类型。
IMAP4.search(charset, criterion[, ...])¶搜索邮箱以查找匹配的邮件。字符集可以是
None，在这种情况下，在向服务器的请求中将不指定CHARSET。IMAP协议要求指定至少一个标准；当服务器返回错误时将引发异常。使用enable()命令启用UTF8=ACCEPT功能时，字符集必须为None例：
# M is a connected IMAP4 instance... typ, msgnums = M.search(None, 'FROM', '"LDJ"') # or: typ, msgnums = M.search(None, '(FROM "LDJ")')
IMAP4.select(mailbox='INBOX', readonly=False)¶选择邮箱。返回的数据是邮箱（
EXISTS响应）中的邮件计数。默认的邮箱是'INBOX'。如果设置了readonly标志，则不允许修改邮箱。
IMAP4.send(data)¶将
data发送到远程服务器。您可以覆盖此方法。
IMAP4.setacl(mailbox, who, what)¶为邮箱设置
ACL。该方法是非标准的，但由Cyrus服务器支持。
IMAP4.setannotation(mailbox, entry, attribute[, ...])¶为邮箱设置
ANNOTATION。该方法是非标准的，但由Cyrus服务器支持。
IMAP4.setquota(root, limits)¶设置
quota根的资源限制。此方法是rfc2087中定义的IMAP4 QUOTA扩展的一部分。
IMAP4.shutdown()¶在
open中建立关闭连接。此方法由IMAP4.logout()隐式调用。您可以覆盖此方法。
IMAP4.socket()¶返回用于连接到服务器的套接字实例。
IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶sort命令是对结果进行排序语义的search的变体。返回的数据包含空格分隔的匹配消息号列表。Sort在search_criterion参数之前有两个参数； sort_criteria的括号列表，以及搜索字符集。请注意，与
search不同，搜索字符集参数是必需的。还有一个uid sort命令，对应于sort的方式uid 搜索对应于search。sort命令首先使用charset参数搜索邮箱中与给定搜索条件匹配的邮件，以解释搜索条件中的字符串。然后它返回匹配消息的数量。这是一个
IMAP4rev1扩展命令。
IMAP4.starttls(ssl_context=None)¶发送
STARTTLS命令。ssl_context参数是可选的，应为ssl.SSLContext对象。这将启用IMAP连接上的加密。有关最佳做法，请参阅Security considerations。版本3.2中的新功能。
在版本3.4中更改：此方法现在支持使用
ssl.SSLContext.check_hostname和服务器名称指示进行主机名检查（请参阅ssl.HAS_SNI）。
IMAP4.status(mailbox, names)¶请求邮箱的命名状态条件。
IMAP4.store(message_set, command, flag_list)¶更改邮箱中邮件的标志位置。命令由 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参数之前有两个参数； a threading_algorithm和搜索字符集。请注意，与
search不同，搜索字符集参数是必需的。还有一个uid 线程命令对应thread的方式uid 搜索对应于search。thread命令首先使用charset参数搜索邮箱中与给定搜索条件匹配的邮件，以解释搜索条件中的字符串。然后它返回根据指定的线程算法线程化的匹配消息。这是一个
IMAP4rev1扩展命令。
IMAP4.uid(command, arg[, ...])¶对由UID标识的消息执行命令args，而不是消息号。返回适合于命令的响应。必须提供至少一个参数；如果没有提供，服务器将返回一个错误，并将引发异常。
IMAP4.unsubscribe(mailbox)¶取消订阅旧邮箱。
IMAP4.xatom(name[, ...])¶允许服务器在
CAPABILITY响应中通知的简单扩展命令。
以下属性在IMAP4的实例上定义：
IMAP4.PROTOCOL_VERSION¶来自服务器的
CAPABILITY响应中最新支持的协议。
IMAP4.debug¶控制调试输出的整数值。初始值取自模块变量
Debug。大于三的值跟踪每个命令。
21.15.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()