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_PORT *)
  • 此类实现实际的 IMAP4 协议。实例初始化时，将创建连接并确定协议版本(IMAP4 或 IMAP4rev1)。如果未指定* host ，则使用''(localhost)。如果Ellipsis port *，则使用标准 IMAP4 端口(143)。

IMAP4类支持with语句。像这样使用时，当with语句退出时，会自动发出 IMAP4 LOGOUT命令。例如。：

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

在版本 3.5 中进行了更改：添加了对with语句的支持。

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

• exception IMAP4. error

  • 任何错误均引发异常。异常的原因作为字符串传递给构造函数。

• exception IMAP4. abort

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

• exception IMAP4. readonly

  • 当可写邮箱的状态由服务器更改时，将引发此异常。这是IMAP4.error的子类。现在，其他一些 Client 端具有写权限，并且邮箱将需要重新打开才能重新获得写权限。

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

• • class * imaplib. IMAP4_SSL(* host =''， port = IMAP4_SSL_PORT ， keyfile = None ， certfile = None ， ssl_context = None *)
  • 这是从IMAP4派生的子类，该子类pass SSL 加密套接字进行连接(要使用此类，您需要使用 SSL 支持编译的套接字模块)。如果未指定* host ，则使用''(localhost)。如果Ellipsis port *，则使用标准的 IMAP4-over-SSL 端口(993)。 * ssl_context *是一个ssl.SSLContext对象，该对象允许将 SSL 配置选项，证书和私钥 Binding 到一个(可能长期存在)的结构中。请阅读Security considerations以获得最佳做法。

• keyfile 和 certfile 是 ssl_context 的遗留替代品-它们可以指向 PEM 格式的私钥和证书链文件以进行 SSL 连接。请注意， keyfile / certfile 参数与 ssl_context 是互斥的，如果与 ssl_context 一起提供 keyfile / certfile *，则会引发ValueError。

在版本 3.3 中更改：添加了* ssl_context *参数。

在版本 3.4 中进行了更改：该类现在支持使用ssl.SSLContext.check_hostname和服务器名称指示(请参阅ssl.HAS_SNI)检查主机名。

从 3.6 版开始不推荐使用：* keyfile 和 certfile 不再推荐使用 ssl_context *。请改用ssl.SSLContext.load_cert_chain()，或让ssl.create_default_context()为您选择系统的受信任 CA 证书。

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

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

定义了以下 Util Function：

• imaplib. Internaldate2tuple(* datestr *)

  • 解析 IMAP4 INTERNALDATE字符串并返回相应的本地时间。如果字符串格式错误，则返回值为time.struct_timeTuples 或None。

• imaplib. Int2AP(* num *)

  • 使用集合[+76+ .. +77+]中的字符将整数转换为字符串表示形式。

• imaplib. ParseFlags(* flagstr *)

  • 将 IMAP4 FLAGS响应转换为单个标志的 Tuples。

• imaplib. Time2Internaldate(* date_time *)

  • 将* date_time *转换为 IMAP4 INTERNALDATE表示形式。返回值是形式为"DD-Mmm-YYYY HH:MM:SS +HHMM"(包括双引号)的字符串。 * date_time *参数可以是一个数字(整数或浮点数)，表示自纪元以来的秒数(由time.time()返回)，一个 9Tuples，表示本地时间time.struct_time的实例(由time.localtime()返回)，有意识的datetime.datetime实例，或者用双引号引起来的字符串。在最后一种情况下，假定已经采用了正确的格式。

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

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

IMAP4 Objects

所有 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)

将调用它来处理服务器连续响应；传递的* response *参数为bytes。它应返回bytes * data *，该数据将以 base64 编码并发送到服务器。如果应该发送 Client 端中止响应*，它应该返回None。

在版本 3.5 中进行了更改：现在，字符串用户名和密码已编码为utf-8，而不再是 ASCII。

• 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(删除任何权限)。

• IMAP4. enable(* capability *)

  • 启用Function(请参阅 RFC 5161)。大多数Function不需要启用。当前仅支持UTF8=ACCEPTFunction(请参阅 RFC 6855)。

版本 3.5 中的新Function：enable()方法本身以及 RFC 6855支持。

• 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服务器支持该方法。

• IMAP4. getquota(* root *)

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

• IMAP4. getquotaroot(邮箱)

  • 获取名为* mailbox *的quota roots列表。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。

• IMAP4. list([目录 [，模式]])

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

• IMAP4. login(* user ， password *)

  • 使用纯文本密码标识 Client 端。 密码将被引用。

• IMAP4. login_cram_md5(* user ， password *)

  • 标识 Client 端以保护密码时，强制使用CRAM-MD5身份验证。仅当服务器CAPABILITY响应中包含短语AUTH=CRAM-MD5时才有效。

• IMAP4. logout ( )

  • 关闭与服务器的连接。返回服务器BYE响应。

在 3.8 版中更改：该方法不再忽略静默的任意异常。

• IMAP4. lsub(* directory ='“”'， pattern ='')

  • 以目录匹配模式列出订阅的邮箱名称。 * directory 默认为顶级目录， pattern *默认为匹配任何邮箱。返回的数据是消息部分信封和数据的 Tuples。

• IMAP4. myrights(邮箱)

  • 显示我的邮箱 ACL(即我在邮箱中拥有的权限)。

• IMAP4. namespace ( )

  • 返回 RFC 2342中定义的 IMAP 命名空间。

• IMAP4. noop ( )

  • 发送NOOP到服务器。

• IMAP4. open(* host ， port *)

  • 在* host 处打开套接字到 port *的套接字。 IMAP4构造函数隐式调用此方法。pass此方法构建的连接对象将在IMAP4.read()，IMAP4.readline()，IMAP4.send()和IMAP4.shutdown()方法中使用。您可以重写此方法。

用参数self，host，port引发auditing event imaplib.open。

• IMAP4. partial(* message_num ， message_part ， start ， length *)

  • 提取消息的截断部分。返回的数据是消息部分信封和数据的 Tuples。

• IMAP4. proxyauth(* user *)

  • 假设身份验证为* user *。允许授权 Management 员代理到任何用户的邮箱。

• 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 协议要求至少指定一个标准。服务器返回错误时将引发异常。如果使用enable()命令启用了UTF8=ACCEPTFunction，则 charset *必须为None。

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 ='INBOX'， readonly = False *)

  • 选择一个邮箱。返回的数据是* mailbox 中的邮件计数(EXISTS响应)。默认 mailbox 是'INBOX'。如果设置了 readonly *标志，则不允许修改邮箱。

• IMAP4. send(* data *)

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

用参数self，data引发auditing event imaplib.send。

• IMAP4. setacl(邮箱，谁，什么)

  • 为* mailbox *设置ACL。该方法是非标准方法，但Cyrus服务器支持该方法。

• IMAP4. setannotation(* mailbox ， entry ， attribute * [，* ... *])

  • 为* mailbox *设置ANNOTATION s。该方法是非标准方法，但Cyrus服务器支持该方法。

• IMAP4. setquota(* root ， limits *)

  • 设置quota * root 的资源 limits *。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。

• 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. starttls(* ssl_context = None *)
  • 发送STARTTLS命令。 * ssl_context *参数是可选的，应为ssl.SSLContext对象。这将在 IMAP 连接上启用加密。请阅读Security considerations以获取最佳做法。

3.2 版中的新Function。

在版本 3.4 中进行了更改：该方法现在支持使用ssl.SSLContext.check_hostname和服务器名称指示(请参阅ssl.HAS_SNI)进行主机名检查。

• 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 命令。

• IMAP4. uid(* command ， arg * [，* ... *])

  • 用 UID 标识的消息而不是消息号执行命令 args。返回适合命令的响应。必须至少提供一个参数。如果未提供任何内容，则服务器将返回错误并引发异常。

• IMAP4. unsubscribe(邮箱)

  • 退订旧邮箱。

• IMAP4. xatom(* name * [，* ... *])

  • 允许服务器在CAPABILITY响应中通知简单的扩展命令。

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

• IMAP4. PROTOCOL_VERSION

  • 服务器CAPABILITY响应中最新支持的协议。

• IMAP4. debug

  • 整数值，用于控制调试输出。初始化值来自模块变量Debug。大于 3 的值将跟踪每个命令。

• IMAP4. utf8_enabled

  • 布尔值，通常为False，但如果为UTF8=ACCEPTFunction成功发出了enable()命令，则将其设置为True。

3.5 版中的新Function。

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