您的位置:  首页 » Python » – IMAP4协议客户端 – 互联网协议和支持(Python教程)(参考资料)

imaplibIMAP4协议客户端

源代码: Lib / imaplib.py


这个模块定义了三个类IMAP4, IMAP4_SSLIMAP4_stream,它封装了与IMAP4服务器的连接,并实现了 RFC 2060 中定义的IMAP4rev1客户端协议的大部分子集。它向后兼容IMAP4( RFC 1730 )服务器,但是IMAP4不支持STATUS命令.

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

class imaplib.IMAP4host=””, port=IMAP4_PORT

该类实现了实际的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声明的支持.

三个异常被定义为IMAP4 class的属性:

exception IMAP4.error

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

exception IMAP4.abort

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

exception IMAP4.readonly

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

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

class imaplib.IMAP4_SSLhost=””, port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None

这是从IMAP4派生的子类,它通过SSL加密套接字连接(要使用此类,您需要一个使用SSL支持编译的套接字模块)。如果没有指定host""(本地主机)被使用。如果省略port,则使用标准的IMAP4-over-SSL端口(993).ssl_contextssl.SSLContext允许将SLSL配置选项,证书和私钥捆绑到单个(可能是长期存在的)结构中的对象。请阅读安全考虑最好的做法.

keyfilecertfilessl_context的遗留替代品 – 他们可以指向SSL连接的PEM格式的私钥和证书链文件。注意keyfile/certfile参数与具有互补性ssl_context, 一个 ValueError被提升keyfile/certfile随提供ssl_context.

改版3.3:ssl_context参数添加了

版本3.4更改:该类现在支持使用ssl.SSLContext.check_hostnameServer Name Indication进行主机名检查(参见ssl.HAS_SNI).

自版本3.6以后不推荐使用:keyfilecertfile被弃用赞成ssl_context。请改用ssl.SSLContext.load_cert_chain(),或者让ssl.create_default_context()为你选择系统的可信CAcertificates

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

class imaplib.IMAP4_streamcommand

这是一个子类源自IMAP4连接到stdin/stdout通过传递commandsubprocess.Popen().

创建的文件描述符定义了以下实用函数:

imaplib.Internaldate2tupledatestr

解析IMAP4 INTERNALDATE字符串并返回相应的localtime。返回值为time.struct_time元组None如果字符串格式错误.

imaplib.Int2AP (num)

将整数转换为一个字符串表示使用集合中的字符[A .. P].

imaplib.ParseFlags(flagstr)

转换IMAP4 FLAGS响应一个元组个别旗帜

imaplib.Time2Internaldate// (date_time)

转换date_time到IMAP4 INTERNALDATE表示。返回值是一个字符串form:"DD-Mmm-YYYY HH:MM:SS+HHMM"(包括双引号)。date_time参数可以是一个数字(int或float),表示自纪元以来的秒数(由time.time()返回),一个代表time.struct_time的本地时间实例的9元组(由time.localtime()),一个知道datetime.datetime的实例,或一个双引号的字符串。在最后一种情况下,假设格式正确.

注意IMAP4消息号随邮箱的变化而变化;特别是在EXPUNGE命令执行删除剩余的消息已编号。因此,建议使用UID代替UID命令.

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

参见

描述协议的文档,以及实现它的服务器的来源和二进制文件,都可以在华盛顿大学找到IMAPInformation Center(https://www.washington.edu/imap/)

IMAP4对象

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

命令的所有参数都转换为字符串,除了AUTHENTICATE,以及APPEND它作为IMAP4文字传递。如果必要(字符串包含IMAP4协议敏感字符,并且没有括号或双引号),则引用每个字符串。但是,passwordLOGIN命令总是引用。如果你想避免引用参数字符串(例如:flags参数STORE)然后将字符串括在括号中(例如:r"(\Deleted)").

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

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

一个IMAP4实例有以下几种方法:

IMAP4.appendmailbox, flags, date_time, message

message附加到命名邮箱.

IMAP4.authenticate (mechanism, authobject)

Authenticate命令 – 需要响应处理.

mechanism指定要使用的认证机制 – 它应该出现在实例变量capabilities中,形式为AUTH=mechanism.

authobject必须是可调用的对象:

data = authobject(response)

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

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

IMAP4.check()

服务器上的检查点邮箱

IMAP4.close/(

关闭当前选中的邮箱。删除的邮件将从writablemailbox中删除。这是LOGOUT.

IMAP4.copymessage_set, new_mailbox)之前的推荐命令

message_set消息复制到new_mailbox.

IMAP4.createmailbox的末尾)

创建名为mailbox.

IMAP4.deletemailbox)的新邮箱

删除名为mailbox.

IMAP4.deleteaclmailbox, who)的旧邮箱

删除为邮箱上的人设置的ACL(删除任何权限)

IMAP4.enable (capability)

启用capability(见RFC 5161 )。大多数功能都不需要被启用。目前只支持UTF8=ACCEPT功能(参见 RFC 6855 ).

版本3.5中的新功能: enable()方法本身,和 RFC 6855 support.

IMAP4.expunge ()

永久删除所选邮箱中已删除的项目。生成EXPUNGE每个已删除邮件的响应。返回的数据包含EXPUNGE消息号码按顺序收到.

IMAP4.fetchmessage_set, message_parts

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

IMAP4.getacl(mailbox)

获取ACL s mailbox。该方法是非标准的,但是由Cyrus服务器支持

IMAP4.getannotation// (mailbox, entry, attribute)

检索指定的ANNOTATION smailbox。该方法是非标准的,但是由Cyrus server.

IMAP4.getquotaroot

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

IMAP4.getquotarootmailbox

获取quota roots为了命名mailbox。此方法是rfc 2087中定义的IMAP4 QUOTA扩展的一部分.

IMAP4.list ( [directory [, pattern]]

列出directory中的邮箱名称匹配pattern. directory默认为顶级邮件文件夹,而pattern默认为匹配任何内容。Returneddata包含LIST的列表

IMAP4.login//(user, password)

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

IMAP4.login_cram_md5user, password

强行使用CRAM-MD5识别客户端以保护密码时的身份验证。只有服务器CAPABILITY回复包括词语AUTH=CRAM-MD5.

IMAP4.logout

关闭与服务器的连接。返回服务器BYE response.

IMAP4.lsub (directory=””””, pattern=”*”)

列出目录匹配模式中的订阅邮箱名称。directory默认为顶级目录和pattern默认匹配任何邮箱。返回的数据是邮件部分信封和数据的元组.

IMAP4.myrights (mailbox)

显示我的邮箱的ACL(即我拥有的权利)在邮箱上。)

IMAP4.namespace

返回RFC 2342 .

IMAP4.noop

发送NOOP到服务器

IMAP4.openhost, port

打开插座porthost。这个方法被含蓄地调用IMAP4构造函数。由thismethod建立的连接对象将用于IMAP4.read(), IMAP4.readline(),IMAP4.send()IMAP4.shutdown()方法。你可以改写这种方法.

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

获取消息的截断部分。返回的数据是消息partenvelope和data的元组.

IMAP4.proxyauth (user)

认证为user。允许授权管理员代理任何用户的邮箱.

IMAP4.read(size)

从远程服务器读取size字节。您可以覆盖此方法.

IMAP4.readline ( )

从远程服务器读取一行。您可以覆盖此方法.

IMAP4.recent()

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

IMAP4.rename//(oldmailbox, newmailbox

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

IMAP4.responsecode

如果收到回复数据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.selectmailbox=”INBOX”, readonly=False

选择一个邮箱。返回的数据是mailboxEXISTS响应)。默认mailbox"INBOX"。如果设置了readonly标志,则不允许修改邮箱.

IMAP4.send (data)

发送到data到遥控器服务器。您可以覆盖此方法.

IMAP4.setacl (mailbox, who, what

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

IMAP4.setannotationmailbox, entry, attribute [, ])

ANNOTATION设置mailbox s。该方法是非标准的,但由Cyrus server.

IMAP4.setquota(root, limits)

设置quota root的资源支持limits。这个方法是rfc2087中定义的IMAP4QUOTA扩展的一部分.

IMAP4.shutdown)

open中建立的关闭连接。这个方法由IMAP4.logout()隐式调用。您可以覆盖此方法.

IMAP4.socket ()

Returns socket实例用于连接服务器.

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

sort命令是search的变种,具有结果的排序语义。返回的数据包含一个空格分隔的匹配messagenumbers列表.

Sort在search_criterion参数之前有两个参数;sort_criteria的隐藏列表,以及搜索charset。注意,不喜欢search,搜索charset参数是强制性的。还有uid sort命令对应sort uid search对应的方式searchsort命令首先使用charset参数在邮箱中搜索与给定搜索条件匹配的消息,以解释搜索条件中的字符串。然后返回匹配消息的数量.

这是个 IMAP4rev1扩展命令.

IMAP4.starttlsssl_context=None

寄一个 STARTTLS命令。ssl_context论证是选择,应该是ssl.SSLContext宾语。这将启用IMAP连接的加密。请阅读安全考虑最好的做法.

新版本3.2.

更改版本3.4:该方法现在用ssl.SSLContext.check_hostnameServer Name Indication支持主机名检查(见ssl.HAS_SNI).

IMAP4.status(mailbox, names)

请求mailbox.

IMAP4.storemessage_set, command, flag_list

的命名状态条件更改邮箱中邮件的标记处置。command 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()

注意

创建包含’]’的标志(例如:“[test]”)违反 RFC 3501 (IMAP协议)。但是,imaplib历来允许创建此类标记,而流行的IMAP服务器(如Gmail)会接受并生成此类标记。还有非Python程序可以创建这样的标记。虽然它是一个RFC违规并且IMAP客户端和服务器应该是严格的,但imaplib仍然允许为了向后兼容性原因创建这些标签,并且从Python 3.6开始,如果它们是从服务器发送的,则处理它们,因为这改善了现实世界兼容性。

IMAP4.subscribemailbox

订阅新邮箱.

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

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

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

search_criterion参数之前有两个参数;一个threading_algorithm和搜索charset。请注意,与search不同,搜索charset参数是必需的。还有uid thread命令对应thread uidsearch对应searchthread命令首先使用charsetargument在邮箱中搜索与给定搜索条件匹配的邮件,以便在搜索条件中解释字符串。然后根据指定的线程算法返回匹配的消息.

这是IMAP4rev1扩展命令.

IMAP4.uid (command, arg [, ])

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

IMAP4.unsubscribemailbox

取消订阅旧邮箱.

IMAP4.xatom (name [, ])

允许服务器通知的简单扩展命令CAPABILITY response.

IMAP4

IMAP4.PROTOCOL_VERSION

中最新支持的协议CAPABILITY来自服务器的回复.

IMAP4.debug

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

IMAP4.utf8_enabled

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

新版本3.5.

IMAP4示例

这是一个最小的例子(没有错误检查)打开邮箱并检索并打印所有邮件:

import getpass, imaplibM = 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()

评论被关闭。