poplib --- POP3 協(xié)議客戶(hù)端?

源代碼： Lib/poplib.py

本模塊定義了一個(gè) POP3 類(lèi)，該類(lèi)封裝了到 POP3 服務(wù)器的連接過(guò)程，并實(shí)現了 RFC 1939 中定義的協(xié)議。POP3 類(lèi)同時(shí)支持 RFC 1939 中最小的和可選的命令集。POP3 類(lèi)還支持在 RFC 2595 中引入的 STLS 命令，用于在已建立的連接上啟用加密通信。

本模塊額外提供一個(gè) POP3_SSL 類(lèi)，在連接到 POP3 服務(wù)器時(shí)，該類(lèi)為使用 SSL 作為底層協(xié)議層提供了支持。

注意，盡管 POP3 具有廣泛的支持，但它已經(jīng)過(guò)時(shí)。POP3 服務(wù)器的實(shí)現質(zhì)量差異很大，而且大多很糟糕。如果郵件服務(wù)器支持 IMAP，則最好使用 imaplib.IMAP4 類(lèi)，因為 IMAP 服務(wù)器一般實(shí)現得更好。

poplib 模塊提供了兩個(gè)類(lèi)：

class poplib.POP3(host, port=POP3_PORT[, timeout])?

本類(lèi)實(shí)現實(shí)際的 POP3 協(xié)議。實(shí)例初始化時(shí)，連接就會(huì )建立。如果省略 port，則使用標準 POP3 端口（110）?？蛇x參數 timeout 指定連接嘗試的超時(shí)時(shí)間（以秒為單位，如果未指定超時(shí)，將使用全局默認超時(shí)設置）。

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

引發(fā)一個(gè) 審計事件 poplib.putline，附帶參數 self, line。

在 3.9 版更改: 如果 timeout 參數設置為 0，創(chuàng )建非阻塞套接字時(shí)，它將引發(fā) ValueError 來(lái)阻止該操作。

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)?

一個(gè) POP3 的子類(lèi)，它使用經(jīng) SSL 加密的套接字連接到服務(wù)器。如果端口 port 未指定，則使用 995，它是標準的 POP3-over-SSL 端口。timeout 的作用與 POP3 構造函數中的相同。context 是一個(gè)可選的 ssl.SSLContext 對象，該對象可以將 SSL 配置選項、證書(shū)和私鑰打包放入一個(gè)單獨的（可以長(cháng)久存在的）結構中。請閱讀 安全考量 以獲取最佳實(shí)踐。

keyfile 和 certfile 是可以代替 context 的傳統方案，它們可以分別指向 PEM 格式的私鑰和證書(shū)鏈文件，用于進(jìn)行 SSL 連接。

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

引發(fā)一個(gè) 審計事件 poplib.putline，附帶參數 self, line。

在 3.2 版更改: 添加了 context 參數。

在 3.4 版更改: 本類(lèi)現在支持使用 ssl.SSLContext.check_hostname 和 服務(wù)器名稱(chēng)指示 （參閱 ssl.HAS_SNI）進(jìn)行主機名檢查。

3.6 版后已移除: keyfile 和 certfile 已棄用并轉而推薦 context。 請改用 ssl.SSLContext.load_cert_chain() 或讓 ssl.create_default_context() 為你選擇系統所信任的 CA 證書(shū)。

在 3.9 版更改: 如果 timeout 參數設置為 0，創(chuàng )建非阻塞套接字時(shí)，它將引發(fā) ValueError 來(lái)阻止該操作。

定義了一個(gè)異常，它是作為 poplib 模塊的屬性定義的：

exception poplib.error_proto?

此模塊的所有錯誤都將引發(fā)本異常（來(lái)自 socket 模塊的錯誤不會(huì )被捕獲）。異常的原因將以字符串的形式傳遞給構造函數。

參見(jiàn)

imaplib 模塊

標準的 Python IMAP 模塊。

有關(guān) Fetchmail 的常見(jiàn)問(wèn)題

fetchmail POP/IMAP 客戶(hù)端的“常見(jiàn)問(wèn)題”收集了 POP3 服務(wù)器之間的差異和 RFC 不兼容的信息，如果要編寫(xiě)基于 POP 協(xié)議的應用程序，這可能會(huì )很有用。

POP3 對象?

All POP3 commands are represented by methods of the same name, in lowercase; most return the response text sent by the server.

A POP3 instance has the following methods:

POP3.set_debuglevel(level)?

設置實(shí)例的調試級別，它控制著(zhù)調試信息的數量。默認值 0 不產(chǎn)生調試信息。值 1 產(chǎn)生中等數量的調試信息，通常每個(gè)請求產(chǎn)生一行。大于或等于 2 的值產(chǎn)生的調試信息最多，FTP 控制連接上發(fā)送和接收的每一行都將被記錄下來(lái)。

POP3.getwelcome()?

返回 POP3 服務(wù)器發(fā)送的問(wèn)候語(yǔ)字符串。

POP3.capa()?

查詢(xún)服務(wù)器支持的功能，這些功能在 RFC 2449 中有說(shuō)明。返回一個(gè) {'name': ['param'...]} 形式的字典。

3.4 新版功能.

POP3.user(username)?

發(fā)送 user 命令，返回的響應應該指示需要一個(gè)密碼。

POP3.pass_(password)?

發(fā)送密碼，響應包括郵件數和郵箱大小。注意：在調用 quit() 前，服務(wù)器上的郵箱都是鎖定的。

POP3.apop(user, secret)?

使用更安全的 APOP 身份驗證登錄到 POP3 服務(wù)器。

POP3.rpop(user)?

使用 RPOP 身份驗證（類(lèi)似于 Unix r-命令）登錄到 POP3 服務(wù)器。

POP3.stat()?

獲取郵箱狀態(tài)。結果為 2 個(gè)整數組成的元組：(message count, mailbox size)。

POP3.list([which])?

請求消息列表，結果的形式為 (response, ['mesg_num octets', ...], octets)。如果設置了 which，它表示需要列出的消息。

POP3.retr(which)?

檢索編號為 which 的整條消息，并設置其已讀標志位。結果的形式為 (response, ['line', ...], octets)。

POP3.dele(which)?

將編號為 which 的消息標記為待刪除。在多數服務(wù)器上，刪除操作直到 QUIT 才會(huì )實(shí)際執行（主要例外是 Eudora QPOP，它在斷開(kāi)連接時(shí)執行刪除，故意違反了 RFC）。

POP3.rset()?

移除郵箱中的所有待刪除標記。

POP3.noop()?

什么都不做?？梢杂糜诒３只顒?dòng)狀態(tài)。

POP3.quit()?

登出：提交更改，解除郵箱鎖定，斷開(kāi)連接。

POP3.top(which, howmuch)?

檢索編號為 which 的消息，范圍是消息頭加上消息頭往后數 howmuch 行。結果的形式為 (response, ['line', ...], octets)。

本方法使用 POP3 TOP 命令，不同于 RETR 命令，它不設置郵件的已讀標志位。不幸的是，TOP 在 RFC 中說(shuō)明不清晰，且在小眾的服務(wù)器軟件中往往不可用。信任并使用它之前，請先手動(dòng)對目標 POP3 服務(wù)器測試本方法。

POP3.uidl(which=None)?

返回消息摘要（唯一 ID）列表。如果指定了 which，那么結果將包含那條消息的唯一 ID，形式為 'response mesgnum uid，如果未指定，那么結果為列表 (response, ['mesgnum uid', ...], octets)。

POP3.utf8()?

嘗試切換至 UTF-8 模式。成功則返回服務(wù)器的響應，失敗則引發(fā) error_proto 異常。在 RFC 6856 中有說(shuō)明。

3.5 新版功能.

POP3.stls(context=None)?

在活動(dòng)連接上開(kāi)啟 TLS 會(huì )話(huà)，在 RFC 2595 中有說(shuō)明。僅在用戶(hù)身份驗證前允許這樣做。

context 參數是一個(gè) ssl.SSLContext 對象，該對象可以將 SSL 配置選項、證書(shū)和私鑰打包放入一個(gè)單獨的（可以長(cháng)久存在的）結構中。請閱讀 安全考量 以獲取最佳實(shí)踐。

此方法支持通過(guò) ssl.SSLContext.check_hostname 和 服務(wù)器名稱(chēng)指示 (參見(jiàn) ssl.HAS_SNI) 進(jìn)行主機名檢查。

3.4 新版功能.

POP3_SSL 實(shí)例沒(méi)有額外方法。該子類(lèi)的接口與其父類(lèi)的相同。

POP3 示例?

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

import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
    for j in M.retr(i+1)[1]:
        print(j)

模塊的最后有一段測試，其中包含的用法示例更加廣泛。