imaplib ---IMAP4协议客户端

源代码: Lib/imaplib.py


该模块定义了三个类, IMAP4IMAP4_SSLIMAP4_stream 它封装了到IMAP4服务器的连接,并实现了在中定义的IMAP4rev1客户机协议的一个子集。 RFC 2060 . 它与IMAP4向后兼容 (RFC 1730 )服务器,但请注意 STATUS IMAP4中不支持命令。

三个类由 imaplib 模块, IMAP4 是基类:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

此类实现了实际的IMAP4协议。创建连接,并在初始化实例时确定协议版本(imap4或imap4rev1)。如果 host 未指定, '' 使用(本地主机)。如果 port 省略时,使用标准IMAP4端口(143)。可选的 超时 参数指定连接尝试的超时时间(秒)。如果未给定超时或为“无”,则使用全局默认套接字超时。

这个 IMAP4 类支持 with 语句。当这样使用时,imap4 LOGOUTwith 语句退出。例如。::

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

在 3.5 版更改: 支持 with 语句已添加。

在 3.9 版更改: 可选的 超时 已添加参数。

三个例外定义为 IMAP4 类:

exception IMAP4.error

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

exception IMAP4.abort

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

exception IMAP4.readonly

当可写邮箱的状态被服务器更改时,会引发此异常。这是一个子类 IMAP4.error . 其他一些客户端现在具有写入权限,需要重新打开邮箱才能重新获得写入权限。

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

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None, timeout=None)

这是派生自 IMAP4 它通过一个SSL加密的套接字进行连接(要使用这个类,您需要一个使用SSL支持编译的套接字模块)。如果 host 未指定, '' 使用(本地主机)。如果 port 如果省略,则使用标准的IMAP4 over SSL端口(993)。 ssl_context 是一个 ssl.SSLContext 对象,它允许将SSL配置选项、证书和私钥绑定到单个(可能是长期存在的)结构中。请阅读 安全注意事项 最佳实践。

关键文件证书文件 是传统的替代品 ssl_context -它们可以指向用于SSL连接的PEM格式的私钥和证书链文件。请注意 关键文件 / 证书文件 参数与互斥 ssl_context ,A ValueError 如果 关键文件 / 证书文件 随附 ssl_context .

可选的 超时 参数指定连接尝试的超时时间(秒)。如果未给定超时或为“无”,则使用全局默认套接字超时。

在 3.3 版更改: ssl_context 已添加参数。

在 3.4 版更改: 类现在支持主机名检查 ssl.SSLContext.check_hostname服务器名称指示 (见 ssl.HAS_SNI

3.6 版后已移除: 关键文件证书文件 被否决,赞成 ssl_context . 请使用 ssl.SSLContext.load_cert_chain() 相反,还是让 ssl.create_default_context() 为您选择系统的可信CA证书。

在 3.9 版更改: 可选的 超时 已添加参数。

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

class imaplib.IMAP4_stream(command)

这是派生自 IMAP4 连接到 stdin/stdout 通过传递创建的文件描述符 命令subprocess.Popen() .

定义了以下实用程序功能:

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 参数可以是表示自epoch以来秒数的数字(int或float)(由返回) time.time() )表示本地时间的9元组 time.struct_time (如返回) time.localtime() )的一个已知实例 datetime.datetime 或双引号字符串。在最后一种情况下,假设它已经是正确的格式。

请注意,随着邮箱的更改,IMAP4邮件号码也会发生更改,特别是在 EXPUNGE 命令执行删除操作。其余消息将重新编号。因此,最好用uid命令代替uid。

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

参见

华盛顿大学IMAP信息中心描述该协议的文件、实施该协议的服务器的源文件都可以在( 源代码 )https://github.com/uw-imap/imap( 未维护 )。

IMAP4对象

所有imap4rev1命令都由相同名称的方法(大写或小写)表示。

命令的所有参数都转换为字符串,除了 AUTHENTICATE 最后一个参数是 APPEND 它作为一个imap4文本传递。如果需要(字符串包含IMAP4协议敏感字符,并且没有用括号或双引号括起来),每个字符串都会被引用。但是, 密码 参数 LOGIN 命令总是被引用。如果要避免引用参数字符串(例如: flags 参数 STORE )然后将字符串括在括号中(例如: r'(\Deleted)'

每个命令返回一个元组: (type, [data, ...]) 在哪里? type 通常是 'OK''NO'data 是来自命令响应的文本,或者是来自命令的强制结果。各 data 或者是 bytes ,或元组。如果是元组,则第一部分是响应的头,第二部分包含数据(即:“literal”值)。

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

IMAP4 实例具有以下方法:

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

追加 消息 到命名邮箱。

IMAP4.authenticate(mechanism, authobject)

authenticate命令---需要响应处理。

机制 指定要使用的身份验证机制-它应出现在实例变量中 capabilities 形式上 AUTH=mechanism .

Auto对象 必须是可调用对象::

data = authobject(response)

它将被调用以处理服务器继续响应;该 响应 它传递的参数将是 bytes . 它应该会回来 bytes data 它将被base64编码并发送到服务器。它应该会回来 None 如果客户端中止响应 * 应该改为发送。

在 3.5 版更改: 字符串用户名和密码现在编码为 utf-8 而不是局限于ASCII。

IMAP4.check()

服务器上的检查点邮箱。

IMAP4.close()

关闭当前选定的邮箱。删除的邮件将从可写邮箱中删除。这是之前建议的命令 LOGOUT .

IMAP4.copy(message_set, new_mailbox)

拷贝 message_set 邮件到的结尾 new_mailbox .

IMAP4.create(mailbox)

创建名为的新邮箱 信箱 .

IMAP4.delete(mailbox)

删除名为的旧邮箱 信箱 .

IMAP4.deleteacl(mailbox, who)

删除邮箱上为who设置的acls(删除任何权限)。

IMAP4.enable(capability)

使能 能力 (见 RFC 5161 )。大多数功能不需要启用。目前只有 UTF8=ACCEPT 支持功能(请参见 RFC 6855

3.5 新版功能: 这个 enable() 方法本身,以及 RFC 6855 支持。

IMAP4.expunge()

从选定邮箱中永久删除已删除的邮件。生成一个 EXPUNGE 对每个已删除邮件的响应。返回的数据包含 EXPUNGE 按顺序接收的消息编号。

IMAP4.fetch(message_set, message_parts)

提取(部分)消息。 message_parts 应该是包含在括号内的消息部分名称的字符串,例如: "(UID BODY[TEXT])" . 返回的数据是消息部分信封和数据的元组。

IMAP4.getacl(mailbox)

得到 ACL 用于 信箱 . 该方法是非标准的,但受 Cyrus 服务器。

IMAP4.getannotation(mailbox, entry, attribute)

检索指定的 ANNOTATION 用于 信箱 . 该方法是非标准的,但受 Cyrus 服务器。

IMAP4.getquota(root)

得到 quota root 的资源使用和限制。此方法是RFC2087中定义的IMAP4配额扩展的一部分。

IMAP4.getquotaroot(mailbox)

获得名单 quota roots 对于命名 信箱 . 此方法是RFC2087中定义的IMAP4配额扩展的一部分。

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

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

IMAP4.login(user, password)

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

IMAP4.login_cram_md5(user, password)

使用武力 CRAM-MD5 在识别客户端以保护密码时进行身份验证。只有在服务器 CAPABILITY 回答包括短语 AUTH=CRAM-MD5 .

IMAP4.logout()

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

在 3.8 版更改: 该方法不再忽略无提示的任意异常。

IMAP4.lsub(directory='""', pattern='*')

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

IMAP4.myrights(mailbox)

显示邮箱的ACL(即邮箱上的权限)。

IMAP4.namespace()

返回在中定义的IMAP命名空间 RFC 2342 .

IMAP4.noop()

发送 NOOP 服务器。

IMAP4.open(host, port, timeout=None)

打开插座 porthost . 可选的 超时 参数指定连接尝试的超时时间(秒)。如果未给定超时或为“无”,则使用全局默认套接字超时。还要注意,如果 超时 参数设置为零,它将引发 ValueError 拒绝创建非阻塞套接字。此方法由 IMAP4 构造器。通过此方法建立的连接对象将用于 IMAP4.read()IMAP4.readline()IMAP4.send()IMAP4.shutdown() 方法。您可以重写此方法。

提出一个 auditing event imaplib.open 带着论据 selfhostport .

在 3.9 版更改: 这个 超时 已添加参数。

IMAP4.partial(message_num, message_part, start, length)

获取消息的截断部分。返回的数据是消息部分信封和数据的元组。

IMAP4.proxyauth(user)

假定身份验证为 user . 允许授权管理员代理任何用户的邮箱。

IMAP4.read(size)

读数 size 来自远程服务器的字节。您可以重写此方法。

IMAP4.readline()

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

IMAP4.recent()

提示服务器进行更新。返回的数据是 None 如果没有新消息,则为 RECENT 反应。

IMAP4.rename(oldmailbox, newmailbox)

重命名名为的邮箱 老邮箱新邮箱 .

IMAP4.response(code)

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

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

在邮箱中搜索匹配的邮件。 charset 可能是 None ,在这种情况下没有 CHARSET 将在对服务器的请求中指定。IMAP协议要求至少指定一个条件;当服务器返回错误时,将引发异常。 charset 必须是 None 如果 UTF8=ACCEPT 使用启用了功能 enable() 命令。

例子::

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

选择邮箱。返回的数据是中的消息数 信箱 (EXISTS 反应)。默认值 信箱'INBOX' . 如果 只读 已设置标志,不允许修改邮箱。

IMAP4.send(data)

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

提出一个 auditing event imaplib.send 带着论据 selfdata .

IMAP4.setacl(mailbox, who, what)

设置一个 ACL 对于 信箱 . 该方法是非标准的,但受 Cyrus 服务器。

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

集合 ANNOTATION 用于 信箱 . 该方法是非标准的,但受 Cyrus 服务器。

IMAP4.setquota(root, limits)

设置 quota root 资源 limit . 此方法是RFC2087中定义的IMAP4配额扩展的一部分。

IMAP4.shutdown()

在中建立的紧密连接 open . 此方法由隐式调用 IMAP4.logout() .您可以重写此方法。

IMAP4.socket()

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

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

这个 sort 命令是 search 结果的排序语义。返回的数据包含一个空格分隔的匹配消息编号列表。

排序前有两个参数 search_criterion 参数;用括号括起来的 sort_criteria 和搜索 charset . 注意,与 search 搜索 charset 参数是必需的。还有一个 uid sort 对应于的命令 sort 方式 uid search 对应于 search . 这个 sort 命令首先使用charset参数搜索邮箱中与给定搜索条件匹配的邮件,以解释搜索条件中的字符串。然后返回匹配消息的数量。

这是一个 IMAP4rev1 扩展命令。

IMAP4.starttls(ssl_context=None)

发送一个 STARTTLS 命令。这个 ssl_context 参数是可选的,应为 ssl.SSLContext 对象。这将在IMAP连接上启用加密。请阅读 安全注意事项 最佳实践。

3.2 新版功能.

在 3.4 版更改: 该方法现在支持主机名检查 ssl.SSLContext.check_hostname服务器名称指示 (见 ssl.HAS_SNI

IMAP4.status(mailbox, names)

请求的命名状态条件 信箱 .

IMAP4.store(message_set, command, flag_list)

更改邮箱中邮件的标志配置。 命令 第6.4.6节规定 RFC 2060 作为“flags”、“+flags”或“-flags”之一,可选后缀为“.silent”。

例如,要在所有消息上设置删除标志,请执行以下操作:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

注解

正在创建包含“]”(例如:“ [test] “”违反 RFC 3501 (IMAP协议)。然而,imaplib历史上允许创建这样的标签,而流行的imap服务器(如gmail)接受并生成这样的标志。也有一些非python程序可以创建这样的标记。尽管这是一种违反RFC的行为,而且IMAP客户机和服务器应该是严格的,但是imaplib仍然允许出于向后兼容性的原因创建此类标记,并且从python 3.6开始,如果这些标记是从服务器发送的,则会对它们进行处理,因为这提高了真实世界的兼容性。

IMAP4.subscribe(mailbox)

订阅新邮箱。

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

这个 thread 命令是 search 结果的线程语义。返回的数据包含以空格分隔的线程成员列表。

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

线程前面有两个参数 search_criterion 论证(a); threading_algorithm 和搜索 charset . 注意,与 search 搜索 charset 参数是必需的。还有一个 uid thread 对应于的命令 thread 方式 uid search 对应于 search . 这个 thread 命令首先使用charset参数搜索邮箱中与给定搜索条件匹配的邮件,以解释搜索条件中的字符串。然后,它返回根据指定的线程算法线程化的匹配消息。

这是一个 IMAP4rev1 扩展命令。

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

使用由uid标识的消息而不是消息编号执行命令参数。返回适用于命令的响应。必须至少提供一个参数;如果未提供任何参数,服务器将返回错误并引发异常。

IMAP4.unsubscribe(mailbox)

取消订阅旧邮箱。

IMAP4.unselect()

imaplib.IMAP4.unselect() 释放与选定邮箱关联的服务器资源,并将服务器返回到已验证状态。此命令执行的操作与 imaplib.IMAP4.close() ,但不会从当前选定的邮箱中永久删除任何邮件。

3.9 新版功能.

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

允许服务器通知的简单扩展命令 CAPABILITY 反应。

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

IMAP4.PROTOCOL_VERSION

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

IMAP4.debug

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

IMAP4.utf8_enabled

布尔值,通常为 False ,但被设置为 True 如果一个 enable() 已成功为发出命令 UTF8=ACCEPT 能力。

3.5 新版功能.

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