20.10. imaplib — IMAP4 协议 Client 端

源代码： Lib/imaplib.py

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

imaplib模块提供了三个类，其中IMAP4是 Base Class：

- class * imaplib. IMAP4([* host * [，* port *]])
- 此类实现实际的 IMAP4 协议。实例初始化时，将创建连接并确定协议版本(IMAP4 或 IMAP4rev1)。如果未指定* host ，则使用''(localhost)。如果Ellipsis port *，则使用标准 IMAP4 端口(143)。

IMAP4类的属性定义了三个 exception：

exception IMAP4. error
- 任何错误均引发异常。异常的原因作为字符串传递给构造函数。
exception IMAP4. abort
- IMAP4 服务器错误导致引发此异常。这是IMAP4.error的子类。请注意，关闭实例并实例化一个新实例通常将允许从此异常中恢复。
exception IMAP4. readonly
- 当可写邮箱的状态由服务器更改时，将引发此异常。这是IMAP4.error的子类。现在，其他一些 Client 端具有写权限，并且邮箱将需要重新打开才能重新获得写权限。

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

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

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

- class * imaplib. IMAP4_stream(* command *)
- 这是从IMAP4派生的子类，该子类连接到pass将* command *传递给os.popen2()而创建的stdin/stdout文件 Descriptors。

2.3 版的新Function。

定义了以下 Util Function：

imaplib. Internaldate2tuple(* datestr *)
- 解析 IMAP4 INTERNALDATE字符串并返回相应的本地时间。返回值是time.struct_time实例或None(如果字符串格式错误)。
imaplib. Int2AP(* num *)
- 使用集合[+52+ .. +53+]中的字符将整数转换为字符串表示形式。
imaplib. ParseFlags(* flagstr *)
- 将 IMAP4 FLAGS响应转换为单个标志的 Tuples。
imaplib. Time2Internaldate(* date_time *)
- 将* date_time *转换为 IMAP4 INTERNALDATE表示形式。返回值是形式为"DD-Mmm-YYYY HH:MM:SS +HHMM"的字符串(包括双引号)。 * date_time *参数可以是代表自纪元以来的秒数的数字(int 或 float)(由time.time()返回)，代表本地时间的 9Tuples(由time.localtime()返回)或双引号字符串。在最后一种情况下，假定已经采用了正确的格式。

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

在模块的最后，有一个测试部分，其中包含更广泛的用法示例。

20.10.1. IMAP4 对象

所有 IMAP4rev1 命令均由大小写相同的相同名称的方法表示。

除AUTHENTICATE之外，所有命令参数均转换为字符串，而APPEND的最后一个参数作为 IMAP4Literals 传递。如有必要(该字符串包含 IMAP4 协议敏感字符，并且不包含在括号或双引号中)，每个字符串都用引号引起来。但是，LOGIN命令的* password 参数总是被引用。如果要避免使用引号将参数字符串引起来(例如STORE的 flags *参数)，则将该字符串括在括号中(例如r'(\Deleted)')。

每个命令都返回一个 Tuples：(type, [data, ...])，其中* type 通常是'OK'或'NO'，而 data 是命令响应中的文本或命令中的强制结果。每个 data *是一个字符串或一个 Tuples。如果是 Tuples，则第一部分是响应的标题，第二部分包含数据(即：“Literals”值)。

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

IMAP4实例具有以下方法：

IMAP4. append(邮箱，标志，日期时间，消息)
- 将* message *附加到命名邮箱。
IMAP4. authenticate(机制，* authobject *)
- 验证命令-需要响应处理。

mechanism *指定要使用的身份验证机制-它应以AUTH=mechanism的形式出现在实例变量capabilities中。
authobject *必须是可调用的对象：

data = authobject(response)

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

IMAP4. check ( )
- 服务器上的 Checkpoint 邮箱。
IMAP4. close ( )
- 关闭当前选择的邮箱。删除的邮件将从可写邮箱中删除。这是LOGOUT之前的推荐命令。
IMAP4. copy(* message_set ， new_mailbox *)
- 将* message_set 消息复制到 new_mailbox *的末尾。
IMAP4. create(邮箱)
- 创建名为* mailbox *的新邮箱。
IMAP4. delete(邮箱)
- 删除名为* mailbox *的旧邮箱。
IMAP4. deleteacl(邮箱，谁)
- 删除为邮箱中的用户设置的 ACL(删除任何权限)。

2.4 版的新Function。

IMAP4. expunge ( )
- 永久删除所选邮箱中的已删除邮件。为每个删除的邮件生成一个EXPUNGE响应。返回的数据包含按接收 Sequences 排列的EXPUNGE个消息号的列表。
IMAP4. fetch(* message_set ， message_parts *)
- 提取消息(的一部分)。 * message_parts *应该是用括号括起来的消息部分名称的字符串，例如："(UID BODY[TEXT])"。返回的数据是消息部分信封和数据的 Tuples。
IMAP4. getacl(邮箱)
- 获取ACL代表* mailbox *。该方法是非标准方法，但Cyrus服务器支持该方法。
IMAP4. getannotation(邮箱，条目，属性)
- 检索* mailbox *的指定ANNOTATION。该方法是非标准方法，但Cyrus服务器支持该方法。

2.5 版的新Function。

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

2.3 版的新Function。

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

2.3 版的新Function。

IMAP4. list([目录 [，模式]])
- 在目录匹配模式中列出邮箱名称。 * directory 默认为顶级邮件文件夹， pattern *默认为匹配任何内容。返回的数据包含LIST个响应的列表。
IMAP4. login(* user ， password *)
- 使用纯文本密码标识 Client 端。密码将被引用。
IMAP4. login_cram_md5(* user ， password *)
- 标识 Client 端以保护密码时，强制使用CRAM-MD5身份验证。仅当服务器CAPABILITY响应中包含短语AUTH=CRAM-MD5时才有效。

2.3 版的新Function。

IMAP4. logout ( )
- 关闭与服务器的连接。返回服务器BYE响应。
IMAP4. lsub([目录 [，模式]])
- 以目录匹配模式列出订阅的邮箱名称。 * directory 默认为顶级目录， pattern *默认为匹配任何邮箱。返回的数据是消息部分信封和数据的 Tuples。
IMAP4. myrights(邮箱)
- 显示我的邮箱 ACL(即我在邮箱中拥有的权限)。

2.4 版的新Function。

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

2.3 版的新Function。

IMAP4. noop ( )
- 发送NOOP到服务器。
IMAP4. open(* host ， port *)
- 在* host 处打开套接字到 port *的套接字。 IMAP4构造函数隐式调用此方法。pass此方法构建的连接对象将在IMAP4.read()，IMAP4.readline()，IMAP4.send()和IMAP4.shutdown()方法中使用。您可以重写此方法。
IMAP4. partial(* message_num ， message_part ， start ， length *)
- 提取消息的截断部分。返回的数据是消息部分信封和数据的 Tuples。
IMAP4. proxyauth(* user *)
- 假设身份验证为* user *。允许授权 Management 员代理到任何用户的邮箱。

2.3 版的新Function。

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 协议要求至少指定一个标准。服务器返回错误时将引发异常。

Example:

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

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

IMAP4. select([邮箱 [，只读]])
- 选择一个邮箱。返回的数据是* mailbox 中的邮件计数(EXISTS响应)。默认 mailbox 是'INBOX'。如果设置了 readonly *标志，则不允许修改邮箱。
IMAP4. send(* data *)
- 将data发送到远程服务器。您可以重写此方法。
IMAP4. setacl(邮箱，谁，什么)
- 为* mailbox *设置ACL。该方法是非标准方法，但Cyrus服务器支持该方法。
IMAP4. setannotation(* mailbox ， entry ， attribute * [，* ... *])
- 为* mailbox *设置ANNOTATION s。该方法是非标准方法，但Cyrus服务器支持该方法。

2.5 版的新Function。

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

2.3 版的新Function。

IMAP4. shutdown ( )
- 在open中构建的关闭连接。 IMAP4.logout()隐式调用此方法。您可以重写此方法。
IMAP4. socket ( )
- 返回用于连接服务器的套接字实例。
IMAP4. sort(* sort_criteria ， charset ， search_criterion * [，* ... *])
- sort命令是search的变体，具有对结果进行排序的语义。返回的数据包含以空格分隔的匹配消息号列表。

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

这是一个IMAP4rev1extensions 命令。

IMAP4. status(邮箱，名称)
- 请求* mailbox *的命名状态条件。
IMAP4. store(* message_set ， command ， flag_list *)
- 更改邮箱中邮件的标志配置。 RFC 2060的第 6.4.6 节将* command *指定为“ 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(邮箱)
- 订阅新邮箱。
IMAP4. thread(* threading_algorithm ， charset ， search_criterion * [，* ... *])
- thread命令是search的变体，具有结果的线程语义。返回的数据包含用空格分隔的线程成员列表。

线程成员由零个或多个消息号组成，并用空格分隔，表示连续的父级和子级。

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

这是一个IMAP4rev1extensions 命令。

2.4 版的新Function。

IMAP4. uid(* command ， arg * [，* ... *])
- 用 UID 标识的消息而不是消息号执行命令 args。返回适合命令的响应。必须至少提供一个参数。如果未提供任何内容，则服务器将返回错误并引发异常。
IMAP4. unsubscribe(邮箱)
- 退订旧邮箱。
IMAP4. xatom(* name * [，* arg * [，* ... *]])
- 允许服务器在CAPABILITY响应中通知简单的扩展命令。

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

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

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

IMAP4. PROTOCOL_VERSION
- 服务器CAPABILITY响应中最新支持的协议。
IMAP4. debug
- 整数值，用于控制调试输出。初始化值来自模块变量Debug。大于 3 的值将跟踪每个命令。

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

Docs

Docs4dev

Title here

20.10. imaplib — IMAP4 协议 Client 端

20.10.1. IMAP4 对象

20.10.2. IMAP4 示例