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í),連接就會(huì)建立。如果省略 port,則使用標(biāo)準(zhǔn) POP3 端口(110)??蛇x參數(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
對(duì)象,該對(duì)象可以將 SSL 配置選項(xiàng)、證書和私鑰打包放入一個(gè)單獨(dú)的(可以長久存在的)結(jié)構(gòu)中。請(qǐng)閱讀 安全考量 以獲取最佳實(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。 請(qǐng)改用
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ò)誤不會(huì)被捕獲)。異常的原因?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)用程序,這可能會(huì)很有用。
POP3 對(duì)象?
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)試級(jí)別,它控制著調(diào)試信息的數(shù)量。默認(rèn)值
0
不產(chǎn)生調(diào)試信息。值1
產(chǎn)生中等數(shù)量的調(diào)試信息,通常每個(gè)請(qǐng)求產(chǎn)生一行。大于或等于2
的值產(chǎn)生的調(diào)試信息最多,F(xiàn)TP 控制連接上發(fā)送和接收的每一行都將被記錄下來。
- POP3.getwelcome()?
返回 POP3 服務(wù)器發(fā)送的問候語字符串。
- 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])?
請(qǐng)求消息列表,結(jié)果的形式為
(response, ['mesg_num octets', ...], octets)
。如果設(shè)置了 which,它表示需要列出的消息。
- POP3.retr(which)?
檢索編號(hào)為 which 的整條消息,并設(shè)置其已讀標(biāo)志位。結(jié)果的形式為
(response, ['line', ...], octets)
。
- POP3.dele(which)?
將編號(hào)為 which 的消息標(biāo)記為待刪除。在多數(shù)服務(wù)器上,刪除操作直到 QUIT 才會(huì)實(shí)際執(zhí)行(主要例外是 Eudora QPOP,它在斷開連接時(shí)執(zhí)行刪除,故意違反了 RFC)。
- POP3.rset()?
移除郵箱中的所有待刪除標(biāo)記。
- POP3.noop()?
什么都不做??梢杂糜诒3只顒?dòng)狀態(tài)。
- POP3.quit()?
登出:提交更改,解除郵箱鎖定,斷開連接。
- POP3.top(which, howmuch)?
檢索編號(hào)為 which 的消息,范圍是消息頭加上消息頭往后數(shù) howmuch 行。結(jié)果的形式為
(response, ['line', ...], octets)
。本方法使用 POP3 TOP 命令,不同于 RETR 命令,它不設(shè)置郵件的已讀標(biāo)志位。不幸的是,TOP 在 RFC 中說明不清晰,且在小眾的服務(wù)器軟件中往往不可用。信任并使用它之前,請(qǐng)先手動(dòng)對(duì)目標(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)?
在活動(dòng)連接上開啟 TLS 會(huì)話,在 RFC 2595 中有說明。僅在用戶身份驗(yàn)證前允許這樣做。
context 參數(shù)是一個(gè)
ssl.SSLContext
對(duì)象,該對(duì)象可以將 SSL 配置選項(xiàng)、證書和私鑰打包放入一個(gè)單獨(dú)的(可以長久存在的)結(jié)構(gòu)中。請(qǐng)閱讀 安全考量 以獲取最佳實(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)
模塊的最后有一段測試,其中包含的用法示例更加廣泛。