20.10. imaplib — IMAP4 protocol client

源程序代码：Lib/imaplib.py

---

本模块定义了三类， IMAP4、 IMAP4_SSL和IMAP4_stream，其中封装到 IMAP4 服务器的连接并实施一个大型的 IMAP4rev1 客户端协议子集所界定的 RFC 2060。它是向下的兼容 IMAP4 (RFC 1730） 服务器，但是要注意 IMAP4状态命令不支持。

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

class imaplib.IMAP4([host[, port]])

此类实现实际的 IMAP4 协议。创建连接和协议版本 （IMAP4 或 IMAP4rev1） 的实例初始化时确定的。如果未指定主机，则使用" （本地主机）。如果省略了端口，则使用标准的 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]]]])

这是通过 SSL 加密套接字连接的IMAP4源自一个子类 （若要使用此类需要编译的插座模块与 SSL 支持）。如果未指定主机，则使用" （本地主机）。如果端口省略，则使用标准的 IMAP4 在 SSL 端口 (993)。密钥文件和certfile也是可选的 — — 它们可以包含一个 PEM 格式私人密钥和证书链文件对于 SSL 连接。

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

class imaplib.IMAP4_stream(command)

这是来自IMAP4连接到stdin/标准输出文件描述符创建通过将命令传递给os.popen2()的一个子类。

在版本 2.3中新增。

以下的效用函数的定义：

imaplib.Internaldate2tuple(datestr)

解析 IMAP4 INTERNALDATE字符串并返回相应的当地时间。如果该字符串有格式错误，返回值是一个time.struct_time实例或根本没有。

imaplib.Int2AP(num)

将整数转换成字符串使用字符从集合 [A ...... P]。

imaplib.ParseFlags(flagstr)

转换 IMAP4旗帜响应单个标志的元组。

imaplib.Time2Internaldate(date_time)

Convert date_time to an IMAP4 INTERNALDATE representation. The return value is a string in the form: "DD-Mmm-YYYY HH:MM:SS +HHMM" (including double-quotes). The date_time argument can be a number (int or float) representing seconds since epoch (as returned by time.time()), a 9-tuple representing local time (as returned by time.localtime()), or a double-quoted string. In the last case, it is assumed to already be in the correct format.

注意，IMAP4 邮件数字发生变化随着邮箱的变化 ；尤其是，清除命令执行删除后剩余的消息会重新编号。所以它是非常明智的做法相反，使用 UID 命令内所列的 Uid。

在本模块的结尾，还有一个包含更广泛的使用的例子的测试部分。

请参见

对于服务器执行它描述议定书 》，和来源和二进制文件的文档，都可以在华盛顿大学的IMAP 信息中心（http://www.washington.edu/imap/） 发现。

20.10.1. IMAP4 Objects

IMAP4rev1 的所有命令都由方法的名称相同，大写或小写字母都表示。

All arguments to commands are converted to strings, except for AUTHENTICATE, and the last argument to APPEND which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn’t enclosed with either parentheses or double quotes) each string is quoted. However, the password argument to the LOGIN command is always quoted. If you want to avoid having an argument string quoted (eg: the flags argument to STORE) then enclose the string in parentheses (eg: r'(\Deleted)').

每个命令将返回一个元组： （类型， [数据， ...]) 类型通常是'OK'或'NO'，并且数据中的文本命令的响应或从该命令已获授权的结果。每个数据是一个字符串，或者一个元组。如果一个元组，然后第一部分是响应头中的，第二部分包含的数据 （即： 字面上值）。

Message_set选项下面的命令是一个字符串，指定一个或多个消息，需采取行动。它可能是简单的消息数 ('1')，一系列的消息数据 （'2： 4'），或一组由逗号分隔的非连续范围 (' 1： 3、 6:9 ')。一系列可以包含一个星号以指示无限的上限 (3： *')。

IMAP4实例都具有以下方法：

IMAP4.append(mailbox, flags, date_time, message)

将消息追加到指定的邮箱。

IMAP4.authenticate(mechanism, authobject)

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

机制指定的身份验证机制是使用 — — 它应该出现在窗体中的实例变量功能 AUTH = 机制。

authobject必须是一个可调用的对象：

data = authobject(response)

它将调用来处理服务器继续响应。它应该返回的数据将被编码并发送到服务器。它应该返回没有如果客户端中断响应*应改为发送。

IMAP4.check()

检查邮箱服务器上。

IMAP4.close()

关闭当前选定的邮箱。从可写的邮箱中删除已删除的邮件。这是推荐的命令之前注销。

IMAP4.copy(message_set, new_mailbox)

复制message_set到new_mailbox结尾的邮件。

IMAP4.create(mailbox)

创建新的邮箱命名邮箱。

IMAP4.delete(mailbox)

删除旧命名邮箱的邮箱。

IMAP4.deleteacl(mailbox, who)

删除 （删除任何权利） 为谁在邮箱上设置的 Acl。

在 2.4 版本新增。

IMAP4.expunge()

从选定的邮箱中永久删除已删除的项目。生成一个清除的反应，每个已删除的邮件。返回的数据包含清除消息号码按接收顺序的列表。

IMAP4.fetch(message_set, message_parts)

Fetch (parts of) messages. message_parts should be a string of message part names enclosed within parentheses, eg: "(UID BODY[TEXT])". Returned data are tuples of message part envelope and data.

IMAP4.getacl(mailbox)

获取邮箱的ACLs。该方法是不标准的但由Cyrus服务器支持。

IMAP4.getannotation(mailbox, entry, attribute)

检索指定的批注的邮箱。该方法是不标准的但由Cyrus服务器支持。

新版本 2.5 中的。

IMAP4.getquota(root)

得到配额根资源的使用和限制。这种方法是扩展的在 rfc2087 中定义 IMAP4 配额的一部分。

新版本 2.3。

IMAP4.getquotaroot(mailbox)

获取已命名的邮箱的配额的根列表。这种方法是扩展的在 rfc2087 中定义 IMAP4 配额的一部分。

新版本 2.3。

IMAP4.list([directory[, pattern]])

列出目录模式匹配中的邮箱名称。目录默认为顶级邮件文件夹中，并且模式默认以匹配任何内容。返回的数据包含LIST响应的列表。

IMAP4.login(user, password)

标识客户端使用明文密码。密码将被引用。

IMAP4.login_cram_md5(user, password)

标识客户端来保护密码时，请强制使用CRAM-MD5验证。将唯一的工作，如果服务器响应能力包括短语AUTH = 补习班 MD5。

新版本 2.3。

IMAP4.logout()

关闭连接到服务器。返回服务器再见响应。

IMAP4.lsub([directory[, pattern]])

列出订阅的邮箱名称在目录匹配的模式。目录的默认的顶级目录和模式来匹配任何邮箱的默认值。返回的数据是元组的邮件部分信封和数据。

IMAP4.myrights(mailbox)

显示我的邮箱 （即我对邮箱的权利） 的 Acl。

在 2.4 版本新。

IMAP4.namespace()

返回 IMAP 的命名空间，如在 RFC2342 中定义。

新版本 2.3。

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)

承担作为用户的身份验证。允许代理授权的管理员到任何用户的邮箱。

新版本 2.3。

IMAP4.read(size)

从远程服务器读取大小字节为单位）。您可以重写此方法。

IMAP4.readline()

从远程服务器读取一行。您可以重写此方法。

IMAP4.recent()

提示服务器以获取更新。返回的数据是没有如果没有新的消息，最近响应的其他值。

IMAP4.rename(oldmailbox, newmailbox)

重命名命名为oldmailbox到newmailbox的邮箱。

IMAP4.response(code)

返回数据的响应代码如果收到，或者根本没有。返回给定的代码，而不是通常的类型。

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

邮箱匹配的邮件中搜索。字符集也可能没有，在这种情况下没有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]])

选择一个邮箱。返回的数据是邮箱（存在响应） 中的消息数。默认邮箱是收件箱。如果设置只读标志，则不允许对邮箱进行修改。

IMAP4.send(data)

将数据发送到远程服务器。您可以重写此方法。

IMAP4.setacl(mailbox, who, what)

设置ACL的邮箱。该方法是不标准的但由Cyrus服务器支持。

IMAP4.setannotation(mailbox, entry, attribute[, ...])

将注释s邮箱的设置。该方法是不标准的但由Cyrus服务器支持。

新版本 2.5 中的。

IMAP4.setquota(root, limits)

设置配额根资源限制。这种方法是扩展的在 rfc2087 中定义 IMAP4 配额的一部分。

新版本 2.3。

IMAP4.shutdown()

关闭在打开已建立连接。由IMAP4.logout()隐式调用此方法。您可以重写此方法。

IMAP4.socket()

返回套接字用来连接到服务器实例。

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

Sort命令是 variant 类型的搜索和排序结果的语义。返回的数据包含消息的数字匹配的空格分隔的列表。

排序具有两个参数前search_criterion的参数 ；带圆括号列表sort_criteria，和搜索的字符集。请注意，与不同的搜索，搜索的charset参数是必需的。还有那uid 搜索对应于排序方式的uid 排序命令对应于搜索。 Sort命令将先搜索匹配给定的搜索条件在搜索条件中使用的字符集的字符串的解释理由 》 的邮件的邮箱。然后，它返回匹配的消息的数。

这是一个IMAP4rev1扩展命令。

IMAP4.status(mailbox, names)

命名邮箱的状态条件的请求。

IMAP4.store(message_set, command, flag_list)

改变标志部署邮箱中的邮件。6.4.6 条所指定命令 RFC 2060作为一种"标记"，"+ 标志"，或"-标志"，并且可选择带有一个后缀"。沉默"。

例如，要在所有邮件上设置删除标志：

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[, ...])

线程命令是用结果的线程语义搜索的一个变种。返回的数据包含线程成员一个空格分隔列表。

线程组成的零个或多个消息的数字，由空格分隔显示连续的父级和子级。

线程有两个论点之前search_criterion参数 ；threading_algorithm和搜索的字符集。请注意，与不同的搜索，搜索的charset参数是必需的。此外，还有一个uid 线程命令该uid 搜索对应于线程的方式对应于搜索。线程命令首先搜索匹配给定的搜索条件在搜索条件中使用的字符集的字符串的解释理由 》 的邮件的邮箱。然后，它返回线程根据指定的线程处理算法的匹配的消息。

这是一个IMAP4rev1扩展命令。

在 2.4 版本新增。

IMAP4.uid(command, arg[, ...])

与由 UID，而不是消息编号标识的邮件执行命令参数。返回适合于命令的响应。必须提供至少一个参数 ；如果没有提供，服务器将返回错误和异常将引发。

IMAP4.unsubscribe(mailbox)

从旧邮箱退订。

IMAP4.xatom(name[, arg[, ...]])

允许简单的扩展命令由服务器能力响应通知。

IMAP4_SSL的实例有只是一种其他方法：

IMAP4_SSL.ssl()

返回 SSLObject 实例，用于与服务器的安全连接。

IMAP4实例上，定义了以下属性：

IMAP4.PROTOCOL_VERSION

最新支持协议来自服务器的响应能力。

IMAP4.debug

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

20.10.2. IMAP4 Example

这里是一个小的示例 （没有错误检查），打开邮箱并检索，然后打印所有消息：

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()