20.10. imaplib — IMAP4 协议 Client 端

源代码: Lib/imaplib.py


此模块定义了三个类IMAP4IMAP4_SSLIMAP4_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。

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

See also

可以在华盛顿大学的* IMAP 信息中心*(https://www.washington.edu/imap/)中找到描述协议的文档以及实现该协议的服务器的源和二进制文件。

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

  • 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对应于searchsort命令首先使用 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对应于searchthread命令首先使用 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()