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

源代碼： Lib/poplib.py

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

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

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

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

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

本類實(shí)現(xiàn)實(shí)際的 POP3 協(xié)議。實(shí)例初始化時(shí)，連接就會建立。如果省略 port，則使用標(biāo)準(zhǔn) POP3 端口（110）。可選參數(shù) timeout 指定連接嘗試的超時(shí)時(shí)間（以秒為單位，如果未指定超時(shí)，將使用全局默認(rèn)超時(shí)設(shè)置）。

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

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

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

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

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

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

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

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

在 3.2 版更改: 添加了 context 參數(shù)。

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

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

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

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

exception poplib.error_proto?

此模塊的所有錯(cuò)誤都將引發(fā)本異常（來自 socket 模塊的錯(cuò)誤不會被捕獲）。異常的原因?qū)⒁宰址男问絺鬟f給構(gòu)造函數(shù)。

參見

imaplib 模塊

標(biāo)準(zhǔn)的 Python IMAP 模塊。

有關(guān) Fetchmail 的常見問題

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

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è)置實(shí)例的調(diào)試級別，它控制著調(diào)試信息的數(shù)量。默認(rèn)值 0 不產(chǎn)生調(diào)試信息。值 1 產(chǎn)生中等數(shù)量的調(diào)試信息，通常每個(gè)請求產(chǎn)生一行。大于或等于 2 的值產(chǎn)生的調(diào)試信息最多，F(xiàn)TP 控制連接上發(fā)送和接收的每一行都將被記錄下來。

POP3.getwelcome()?

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

POP3.capa()?

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

3.4 新版功能.

POP3.user(username)?

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

POP3.pass_(password)?

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

POP3.apop(user, secret)?

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

POP3.rpop(user)?

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

POP3.stat()?

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

POP3.list([which])?

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

POP3.retr(which)?

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

POP3.dele(which)?

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

POP3.rset()?

移除郵箱中的所有待刪除標(biāo)記。

POP3.noop()?

什么都不做?？梢杂糜诒３只顒訝顟B(tài)。

POP3.quit()?

登出：提交更改，解除郵箱鎖定，斷開連接。

POP3.top(which, howmuch)?

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

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

POP3.uidl(which=None)?

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

POP3.utf8()?

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

3.5 新版功能.

POP3.stls(context=None)?

在活動連接上開啟 TLS 會話，在 RFC 2595 中有說明。僅在用戶身份驗(yàn)證前允許這樣做。

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

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

3.4 新版功能.

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

POP3 示例?

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

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)

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