imaplib
---IMAP4协议客户端¶
源代码: Lib/imaplib.py
该模块定义了三个类, IMAP4
, IMAP4_SSL
和 IMAP4_stream
它封装了到IMAP4服务器的连接,并实现了在中定义的IMAP4rev1客户机协议的一个子集。 RFC 2060 . 它与IMAP4向后兼容 (RFC 1730 )服务器,但请注意 STATUS
IMAP4中不支持命令。
- class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶
此类实现了实际的IMAP4协议。创建连接,并在初始化实例时确定协议版本(imap4或imap4rev1)。如果 host 未指定,
''
使用(本地主机)。如果 port 省略时,使用标准IMAP4端口(143)。可选的 超时 参数指定连接尝试的超时时间(秒)。如果未给定超时或为“无”,则使用全局默认套接字超时。这个
IMAP4
类支持with
语句。当这样使用时,imap4LOGOUT
当with
语句退出。例如。::>>> 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.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.noop()¶
发送
NOOP
服务器。
- IMAP4.open(host, port, timeout=None)¶
打开插座 port 在 host . 可选的 超时 参数指定连接尝试的超时时间(秒)。如果未给定超时或为“无”,则使用全局默认套接字超时。还要注意,如果 超时 参数设置为零,它将引发
ValueError
拒绝创建非阻塞套接字。此方法由IMAP4
构造器。通过此方法建立的连接对象将用于IMAP4.read()
,IMAP4.readline()
,IMAP4.send()
和IMAP4.shutdown()
方法。您可以重写此方法。提出一个 auditing event
imaplib.open
带着论据self
,host
,port
.在 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
带着论据self
,data
.
- 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实例¶
以下是打开邮箱并检索和打印所有邮件的最小示例(无错误检查)::
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()