imaplib模块
imaplib ---IMAP4协议客户端
该模块定义了三个类， IMAP4 ， IMAP4_SSL 和 IMAP4_stream 它封装了到IMAP4服务器的连接，并实现了在中定义的IMAP4rev1客户机协议的一个子集。 RFC 2060 . 它与IMAP4向后兼容 (RFC 1730 ）服务器，但请注意 STATUS IMAP4中不支持命令。
IMAP4 是基类：
class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)
此类实现了实际的IMAP4协议。创建连接，并在初始化实例时确定协议版本（imap4或imap4rev1）。如果 host 未指定， '' 使用（本地主机）。如果 port 省略时，使用标准IMAP4端口（143）。可选的 超时 参数指定连接尝试的超时时间（秒）。如果未给定超时或为“无”，则使用全局默认套接字超时。
这个 IMAP4 类支持 with 语句。当这样使用时，imap4 LOGOUT 当 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派生的子类，该子类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 *)
-
IMAP4.expunge( )- 永久删除所选邮箱中的已删除邮件。为每个删除的邮件生成一个
EXPUNGE响应。返回的数据包含按接收 Sequences 排列的EXPUNGE个消息号的列表。
- 永久删除所选邮箱中的已删除邮件。为每个删除的邮件生成一个
-
IMAP4.fetch(* message_set ， message_parts *)- 提取消息(的一部分)。 * message_parts *应该是用括号括起来的消息部分名称的字符串，例如：
"(UID BODY[TEXT])"。返回的数据是消息部分信封和数据的 Tuples。
- 提取消息(的一部分)。 * message_parts *应该是用括号括起来的消息部分名称的字符串，例如：
-
IMAP4.getacl(邮箱)- 获取
ACL代表* mailbox *。该方法是非标准方法，但Cyrus服务器支持该方法。
- 获取
-
IMAP4.getannotation(邮箱，条目，属性)- 检索* mailbox *的指定
ANNOTATION。该方法是非标准方法，但Cyrus服务器支持该方法。
- 检索* mailbox *的指定
-
IMAP4.getquota(* root *)- 获取
quota* root *的资源使用情况和限制。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。
- 获取
-
IMAP4.getquotaroot(邮箱)- 获取名为* mailbox *的
quotaroots列表。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。
- 获取名为* mailbox *的
-
IMAP4.list([目录 [，模式]])- 在目录匹配模式中列出邮箱名称。 * directory 默认为顶级邮件文件夹， pattern *默认为匹配任何内容。返回的数据包含
LIST个响应的列表。
- 在目录匹配模式中列出邮箱名称。 * directory 默认为顶级邮件文件夹， pattern *默认为匹配任何内容。返回的数据包含
-
IMAP4.login(* user ， password *)- 使用纯文本密码标识 Client 端。 密码将被引用。
-
IMAP4.login_cram_md5(* user ， password *)- 标识 Client 端以保护密码时，强制使用
CRAM-MD5身份验证。仅当服务器CAPABILITY响应中包含短语AUTH=CRAM-MD5时才有效。
- 标识 Client 端以保护密码时，强制使用
-
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。返回给定的代码，而不是通常的类型。
- 返回数据，以获取响应* code *或
-
IMAP4.search(* charset ， criterion * [，* ... *])- 在邮箱中搜索匹配的邮件。 * charset 可以是
None，在这种情况下，对服务器的请求中不会指定CHARSET。 IMAP 协议要求至少指定一个标准。服务器返回错误时将引发异常。如果使用enable()命令启用了UTF8=ACCEPTFunction，则 charset *必须为None。
- 在邮箱中搜索匹配的邮件。 * charset 可以是
例子：
# 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 *标志，则不允许修改邮箱。
- 选择一个邮箱。返回的数据是* mailbox 中的邮件计数(
-
IMAP4.send(* data *)- 将
data发送到远程服务器。您可以重写此方法。
- 将
用参数self，data引发auditing event imaplib.send。
-
IMAP4.setacl(邮箱，谁，什么)- 为* mailbox *设置
ACL。该方法是非标准方法，但Cyrus服务器支持该方法。
- 为* mailbox *设置
-
IMAP4.setannotation(* mailbox ， entry ， attribute * [，* ... *])- 为* mailbox *设置
ANNOTATIONs。该方法是非标准方法，但Cyrus服务器支持该方法。
- 为* mailbox *设置
-
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()
