ftplib --- FTP 協(xié)議客戶端?

FTP 對象?

一些方法可以按照兩種方式來使用：一種處理文本文件，另一種處理二進(jìn)制文件。方法名稱與相應(yīng)的命令相同，文本版中命令后面跟著 lines，二進(jìn)制版中命令后面跟著 binary。

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

FTP.set_debuglevel(level)?

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

FTP.connect(host='', port=0, timeout=None, source_address=None)?

連接到給定的主機(jī)和端口。默認(rèn)端口號由 FTP 協(xié)議規(guī)范規(guī)定，為 21。偶爾才需要指定其他端口號。每個實(shí)例只應(yīng)調(diào)用一次本函數(shù)，如果在創(chuàng)建實(shí)例時就傳入了 host，則根本不應(yīng)調(diào)用它。所有其他方法只能在建立連接后使用。可選參數(shù) timeout 指定連接嘗試的超時（以秒為單位）。如果沒有傳入 timeout，將使用全局默認(rèn)超時設(shè)置。source_address 是一個 2 元組 (host, port)，套接字在連接前綁定它，作為其源地址。

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

在 3.3 版更改: 添加了 source_address 參數(shù)。

FTP.getwelcome()?

返回服務(wù)器發(fā)送的歡迎消息，作為連接開始的回復(fù)。（該消息有時包含與用戶有關(guān)的免責(zé)聲明或幫助信息。）

FTP.login(user='anonymous', passwd='', acct='')?

以 user 的身份登錄。passwd 和 acct 是可選參數(shù)，默認(rèn)為空字符串。如果沒有指定 user，則默認(rèn)為 'anonymous'。如果 user 為 'anonymous'，那么默認(rèn)的 passwd 是 'anonymous@'。連接建立后，每個實(shí)例只應(yīng)調(diào)用一次本函數(shù)；如果在創(chuàng)建實(shí)例時傳入了 host 和 user，則完全不應(yīng)該調(diào)用本函數(shù)。在客戶端登錄后，才允許執(zhí)行大多數(shù) FTP 命令。acct 參數(shù)提供記賬信息 ("accounting information")；僅少數(shù)系統(tǒng)實(shí)現(xiàn)了該特性。

FTP.abort()?

中止正在進(jìn)行的文件傳輸。本方法并不總是有效，但值得一試。

FTP.sendcmd(cmd)?

將一條簡單的命令字符串發(fā)送到服務(wù)器，返回響應(yīng)的字符串。

引發(fā)一個 審計(jì)事件 ftplib.sendcmd，附帶參數(shù) self, cmd。

FTP.voidcmd(cmd)?

將一條簡單的命令字符串發(fā)送到服務(wù)器，并處理響應(yīng)內(nèi)容。如果收到的響應(yīng)代碼表示的是成功（代碼范圍 200--299），則不返回任何內(nèi)容。否則將引發(fā) error_reply。

引發(fā)一個 審計(jì)事件 ftplib.sendcmd，附帶參數(shù) self, cmd。

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)?

以二進(jìn)制傳輸模式下載文件。cmd 應(yīng)為恰當(dāng)?shù)?RETR 命令：'RETR 文件名'。callback 函數(shù)會在收到每個數(shù)據(jù)塊時調(diào)用，傳入的參數(shù)是表示數(shù)據(jù)塊的一個字節(jié)。為執(zhí)行實(shí)際傳輸，創(chuàng)建了底層套接字對象，可選參數(shù) blocksize 指定了讀取該對象時的最大塊大?。ㄟ@也是傳入 callback 的數(shù)據(jù)塊的最大大?。?。已經(jīng)選擇了合理的默認(rèn)值。rest 的含義與 transfercmd() 方法中的含義相同。

FTP.retrlines(cmd, callback=None)?

按照初始化時的 encoding 參數(shù)指定的編碼，獲取文件或目錄列表。cmd 應(yīng)是恰當(dāng)?shù)?RETR 命令（參閱 retrbinary()），也可以是諸如 LIST 或 NLST 之類的命令（通常就只是字符串 'LIST'）。LIST 獲取文件列表以及那些文件的信息。NLST 獲取文件名稱列表。callback 函數(shù)會在每一行都調(diào)用，參數(shù)就是包含一行的字符串，刪除了尾部的 CRLF。默認(rèn)的 callback 會把行打印到 sys.stdout。

FTP.set_pasv(val)?

如果 val 為 true，則打開“被動”模式，否則禁用被動模式。默認(rèn)下被動模式是打開的。

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)?

以二進(jìn)制傳輸模式存儲文件。 cmd 應(yīng)為恰當(dāng)?shù)?STOR 命令: "STOR filename"。fp 是一個 文件對象 (以二進(jìn)制模式打開)，將使用它的 read() 方法讀取它，用于提供要存儲的數(shù)據(jù)，直到遇到 EOF，讀取時的塊大小為 blocksize。 參數(shù) blocksize 的默認(rèn)值為 8192。 可選參數(shù) callback 是單參數(shù)函數(shù)，在每個數(shù)據(jù)塊發(fā)送后都會以該數(shù)據(jù)塊作為參數(shù)來調(diào)用它。rest 的含義與 transfercmd() 方法中的含義相同。

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

FTP.storlines(cmd, fp, callback=None)?

以文本行模式存儲文件。cmd 應(yīng)為恰當(dāng)?shù)?STOR 命令 (請參閱 storbinary())。 fp 是一個 文件對象 (以二進(jìn)制模式打開)，將使用它的 readline() 方法讀取它的每一行，用于提供要存儲的數(shù)據(jù)，直到遇到 EOF。 可選參數(shù) callback 是單參數(shù)函數(shù)，在每行發(fā)送后都會以該行作為參數(shù)來調(diào)用它。

FTP.transfercmd(cmd, rest=None)?

在 FTP 數(shù)據(jù)連接上開始傳輸數(shù)據(jù)。如果傳輸處于活動狀態(tài)，傳輸命令由 cmd 指定，需發(fā)送 EPRT 或 PORT 命令，然后接受連接 (accept)。如果服務(wù)器是被動服務(wù)器，需發(fā)送 EPSV 或 PASV 命令，連接到服務(wù)器 (connect)，然后啟動傳輸命令。兩種方式都將返回用于連接的套接字。

如果傳入了可選參數(shù) rest，則一條 REST 命令會被發(fā)送到服務(wù)器，并以 rest 作為參數(shù)。rest 通常表示請求文件中的字節(jié)偏移量，它告訴服務(wù)器重新開始發(fā)送文件的字節(jié)，從請求的偏移量處開始，跳過起始字節(jié)。但是請注意，transfercmd() 方法會將 rest 轉(zhuǎn)換為字符串，但是不檢查字符串的內(nèi)容，轉(zhuǎn)換用的編碼是在初始化時指定的 encoding 參數(shù)。如果服務(wù)器無法識別 REST 命令，將引發(fā) error_reply 異常。如果發(fā)生這種情況，只需不帶 rest 參數(shù)調(diào)用 transfercmd()。

FTP.ntransfercmd(cmd, rest=None)?

類似于 transfercmd()，但返回一個元組，包括數(shù)據(jù)連接和數(shù)據(jù)的預(yù)計(jì)大小。如果預(yù)計(jì)大小無法計(jì)算，則返回的預(yù)計(jì)大小為 None。cmd 和 rest 的含義與 transfercmd() 中的相同。

FTP.mlsd(path='', facts=[])?

使用 MLSD 命令以標(biāo)準(zhǔn)格式列出目錄內(nèi)容 (RFC 3659)。如果省略 path 則使用當(dāng)前目錄。facts 是字符串列表，表示所需的信息類型（如 ["type", "size", "perm"]）。返回一個生成器對象，每個在 path 中找到的文件都將在該對象中生成兩個元素的元組。第一個元素是文件名，第二個元素是該文件的 facts 的字典。該字典的內(nèi)容受 facts 參數(shù)限制，但不能保證服務(wù)器會返回所有請求的 facts。

3.3 新版功能.

FTP.nlst(argument[, ...])?

返回一個文件名列表，文件名由 NLST 命令返回?？蛇x參數(shù) argument 是待列出的目錄（默認(rèn)為當(dāng)前服務(wù)器目錄）?？梢允褂枚鄠€參數(shù)，將非標(biāo)準(zhǔn)選項(xiàng)傳遞給 NLST 命令。

備注

如果目標(biāo)服務(wù)器支持相關(guān)命令，那么 mlsd() 提供的 API 更好。

FTP.dir(argument[, ...])?

生成目錄列表，即 LIST 命令所返回的結(jié)果，并將其打印到標(biāo)準(zhǔn)輸出?？蛇x參數(shù) argument 是待列出的目錄（默認(rèn)為當(dāng)前服務(wù)器目錄）?？梢允褂枚鄠€參數(shù)，將非標(biāo)準(zhǔn)選項(xiàng)傳遞給 LIST 命令。如果最后一個參數(shù)是一個函數(shù)，它將被用作 callback 函數(shù)，與 retrlines() 中的相同，默認(rèn)將打印到 sys.stdout。本方法返回 None。

備注

如果目標(biāo)服務(wù)器支持相關(guān)命令，那么 mlsd() 提供的 API 更好。

FTP.rename(fromname, toname)?

將服務(wù)器上的文件 fromname 重命名為 toname。

FTP.delete(filename)?

將服務(wù)器上名為 filename 的文件刪除。如果刪除成功，返回響應(yīng)文本，如果刪除失敗，在權(quán)限錯誤時引發(fā) error_perm，在其他錯誤時引發(fā) error_reply。

FTP.cwd(pathname)?

設(shè)置服務(wù)器端的當(dāng)前目錄。

FTP.mkd(pathname)?

在服務(wù)器上創(chuàng)建一個新目錄。

FTP.pwd()?

返回服務(wù)器上當(dāng)前目錄的路徑。

FTP.rmd(dirname)?

將服務(wù)器上名為 dirname 的目錄刪除。

FTP.size(filename)?

請求服務(wù)器上名為 filename 的文件大小。成功后以整數(shù)返回文件大小，未成功則返回 None。注意，SIZE 不是標(biāo)準(zhǔn)命令，但通常許多服務(wù)器的實(shí)現(xiàn)都支持該命令。

FTP.quit()?

向服務(wù)器發(fā)送 QUIT 命令并關(guān)閉連接。 這是關(guān)閉一個連接的“禮貌”方式，但是如果服務(wù)器對 QUIT 命令的響應(yīng)帶有錯誤消息則這會引發(fā)一個異常。 這意味著對 close() 方法的調(diào)用，它將使得 FTP 實(shí)例對后繼調(diào)用無效（見下文）。

FTP.close()?

單方面關(guān)閉連接。 這不該被應(yīng)用于已經(jīng)關(guān)閉的連接，例如成功調(diào)用 quit() 之后的連接。 在此調(diào)用之后 FTP 實(shí)例不應(yīng)被繼續(xù)使用（在調(diào)用 close() 或 quit() 之后你不能通過再次發(fā)起調(diào)用 login() 方法重新打開連接）。

FTP_TLS 對象?

FTP_TLS 類繼承自 FTP，它定義了下述其他對象：

FTP_TLS.ssl_version?

欲采用的 SSL 版本（默認(rèn)為 ssl.PROTOCOL_SSLv23）。

FTP_TLS.auth()?

通過使用 TLS 或 SSL 來設(shè)置一個安全控制連接，具體取決于 ssl_version 屬性是如何設(shè)置的。

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

FTP_TLS.ccc()?

將控制通道回復(fù)為純文本。 這適用于發(fā)揮知道如何使用非安全 FTP 處理 NAT 而無需打開固定端口的防火墻的優(yōu)勢。

3.3 新版功能.

FTP_TLS.prot_p()?

設(shè)置加密數(shù)據(jù)連接。

FTP_TLS.prot_c()?

設(shè)置明文數(shù)據(jù)連接。