IMAP4 對象?

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

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

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

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

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

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

將 message 添加到指定的郵箱。

IMAP4.authenticate(mechanism, authobject)?

認證命令 --- 要求對響應進(jìn)行處理。

mechanism 指明要使用哪種認證機制 —— 它應當在實(shí)例變量 capabilities 中以 AUTH=mechanism 的形式出現。

authobject 必須是一個(gè)可調用對象:

data = authobject(response)

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

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

IMAP4.check()?

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

IMAP4.close()?

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

IMAP4.copy(message_set, new_mailbox)?

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

IMAP4.create(mailbox)?

新建名為 mailbox 新郵箱。

IMAP4.delete(mailbox)?

刪除名為 mailbox 的舊郵箱。

IMAP4.deleteacl(mailbox, who)?

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

IMAP4.enable(capability)?

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

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

IMAP4.expunge()?

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

IMAP4.fetch(message_set, message_parts)?

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

IMAP4.getacl(mailbox)?

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

IMAP4.getannotation(mailbox, entry, attribute)?

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

IMAP4.getquota(root)?

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

IMAP4.getquotaroot(mailbox)?

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

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

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

IMAP4.login(user, password)?

使用純文本密碼標識客戶(hù)。 password 將被轉碼。

IMAP4.login_cram_md5(user, password)?

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

IMAP4.logout()?

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

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

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

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

IMAP4.myrights(mailbox)?

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

IMAP4.namespace()?

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

IMAP4.noop()?

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

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

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

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

在 3.9 版更改: 加入 timeout 參數。

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

獲取消息被截斷的部分。 返回的數據是由消息部分封包和數據組成的元組。

IMAP4.proxyauth(user)?

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

IMAP4.read(size)?

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

IMAP4.readline()?

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

IMAP4.recent()?

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

IMAP4.rename(oldmailbox, newmailbox)?

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

IMAP4.response(code)?

如果收到響應 code 則返回其數據，否則返回 None。 返回給定的代碼，而不是普通的類(lèi)型。

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

在郵箱中搜索匹配的消息。 charset 可以為 None，在這種情況下在發(fā)給服務(wù)器的請求中將不指定 CHARSET。 IMAP 協(xié)議要求至少指定一個(gè)標準；當服務(wù)器返回錯誤時(shí)將會(huì )引發(fā)異常。 charset 為 None 對應使用 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è)郵箱。 返回的數據是 mailbox 中消息的數量 (EXISTS 響應)。 默認的 mailbox 為 'INBOX'。 如果設置了 readonly 旗標，則不允許修改該郵箱。

IMAP4.send(data)?

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

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

IMAP4.setacl(mailbox, who, what)?

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

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

設置 mailbox 的 ANNOTATION。 此方法是非標準的，但是被 Cyrus 服務(wù)器所支持。

IMAP4.setquota(root, limits)?

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

IMAP4.shutdown()?

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

IMAP4.socket()?

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

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

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

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

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

IMAP4.starttls(ssl_context=None)?

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

3.2 新版功能.

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

IMAP4.status(mailbox, names)?

針對 mailbox 請求指定的狀態(tài)條件。

IMAP4.store(message_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()

備注

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

IMAP4.subscribe(mailbox)?

訂閱新郵箱。

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

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

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

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

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

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

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

IMAP4.unsubscribe(mailbox)?

取消訂閱原有郵箱。

IMAP4.unselect()?

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

3.9 新版功能.

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

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

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

IMAP4.PROTOCOL_VERSION?

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

IMAP4.debug?

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

IMAP4.utf8_enabled?

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

3.5 新版功能.

IMAP4 示例?

以下是一個(gè)最短示例（不帶錯誤檢查），該示例將打開(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()