imaplib

imaplib — IMAP4 protocol client

源代码： Lib / imaplib.py

该模块定义了三个类，IMAP4，IMAP4_SSL和IMAP4_stream，其中封装到IMAP4服务器的连接，并执行如在所限定的IMAP4rev1客户端协议的一个大的子集RFC 2060。它向后兼容IMAP4（RFC 1730）服务器，但请注意，该STATUS命令在IMAP4中不受支持。

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

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

这是IMAP4通过SSL加密套接字连接而来的子类（要使用此类，您需要一个使用SSL支持编译的套接字模块）。如果主机没有指定，''（本地主机）被使用。如果省略端口，则使用标准的IMAP4-SSL端口（993）。keyfile和certfile也是可选的 - 它们可以包含用于SSL连接的PEM格式的私钥和证书链文件。

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

class imaplib.IMAP4_stream(command)

这是衍生自一个子类IMAP4，其连接到stdin/stdout通过使创造的文件描述符命令到os.popen2()。

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参数可以是数（整数或浮点数）表示纪元以来秒（由返回的time.time()），代表（如通过返回本地时间9元组time.localtime()），或一个双引号字符串。在最后一种情况下，假定它已经是正确的格式。

请注意，IMAP4邮件号码随邮箱更改而变化; 特别是在EXPUNGE命令执行删除操作后，剩余的消息将被重新编号。因此，使用UID命令来代替使用UID是非常明智的。

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

1. IMAP4对象

所有IMAP4rev1命令都由相同名称的方法表示，无论是大写还是小写。

所有命令的参数都被转换为字符串，除了AUTHENTICATE，以及最后一个参数APPEND作为IMAP4文字传递。如有必要（该字符串包含IMAP4协议敏感字符，不包含括号或双引号），每个字符串都被引用。但是，该命令的密码参数LOGIN始终是引用的。如果你想避免引用一个参数字符串（例如：flags参数STORE），那么将该字符串括在括号内（例如：）r'(\Deleted)'。

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

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

一个IMAP4实例有以下方法：

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

将邮件追加到指定的邮箱。

IMAP4.authenticate(mechanism, authobject)

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

机制指定要使用哪种认证机制 - 它应该出现在capabilities表单中的实例变量中AUTH=mechanism。

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)

删除旧邮箱命名邮箱。

IMAP4.deleteacl(mailbox, who)

删除为邮箱上的用户设置的ACL（删除所有权限）。

2.4版本中的新功能。

IMAP4.expunge()

永久删除所选邮箱中的已删除邮件。EXPUNGE为每个已删除的消息生成一个响应。返回的数据包含EXPUNGE收到订单的消息编号列表。

IMAP4.fetch(message_set, message_parts)

获取（部分）消息。message_parts应该是括在括号内的消息部分名称的字符串，例如："(UID BODY[TEXT])"。返回的数据是消息部分包络和数据的元组。

IMAP4.getacl(mailbox)

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

IMAP4.getannotation(mailbox, entry, attribute)

检索邮箱的指定ANNOTATIONs 。该方法是非标准的，但由服务器支持。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]])

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

IMAP4.login(user, password)

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

IMAP4.login_cram_md5(user, password)

CRAM-MD5识别客户端以保护密码时强制使用身份验证。只有当服务器CAPABILITY响应包含该短语时才会起作用AUTH=CRAM-MD5。

2.3版本的新功能。

IMAP4.logout()

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

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

以目录匹配模式列出订阅的邮箱名称。目录默认为顶级目录，并且模式默认为匹配任何邮箱。返回的数据是消息部分包络和数据的元组。

IMAP4.myrights(mailbox)

显示我的邮箱ACL（即我拥有的邮箱权限）。

2.4版本中的新功能。

IMAP4.namespace()

返回RFC2342中定义的IMAP名称空间。

2.3版本的新功能。

IMAP4.noop()

发送NOOP到服务器。

IMAP4.open(host, port)

在主机上打开套接字到端口。该方法由构造函数隐式调用。通过这种方法建立的连接对象将在被使用，，，和方法。您可以重写此方法。IMAP4IMAP4.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()

提示服务器进行更新。None如果没有新消息，则返回数据，否则返回值RECENT。

IMAP4.rename(oldmailbox, newmailbox)

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

IMAP4.response(code)

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

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

搜索邮箱中的匹配邮件。字符集可能是None，在这种情况下，CHARSET将在服务器的请求中指定no 。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]])

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

IMAP4.send(data)

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

IMAP4.setacl(mailbox, who, what)

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

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

设置ANNOTATIONS代表邮箱。该方法是非标准的，但由Cyrus服务器支持。

2.5版本中的新功能。

IMAP4.setquota(root, limits)

设置quota 根目录的资源限制。此方法是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的加括号列表和搜索字符集。请注意，不同的是search，搜索字符集参数是强制性的。还有一个uid sort对应于命令sort的方式uid search对应search。该sort命令首先使用charset参数在邮箱中搜索与给定搜索条件相匹配的邮件，以便在搜索条件中解释字符串。然后它返回匹配消息的数量。

这是一个IMAP4rev1扩展命令。

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参数前有两个参数; 一个threading_algorithm，以及搜索字符集。请注意，不同的是search，搜索字符集参数是强制性的。还有一个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。大于三的值跟踪每条命令。

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