imaplib

源代码: Lib / imaplib.py

该模块定义了三个类,IMAP4IMAP4_SSLIMAP4_stream,其中封装到IMAP4服务器的连接,并执行如在所限定的IMAP4rev1客户端协议的一个大的子集RFC 2060。它向后兼容IMAP4(RFC 1730)服务器,但请注意,该STATUS命令在IMAP4中不受支持。

imaplib模块提供了三个类,IMAP4它是基类:

class imaplib.IMAP4([host[, port]])

该类实现了实际的IMAP4协议。创建连接并在实例初始化时确定协议版本(IMAP4或IMAP4rev1)。如果主机没有指定,''(本地主机)被使用。如果省略端口,则使用标准IMAP4端口(143)。

三个例外被定义为IMAP4该类的属性:

exception IMAP4.error

任何错误都会引发异常。异常的原因以字符串形式传递给构造函数。

exception IMAP4.abort

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

exception IMAP4.readonly

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

还有一个安全连接的子类:

class imaplib.IMAP4_SSL([host[, port[, keyfile[, certfile]]]])

这是IMAP4通过SSL加密套接字连接而来的子类(要使用此类,您需要一个使用SSL支持编译的套接字模块)。如果主机没有指定,''(本地主机)被使用。如果省略端口,则使用标准的IMAP4-SSL端口(993)。keyfilecertfile也是可选的 - 它们可以包含用于SSL连接的PEM格式的私钥和证书链文件。

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

class imaplib.IMAP4_stream(command)

这是衍生自一个子类IMAP4,其连接到stdin/stdout通过使创造的文件描述符命令os.popen2()

2.3版本的新功能。

定义了以下效用函数:

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参数可以是数(整数或浮点数)表示纪元以来秒(由返回的time.time()),代表(如通过返回本地时间9元组time.localtime()),或一个双引号字符串。在最后一种情况下,假定它已经是正确的格式。

请注意,IMAP4邮件号码随邮箱更改而变化; 特别是在EXPUNGE命令执行删除操作后,剩余的消息将被重新编号。因此,使用UID命令来代替使用UID是非常明智的。

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

1. IMAP4对象

所有IMAP4rev1命令都由相同名称的方法表示,无论是大写还是小写。

所有命令的参数都被转换为字符串,除了AUTHENTICATE,以及最后一个参数APPEND作为IMAP4文字传递。如有必要(该字符串包含IMAP4协议敏感字符,不包含括号或双引号),每个字符串都被引用。但是,该命令的密码参数LOGIN始终是引用的。如果你想避免引用一个参数字符串(例如:flags参数STORE),那么将该字符串括在括号内(例如:)r'(\Deleted)'

每个命令都会返回一个元组:(type, [data, ...])其中type通常是'OK''NO',而data是来自命令响应的文本,或者来自命令的命令结果。每个数据都是一个字符串或一个元组。如果是一个元组,那么第一部分是响应的头部,第二部分包含数据(即'literal'值)。

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

一个IMAP4实例有以下方法:

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

邮件追加到指定的邮箱。

IMAP4.authenticate(mechanism, authobject)

验证命令 - 需要响应处理。

机制指定要使用哪种认证机制 - 它应该出现在capabilities表单中的实例变量中AUTH=mechanism

authobject必须是可调用的对象:

data = authobject(response)

它将被调用来处理服务器连续响应。它应该返回data,将被编码并发送到服务器。None如果*应该发送客户端中止响应,它应该返回。

IMAP4.check()

服务器上的检查点邮箱。

IMAP4.close()

关闭当前选定的邮箱。已删除的邮件将从可写邮箱中删除。这是以前推荐的命令LOGOUT

IMAP4.copy(message_set, new_mailbox)

message_set消息复制到new_mailbox的末尾

IMAP4.create(mailbox)

创建名为mailbox的邮箱

IMAP4.delete(mailbox)

删除旧邮箱命名邮箱

IMAP4.deleteacl(mailbox, who)

删除为邮箱上的用户设置的ACL(删除所有权限)。

2.4版本中的新功能。

IMAP4.expunge()

永久删除所选邮箱中的已删除邮件。EXPUNGE为每个已删除的消息生成一个响应。返回的数据包含EXPUNGE收到订单的消息编号列表。

IMAP4.fetch(message_set, message_parts)

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

IMAP4.getacl(mailbox)

获取邮箱ACLs 。该方法是非标准的,但由服务器支持。Cyrus

IMAP4.getannotation(mailbox, entry, attribute)

检索邮箱的指定ANNOTATIONs 。该方法是非标准的,但由服务器支持。Cyrus

2.5版本中的新功能。

IMAP4.getquota(root)

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

2.3版本的新功能。

IMAP4.getquotaroot(mailbox)

获取quota roots指定邮箱的列表。此方法是rfc2087中定义的IMAP4 QUOTA扩展的一部分。

2.3版本的新功能。

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

列出目录匹配模式中的邮箱名称。目录默认为顶层邮件文件夹,并且模式默认为匹配任何内容。返回的数据包含LIST响应列表。

IMAP4.login(user, password)

使用明文密码识别客户端。该密码将被引用。

IMAP4.login_cram_md5(user, password)

CRAM-MD5识别客户端以保护密码时强制使用身份验证。只有当服务器CAPABILITY响应包含该短语时才会起作用AUTH=CRAM-MD5

2.3版本的新功能。

IMAP4.logout()

关闭连接到服务器。返回服务器BYE响应。

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

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

IMAP4.myrights(mailbox)

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

2.4版本中的新功能。

IMAP4.namespace()

返回RFC2342中定义的IMAP名称空间。

2.3版本的新功能。

IMAP4.noop()

发送NOOP到服务器。

IMAP4.open(host, port)

主机上打开套接字到端口。该方法由构造函数隐式调用。通过这种方法建立的连接对象将在被使用,,,和方法。您可以重写此方法。IMAP4IMAP4.read()IMAP4.readline()IMAP4.send()IMAP4.shutdown()

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

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

IMAP4.proxyauth(user)

假设用户身份验证。允许授权管理员代理进入任何用户的邮箱。

2.3版本的新功能。

IMAP4.read(size)

从远程服务器读取大小字节。您可以重写此方法。

IMAP4.readline()

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

IMAP4.recent()

提示服务器进行更新。None如果没有新消息,则返回数据,否则返回值RECENT

IMAP4.rename(oldmailbox, newmailbox)

将名为oldmailbox的邮箱重命名为newmailbox

IMAP4.response(code)

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

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

搜索邮箱中的匹配邮件。字符集可能是None,在这种情况下,CHARSET将在服务器的请求中指定no 。IMAP协议要求至少指定一个标准; 服务器返回错误时将引发异常。

例:

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select([mailbox[, readonly]])

选择一个邮箱。返回的数据是邮箱中的邮件数(EXISTS响应)。默认邮箱'INBOX'。如果设置了只读标志,则不允许对邮箱进行修改。

IMAP4.send(data)

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

IMAP4.setacl(mailbox, who, what)

设置ACL邮箱。该方法是非标准的,但由Cyrus服务器支持。

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

设置ANNOTATIONS代表邮箱。该方法是非标准的,但由Cyrus服务器支持。

2.5版本中的新功能。

IMAP4.setquota(root, limits)

设置quota 根目录的资源限制。此方法是rfc2087中定义的IMAP4 QUOTA扩展的一部分。

2.3版本的新功能。

IMAP4.shutdown()

关闭连接建立在open。这个方法被隐含地称为IMAP4.logout()。您可以重写此方法。

IMAP4.socket()

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

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

sort命令是search对结果进行排序语义的变体。返回的数据包含空格分隔的匹配消息编号列表。

Sort在search_criterion参数前有两个参数; sort_criteria的加括号列表和搜索字符集。请注意,不同的是search,搜索字符集参数是强制性的。还有一个uid sort对应于命令sort的方式uid search对应search。该sort命令首先使用charset参数在邮箱中搜索与给定搜索条件相匹配的邮件,以便在搜索条件中解释字符串。然后它返回匹配消息的数量。

这是一个IMAP4rev1扩展命令。

IMAP4.status(mailbox, names)

请求邮箱的命名状态条件。

IMAP4.store(message_set, command, flag_list)

更改标记邮箱中邮件的处置。命令RFC 2060第6.4.6节规定为“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(mailbox)

订阅新邮箱。

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

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

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

线程在search_criterion参数前有两个参数; 一个threading_algorithm,以及搜索字符集。请注意,不同的是search,搜索字符集参数是强制性的。还有一个uid thread对应于命令thread的方式uid search对应search。该thread命令首先使用charset参数在邮箱中搜索与给定搜索条件相匹配的邮件,以便在搜索条件中解释字符串。然后它根据指定的线程算法返回匹配的消息。

这是一个IMAP4rev1扩展命令。

2.4版本中的新功能。

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

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

IMAP4.unsubscribe(mailbox)

取消订阅旧邮箱。

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

作为CAPABILITY回应,允许服务器通知简单的扩展命令。

实例IMAP4_SSL只有一个额外的方法:

IMAP4_SSL.ssl()

返回用于与服务器进行安全连接的SSLObject实例。

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

IMAP4.PROTOCOL_VERSION

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

IMAP4.debug

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

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

扫码关注云+社区

领取腾讯云代金券