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í)踐。

keyfilecertfile 是可以代替 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 版后已移除: keyfilecertfile 已棄用并轉(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.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])?

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

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