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

源代碼： Lib/ftplib.py

本模塊定義了 FTP 類(lèi)和一些相關(guān)項目。 FTP 類(lèi)實(shí)現了 FTP 協(xié)議的客戶(hù)端。 你可以用這個(gè)類(lèi)來(lái)編寫(xiě)執行各種自動(dòng)化 FTP 任務(wù)的 Python 程序，例如鏡像其他 FTP 服務(wù)器等。 它還被 urllib.request 模塊用來(lái)處理使用 FTP 的 URL。 有關(guān) FTP (文件傳輸協(xié)議) 的更多信息，請參閱 RFC 959。

默認編碼為 UTF-8，遵循 RFC 2640。

以下是使用 ftplib 模塊的會(huì )話(huà)示例:

>>>
>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
>>> ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()
'221 Goodbye.'

這個(gè)模塊定義了以下內容：

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')?

返回一個(gè) FTP 類(lèi)的新實(shí)例。當傳入 host 時(shí)，將調用 connect(host) 方法。當傳入 user 時(shí)，將額外調用 login(user, passwd, acct) 方法（其中 passwd 和 acct 若沒(méi)有傳入則默認為空字符串）?？蛇x參數 timeout 指定阻塞操作（如連接嘗試）的超時(shí)（以秒為單位，如果未指定超時(shí)，將使用全局默認超時(shí)設置）。source_address 是一個(gè) 2 元組 (host, port)，套接字在連接前綁定它，作為其源地址。encoding 參數指定目錄和文件名的編碼。

FTP 類(lèi)支持 with 語(yǔ)句，例如：

>>>
>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
... 
'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
>>>

在 3.2 版更改: 添加了對 with 語(yǔ)句的支持。

在 3.3 版更改: 添加了 source_address 參數。

在 3.9 版更改: 如果 timeout 參數設置為 0，創(chuàng )建非阻塞套接字時(shí)，它將引發(fā) ValueError 來(lái)阻止該操作。添加了 encoding 參數，且為了遵循 RFC 2640，該參數默認值從 Latin-1 改為了 UTF-8。

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')?

一個(gè) FTP 的子類(lèi)，它為 FTP 添加了 TLS 支持，如 RFC 4217 所述。它將像通常一樣連接到 21 端口，暗中保護在身份驗證前的 FTP 控制連接。而保護數據連接需要用戶(hù)明確調用 prot_p() 方法。context 是一個(gè) ssl.SSLContext 對象，該對象可以將 SSL 配置選項、證書(shū)和私鑰打包放入一個(gè)單獨的（可以長(cháng)久存在的）結構中。請閱讀 安全考量 以獲取最佳實(shí)踐。

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

3.2 新版功能.

在 3.3 版更改: 添加了 source_address 參數。

在 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)阻止該操作。添加了 encoding 參數，且為了遵循 RFC 2640，該參數默認值從 Latin-1 改為了 UTF-8。

以下是使用 FTP_TLS 類(lèi)的會(huì )話(huà)示例:

>>>
>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']
exception ftplib.error_reply?

從服務(wù)器收到意外答復時(shí)，將引發(fā)本異常。

exception ftplib.error_temp?

收到表示臨時(shí)錯誤的錯誤代碼（響應代碼在 400--499 范圍內）時(shí)，將引發(fā)本異常。

exception ftplib.error_perm?

收到表示永久性錯誤的錯誤代碼（響應代碼在 500--599 范圍內）時(shí)，將引發(fā)本異常。

exception ftplib.error_proto?

從服務(wù)器收到不符合 FTP 響應規范的答復，比如以數字 1--5 開(kāi)頭時(shí)，將引發(fā)本異常。

ftplib.all_errors?

所有異常的集合（一個(gè)元組），由于 FTP 連接出現問(wèn)題（并非調用者的編碼錯誤），FTP 實(shí)例的方法可能會(huì )引發(fā)這些異常。該集合包括上面列出的四個(gè)異常以及 OSError 和 EOFError。

參見(jiàn)

netrc 模塊

.netrc 文件格式解析器。FTP 客戶(hù)端在響應用戶(hù)之前，通常使用 .netrc 文件來(lái)加載用戶(hù)認證信息。

FTP 對象?

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

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

FTP.set_debuglevel(level)?

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

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

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

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

在 3.3 版更改: 添加了 source_address 參數。

FTP.getwelcome()?

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

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

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

FTP.abort()?

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

FTP.sendcmd(cmd)?

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

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

FTP.voidcmd(cmd)?

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

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

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

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

FTP.retrlines(cmd, callback=None)?

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

FTP.set_pasv(val)?

如果 val 為 true，則打開(kāi)“被動(dòng)”模式，否則禁用被動(dòng)模式。默認下被動(dòng)模式是打開(kāi)的。

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

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

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

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

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

FTP.transfercmd(cmd, rest=None)?

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

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

FTP.ntransfercmd(cmd, rest=None)?

類(lèi)似于 transfercmd()，但返回一個(gè)元組，包括數據連接和數據的預計大小。如果預計大小無(wú)法計算，則返回的預計大小為 None。cmd 和 rest 的含義與 transfercmd() 中的相同。

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

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

3.3 新版功能.

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

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

備注

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

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

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

備注

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

FTP.rename(fromname, toname)?

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

FTP.delete(filename)?

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

FTP.cwd(pathname)?

設置服務(wù)器端的當前目錄。

FTP.mkd(pathname)?

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

FTP.pwd()?

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

FTP.rmd(dirname)?

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

FTP.size(filename)?

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

FTP.quit()?

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

FTP.close()?

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

FTP_TLS 對象?

FTP_TLS 類(lèi)繼承自 FTP，它定義了下述其他對象：

FTP_TLS.ssl_version?

欲采用的 SSL 版本（默認為 ssl.PROTOCOL_SSLv23）。

FTP_TLS.auth()?

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

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

FTP_TLS.ccc()?

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

3.3 新版功能.

FTP_TLS.prot_p()?

設置加密數據連接。

FTP_TLS.prot_c()?

設置明文數據連接。