imaplib --- IMAP4 協(xié)議客戶端?

IMAP4 對(duì)象?

所有 IMAP4rev1 命令都表示為同名的方法，可以為大寫(xiě)或小寫(xiě)形式。

命令的所有參數(shù)都會(huì)被轉(zhuǎn)換為字符串，只有 AUTHENTICATE 例外，而 APPEND 的最后一個(gè)參數(shù)會(huì)被作為 IMAP4 字面值傳入。 如有必要 (字符串包含 IMAP4 協(xié)議中的敏感字符并且未加圓括號(hào)或雙引號(hào)) 每個(gè)字符串都會(huì)被轉(zhuǎn)碼。 但是，LOGIN 命令的 password 參數(shù)總是會(huì)被轉(zhuǎn)碼。 如果你想讓某個(gè)參數(shù)字符串免于被轉(zhuǎn)碼 (例如: STORE 的 flags 參數(shù)) 則要為該字符串加上圓括號(hào) (例如: r'(\Deleted)')。

每條命令均返回一個(gè)元組: (type, [data, ...]) 其中 type 通常為 'OK' 或 'NO'，而 data 為來(lái)自命令響應(yīng)的文本，或?yàn)閬?lái)自命令的規(guī)定結(jié)果。 每個(gè) data 均為 bytes 或者元組。 如果為元組，則其第一部分是響應(yīng)的標(biāo)頭，而第二部分將包含數(shù)據(jù) (例如: 'literal' 值)。

以下命令的 message_set 選項(xiàng)為指定要操作的一條或多條消息的字符串。 它可以是一個(gè)簡(jiǎn)單的消息編號(hào) ('1')，一段消息編號(hào)區(qū)間 ('2:4')，或者一組以逗號(hào)分隔的非連續(xù)區(qū)間 ('1:3,6:9')。 區(qū)間可以包含一個(gè)星號(hào)來(lái)表示無(wú)限的上界 ('3:*')。

IMAP4 實(shí)例具有下列方法:

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

將 message 添加到指定的郵箱。

IMAP4.authenticate(mechanism, authobject)?

認(rèn)證命令 --- 要求對(duì)響應(yīng)進(jìn)行處理。

mechanism 指明要使用哪種認(rèn)證機(jī)制 —— 它應(yīng)當(dāng)在實(shí)例變量 capabilities 中以 AUTH=mechanism 的形式出現(xiàn)。

authobject 必須是一個(gè)可調(diào)用對(duì)象:

data = authobject(response)

它將被調(diào)用以便處理服務(wù)器連續(xù)響應(yīng)；傳給它的 response 參數(shù)將為 bytes 類型。 它應(yīng)當(dāng)返回 base64 編碼的 bytes 數(shù)據(jù) 并發(fā)送給服務(wù)器。 或者在客戶端中止響應(yīng)時(shí)返回 None 并應(yīng)改為發(fā)送 *。

在 3.5 版更改: 字符串形式的用戶名和密碼現(xiàn)在會(huì)被執(zhí)行 utf-8 編碼而不限于 ASCII 字符。

IMAP4.check()?

為服務(wù)器上的郵箱設(shè)置檢查點(diǎn)。

IMAP4.close()?

關(guān)閉當(dāng)前選定的郵箱。 已刪除的消息會(huì)從可寫(xiě)郵箱中被移除。 在 LOGOUT 之前建議執(zhí)行此命令。

IMAP4.copy(message_set, new_mailbox)?

將 message_set 消息拷貝到 new_mailbox 的末尾。

IMAP4.create(mailbox)?

新建名為 mailbox 新郵箱。

IMAP4.delete(mailbox)?

刪除名為 mailbox 的舊郵箱。

IMAP4.deleteacl(mailbox, who)?

刪除郵箱上某人的 ACL (移除任何權(quán)限)。

IMAP4.enable(capability)?

啟用 capability (參見(jiàn) RFC 5161)。 大多數(shù)功能都不需要被啟用。 目前只有 UTF8=ACCEPT 功能受到支持 (參見(jiàn) RFC 6855)。

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

IMAP4.expunge()?

從選定的郵箱中永久移除被刪除的條目。 為每條被刪除的消息各生成一個(gè) EXPUNGE 響應(yīng)。 返回包含按接收時(shí)間排序的 EXPUNGE 消息編號(hào)的列表。

IMAP4.fetch(message_set, message_parts)?

獲取消息（的各個(gè)部分）。 message_parts 應(yīng)為加圓標(biāo)號(hào)的消息部分名稱字符串，例如: "(UID BODY[TEXT])"。 返回的數(shù)據(jù)是由消息部分封包和數(shù)據(jù)組成的元組。

IMAP4.getacl(mailbox)?

獲取 mailbox 的 ACL。 此方法是非標(biāo)準(zhǔn)的，但是被 Cyrus 服務(wù)器所支持。

IMAP4.getannotation(mailbox, entry, attribute)?

提取 mailbox 的特定 ANNOTATION。 此方法是非標(biāo)準(zhǔn)的，但是被 Cyrus 服務(wù)器所支持。

IMAP4.getquota(root)?

獲取 quota root 的資源使用和限制。 此方法是 rfc2087 定義的 IMAP4 QUOTA 擴(kuò)展的組成部分。

IMAP4.getquotaroot(mailbox)?

獲取指定 mailbox 的 quota roots 列表。 此方法是 rfc2087 定義的 IMAP4 QUOTA 擴(kuò)展的組成部分。

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

列出 directory 中與 pattern 相匹配的郵箱名稱。 directory 默認(rèn)為最高層級(jí)的電郵文件夾，而 pattern 默認(rèn)為匹配任何文本。 返回的數(shù)據(jù)包含 LIST 響應(yīng)列表。

IMAP4.login(user, password)?

使用純文本密碼標(biāo)識(shí)客戶。 password 將被轉(zhuǎn)碼。

IMAP4.login_cram_md5(user, password)?

在標(biāo)識(shí)用戶以保護(hù)密碼時(shí)強(qiáng)制使用 CRAM-MD5 認(rèn)證。 將只在服務(wù)器 CAPABILITY 響應(yīng)包含 AUTH=CRAM-MD5 階段時(shí)才有效。

IMAP4.logout()?

關(guān)閉對(duì)服務(wù)器的連接。 返回服務(wù)器 BYE 響應(yīng)。

在 3.8 版更改: 此方法不會(huì)再忽略靜默的任意異常。

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

列出 directory 中抽取的與 pattern 相匹配的郵箱。 directory 默認(rèn)為最高層級(jí)目錄而 pattern 默認(rèn)為匹配任何郵箱。 返回的數(shù)據(jù)為消息部分封包和數(shù)據(jù)的元組。

IMAP4.myrights(mailbox)?

顯示某個(gè)郵箱的本人 ACL (即本人在郵箱中的權(quán)限)。

IMAP4.namespace()?

返回 RFC 2342 中定義的 IMAP 命名空間。

IMAP4.noop()?

將 NOOP 發(fā)送給服務(wù)器。

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

打開(kāi)連接 host 上 port 的套接字。 可選的 timeout 形參指定連接嘗試的超時(shí)秒數(shù)。 如果 timeout 未給出或?yàn)?None，則會(huì)使用全局默認(rèn)的套接字超時(shí)。 另外請(qǐng)注意如果 timeout 形參被設(shè)為零，它將引發(fā) ValueError 以拒絕創(chuàng)建非阻塞套接字。 此方法會(huì)由 IMAP4 構(gòu)造器隱式地調(diào)用。 此方法所建立的連接對(duì)象將在 IMAP4.read(), IMAP4.readline(), IMAP4.send() 和 IMAP4.shutdown() 等方法中被使用。 你可以重載此方法。

引發(fā)一個(gè) 審計(jì)事件 imaplib.open，附帶參數(shù) self, host, port。

在 3.9 版更改: 加入 timeout 參數(shù)。

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

獲取消息被截?cái)嗟牟糠帧?返回的數(shù)據(jù)是由消息部分封包和數(shù)據(jù)組成的元組。

IMAP4.proxyauth(user)?

作為 user 進(jìn)行認(rèn)證。 允許經(jīng)權(quán)限的管理員通過(guò)代理進(jìn)入任意用戶的郵箱。

IMAP4.read(size)?

從遠(yuǎn)程服務(wù)器讀取 size 字節(jié)。 你可以重載此方法。

IMAP4.readline()?

從遠(yuǎn)程服務(wù)器讀取一行。 你可以重載此方法。

IMAP4.recent()?

提示服務(wù)器進(jìn)行更新。 如果沒(méi)有新消息則返回的數(shù)據(jù)為 None，否則為 RECENT 響應(yīng)的值。

IMAP4.rename(oldmailbox, newmailbox)?

將名為 oldmailbox 的郵箱重命名為 newmailbox。

IMAP4.response(code)?

如果收到響應(yīng) code 則返回其數(shù)據(jù)，否則返回 None。 返回給定的代碼，而不是普通的類型。

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

在郵箱中搜索匹配的消息。 charset 可以為 None，在這種情況下在發(fā)給服務(wù)器的請(qǐng)求中將不指定 CHARSET。 IMAP 協(xié)議要求至少指定一個(gè)標(biāo)準(zhǔn)；當(dāng)服務(wù)器返回錯(cuò)誤時(shí)將會(huì)引發(fā)異常。 charset 為 None 對(duì)應(yīng)使用 enable() 命令啟用了 UTF8=ACCEPT 功能的情況。

示例:

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

選擇一個(gè)郵箱。 返回的數(shù)據(jù)是 mailbox 中消息的數(shù)量 (EXISTS 響應(yīng))。 默認(rèn)的 mailbox 為 'INBOX'。 如果設(shè)置了 readonly 旗標(biāo)，則不允許修改該郵箱。

IMAP4.send(data)?

將 data 發(fā)送給遠(yuǎn)程服務(wù)器。 你可以重載此方法。

引發(fā)一個(gè) 審計(jì)事件 imaplib.send，附帶參數(shù) self, data。

IMAP4.setacl(mailbox, who, what)?

發(fā)送 mailbox 的 ACL。 此方法是非標(biāo)準(zhǔn)的，但是被 Cyrus 服務(wù)器所支持。

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

設(shè)置 mailbox 的 ANNOTATION。 此方法是非標(biāo)準(zhǔn)的，但是被 Cyrus 服務(wù)器所支持。

IMAP4.setquota(root, limits)?

設(shè)置 quota root 的資源限制為 limits。 此方法是 rfc2087 定義的 IMAP4 QUOTA 擴(kuò)展的組成部分。

IMAP4.shutdown()?

關(guān)閉在 open 中建立的連接。 此方法會(huì)由 IMAP4.logout() 隱式地調(diào)用。 你可以重載此方法。

IMAP4.socket()?

返回用于連接服務(wù)器的套接字實(shí)例。

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

sort 命令是 search 的變化形式，帶有結(jié)果排序語(yǔ)句。 返回的數(shù)據(jù)包含以空格分隔的匹配消息編號(hào)列表。

sort 命令在 search_criterion 參數(shù)之前還有兩個(gè)參數(shù)；一個(gè)帶圓括號(hào)的 sort_criteria 列表，和搜索的 charset。 請(qǐng)注意不同于 search，搜索的 charset 參數(shù)是強(qiáng)制性的。 還有一個(gè) uid sort 命令與 sort 對(duì)應(yīng)，如同 uid search 與 search 對(duì)應(yīng)一樣。 sort 命令首先在郵箱中搜索匹配給定搜索條件的消息，使用 charset 參數(shù)來(lái)解讀搜索條件中的字符串。 然后它將返回所匹配消息的編號(hào)。

這是一個(gè) IMAP4rev1 擴(kuò)展命令。

IMAP4.starttls(ssl_context=None)?

發(fā)送一個(gè) STARTTLS 命令。 ssl_context 參數(shù)是可選的并且應(yīng)為一個(gè) ssl.SSLContext 對(duì)象。 這將在 IMAP 連接上啟用加密。 請(qǐng)閱讀 安全考量 來(lái)了解最佳實(shí)踐。

3.2 新版功能.

在 3.4 版更改: 此方法現(xiàn)在支持使用 ssl.SSLContext.check_hostname 和 服務(wù)器名稱指示 (參見(jiàn) ssl.HAS_SNI) 進(jìn)行主機(jī)名檢查。

IMAP4.status(mailbox, names)?

針對(duì) mailbox 請(qǐng)求指定的狀態(tài)條件。

IMAP4.store(message_set, command, flag_list)?

改變郵箱中消息的旗標(biāo)處理。 command 由 RFC 2060 的 6.4.6 小節(jié)指明，應(yīng)為 "FLAGS", "+FLAGS" 或 "-FLAGS" 之一，并可選擇附帶 ".SILENT" 后綴。

例如，要在所有消息上設(shè)置刪除旗標(biāo):

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

備注

創(chuàng)建包含 ']' 的旗標(biāo) (例如: "[test]") 會(huì)違反 RFC 3501 (IMAP 協(xié)議)。 但是，imaplib 在歷史上曾經(jīng)允許創(chuàng)建這樣的標(biāo)簽，并且流行的 IMAP 服務(wù)器如 Gmail 都會(huì)接受并生成這樣的旗標(biāo)。 有些非 Python 程序也會(huì)創(chuàng)建這樣的旗標(biāo)。 雖然它違反 RFC 并且 IMAP 客戶端和服務(wù)器應(yīng)當(dāng)嚴(yán)格遵守規(guī)范，但是 imaplib 出于向下兼容的理由仍然繼續(xù)允許創(chuàng)建這樣的標(biāo)簽，并且在 Python 3.6 中會(huì)在其被服務(wù)器所發(fā)送時(shí)處理它們，因?yàn)檫@能提升實(shí)際的兼容性。

IMAP4.subscribe(mailbox)?

訂閱新郵箱。

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

thread 命令是 search 的變化形式，帶有針對(duì)結(jié)果的消息串句法。 返回的數(shù)據(jù)包含以空格分隔的消息串成員列表。

消息串成員由零個(gè)或多個(gè)消息編號(hào)組成，以空格分隔，標(biāo)示了連續(xù)的上下級(jí)關(guān)系。

thread 命令在 search_criterion 參數(shù)之前還有兩個(gè)參數(shù)；一個(gè) threading_algorithm，以及搜索使用的 charset。 請(qǐng)注意不同于 search，搜索使用的 charset 參數(shù)是強(qiáng)制性的。 還有一個(gè) uid thread 命令與 thread 對(duì)應(yīng)，如同 uid search 與 search 對(duì)應(yīng)一個(gè)。 thread 命令首先在郵箱中搜索匹配給定搜索條件的消息，使用 charset 參數(shù)來(lái)解讀搜索條件中的字符串。 然后它將按照指定的消息串算法返回所匹配的消息串。

這是一個(gè) IMAP4rev1 擴(kuò)展命令。

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

執(zhí)行 command arg 并附帶用 UID 所標(biāo)識(shí)的消息，而不是用消息編號(hào)。 返回與命令對(duì)應(yīng)的響應(yīng)。 必須至少提供一個(gè)參數(shù)；如果不提供任何參數(shù)，服務(wù)器將返回錯(cuò)誤并引發(fā)異常。

IMAP4.unsubscribe(mailbox)?

取消訂閱原有郵箱。

IMAP4.unselect()?

imaplib.IMAP4.unselect() 會(huì)釋放關(guān)聯(lián)到選定郵箱的服務(wù)器資源并將服務(wù)器返回到已認(rèn)證狀態(tài)。 此命令會(huì)執(zhí)行與 imaplib.IMAP4.close() 相同的動(dòng)作，區(qū)別在于它不會(huì)從當(dāng)前選定郵箱中永久性地移除消息。

3.9 新版功能.

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

允許服務(wù)器在 CAPABILITY 響應(yīng)中通知簡(jiǎn)單的擴(kuò)展命令。

在 IMAP4 的實(shí)例上定義了下列屬性:

IMAP4.PROTOCOL_VERSION?

在服務(wù)器的 CAPABILITY 響應(yīng)中最新的受支持協(xié)議。

IMAP4.debug?

控制調(diào)試輸出的整數(shù)值。 初始值會(huì)從模塊變量 Debug 中獲取。 大于三的值表示將追蹤每一條命令。

IMAP4.utf8_enabled?

通常為 False 的布爾值，但也可以被設(shè)為 True，如果成功地為 UTF8=ACCEPT 功能發(fā)送了 enable() 命令的話。

3.5 新版功能.

IMAP4 示例?

以下是一個(gè)最短示例（不帶錯(cuò)誤檢查），該示例將打開(kāi)郵箱，檢索并打印所有消息:

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