ftplib — FTP 協議客戶端¶
原始碼: Lib/ftplib.py
該模組定義了 FTP 類和一些相關項。FTP 類實現了 FTP 協議的客戶端部分。 你可以使用它來編寫執行各種自動化 FTP 作業的 Python 程式，例如映象其他 FTP 伺服器。 它也被模組 urllib.request 用於處理使用 FTP 的 URL。 有關 FTP（檔案傳輸協議）的更多資訊，請參閱網際網路 RFC 959。
預設編碼是 UTF-8，遵循 RFC 2640。
可用性: 非 WASI。
此模組在 WebAssembly 上不起作用或不可用。 有關更多資訊，請參閱 WebAssembly 平臺。
這是一個使用 ftplib 模組的會話示例
>>> 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.'
參考¶
FTP 物件¶
- class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')¶
返回
FTP類的新例項。- 引數：
host (str) – 要連線的主機名。 如果給定，則建構函式會隱式呼叫
connect(host)。user (str) – 用於登入的使用者名稱（預設值：
'anonymous'）。 如果給定，則建構函式會隱式呼叫login(host, passwd, acct)。passwd (str) – 登入時使用的密碼。 如果未給定，並且如果 passwd 是空字串或
"-"，則會自動生成密碼。acct (str) – 用於
ACCTFTP 命令的帳戶資訊。 很少有系統實現此功能。 有關更多詳細資訊，請參閱 RFC-959。timeout (float | None) – 阻塞操作（如
connect()）的超時時間（以秒為單位）（預設值：全域性預設超時設定）。source_address (tuple | None) – 用於套接字在連線前繫結到的源地址的 2 元組
(host, port)。encoding (str) – 目錄和檔名的編碼（預設值：
'utf-8'）。
>>> 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語句的支援。在 3.3 版本中更改: 添加了 source_address 引數。
在 3.9 版本中更改: 如果 timeout 引數設定為零，它將引發
ValueError以防止建立非阻塞套接字。 添加了 encoding 引數，並且預設值從 Latin-1 更改為 UTF-8，以遵循 RFC 2640。有幾種
FTP方法有兩種形式：一種用於處理文字檔案，另一種用於處理二進位制檔案。 這些方法以所使用的命令命名，後跟用於文字版本的lines或用於二進位制版本的binary。FTP例項具有以下方法- set_debuglevel(level)¶
將例項的除錯級別設定為
int。 這控制列印的除錯輸出量。 除錯級別是0（預設值）：無除錯輸出。1：產生適量的除錯輸出，通常每個請求一行。2或更高：產生最大量的除錯輸出，記錄在控制連線上傳送和接收的每一行。
- connect(host='', port=0, timeout=None, source_address=None)¶
連線到給定的主機和埠。 每個例項應僅呼叫此函式一次； 如果建立
FTP例項時給定了 host 引數，則不應呼叫此函式。 只有在成功建立連線後才能呼叫所有其他FTP方法。- 引數：
引發一個審計事件
ftplib.connect，引數為self、host和port。在 3.3 版本中更改: 添加了 source_address 引數。
- getwelcome()¶
返回伺服器在初始連線時傳送的歡迎訊息。（此訊息有時包含可能與使用者相關的免責宣告或幫助資訊。）
- login(user='anonymous', passwd='', acct='')¶
登入到連線的 FTP 伺服器。此函式對於每個例項應僅呼叫一次，在建立連線後呼叫；如果在建立
FTP例項時已提供 host 和 user 引數，則不應呼叫此函式。大多數 FTP 命令僅在客戶端登入後才允許執行。
- abort()¶
中止正在進行的檔案傳輸。使用此方法並非總是有效，但值得一試。
- voidcmd(cmd)¶
向伺服器傳送一個簡單的命令字串並處理響應。如果響應程式碼對應於成功（程式碼範圍在 200-299 之間），則返回響應字串。否則，引發
error_reply異常。引發一個審計事件
ftplib.sendcmd，引數為self和cmd。
- retrbinary(cmd, callback, blocksize=8192, rest=None)¶
以二進位制傳輸模式檢索檔案。
- retrlines(cmd, callback=None)¶
檢索以初始化時 encoding 引數指定的編碼的檔案或目錄列表。cmd 應該是適當的
RETR命令（參見retrbinary()）或諸如LIST或NLST之類的命令（通常只是字串'LIST'）。LIST檢索檔案列表以及有關這些檔案的資訊。NLST檢索檔名稱列表。對於每一行，將呼叫 callback 函式，其中字串引數包含該行，並且刪除了尾部的 CRLF。預設的 callback 將該行列印到sys.stdout。
- set_pasv(val)¶
如果 val 為 true，則啟用“被動”模式，否則停用被動模式。預設情況下，被動模式處於啟用狀態。
- storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)¶
以二進位制傳輸模式儲存檔案。
- 引數：
在 3.2 版本中更改: 添加了 rest 引數。
- storlines(cmd, fp, callback=None)¶
以行模式儲存檔案。cmd 應該是適當的
STOR命令（參見storbinary()）。使用readline()方法從 檔案物件 fp（以二進位制模式開啟）中讀取行，直到 EOF，以提供要儲存的資料。 callback 是一個可選的單引數可呼叫物件，在每行傳送後呼叫。
- transfercmd(cmd, rest=None)¶
透過資料連線啟動傳輸。如果傳輸處於活動狀態，則傳送
EPRT或PORT命令和 cmd 指定的傳輸命令，並接受連線。如果伺服器處於被動模式，則傳送EPSV或PASV命令，連線到它並啟動傳輸命令。無論哪種方式，都返回連線的套接字。如果提供了可選的 rest 引數，則會向伺服器傳送一個
REST命令，並將 rest 作為引數傳遞。rest 通常是請求檔案中的位元組偏移量，告訴伺服器從請求的偏移量處重新開始傳送檔案的位元組，跳過初始位元組。但請注意，transfercmd()方法會將 rest 轉換為字串，並使用初始化時指定的 encoding 引數，但不對字串內容進行檢查。如果伺服器無法識別REST命令，將引發error_reply異常。如果發生這種情況，只需在不使用 rest 引數的情況下呼叫transfercmd()即可。
- ntransfercmd(cmd, rest=None)¶
與
transfercmd()類似，但返回一個包含資料連線和預期資料大小的元組。如果無法計算預期大小，則預期大小將返回None。cmd 和 rest 的含義與transfercmd()中的含義相同。
- mlsd(path='', facts=[])¶
使用
MLSD命令（RFC 3659）以標準化格式列出目錄。如果省略 path，則假定為當前目錄。facts 是一個字串列表，表示所需的資訊型別（例如，["type", "size", "perm"]）。返回一個生成器物件，該物件為在路徑中找到的每個檔案生成一個包含兩個元素的元組。第一個元素是檔名，第二個元素是一個包含有關檔名的資訊的字典。此字典的內容可能受 facts 引數的限制，但不保證伺服器返回所有請求的資訊。在 3.3 版本中新增。
- nlst(argument[, ...])¶
返回由
NLST命令返回的檔名列表。可選的 argument 是要列出的目錄（預設為當前伺服器目錄）。可以使用多個引數將非標準選項傳遞給NLST命令。注意
如果您的伺服器支援該命令，
mlsd()提供了更好的 API。
- dir(argument[, ...])¶
生成由
LIST命令返回的目錄列表，並將其列印到標準輸出。可選的 argument 是要列出的目錄（預設為當前伺服器目錄）。可以使用多個引數將非標準選項傳遞給LIST命令。如果最後一個引數是一個函式，則將其用作retrlines()的 callback 函式；預設情況下會列印到sys.stdout。此方法返回None。注意
如果您的伺服器支援該命令，
mlsd()提供了更好的 API。
- rename(fromname, toname)¶
將伺服器上的檔案 fromname 重新命名為 toname。
- delete(filename)¶
從伺服器中刪除名為 filename 的檔案。如果成功，則返回響應的文字，否則，如果出現許可權錯誤，則引發
error_perm，如果出現其他錯誤，則引發error_reply。
- cwd(pathname)¶
設定伺服器上的當前目錄。
- mkd(pathname)¶
在伺服器上建立一個新目錄。
- pwd()¶
返回伺服器上當前目錄的路徑名。
- rmd(dirname)¶
刪除伺服器上名為 dirname 的目錄。
- size(filename)¶
請求伺服器上名為 filename 的檔案的大小。如果成功，則返回檔案的大小（整數），否則返回
None。請注意，SIZE命令未標準化，但許多常見的伺服器實現都支援該命令。
FTP_TLS 物件¶
- class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')¶
一個
FTP的子類，它按照 RFC 4217 中的描述，為 FTP 添加了 TLS 支援。連線到埠 21 會在身份驗證之前隱式地保護 FTP 控制連線。注意
使用者必須透過呼叫
prot_p()方法來顯式地保護資料連線。- 引數：
host (str) – 要連線的主機名。 如果給定，則建構函式會隱式呼叫
connect(host)。user (str) – 用於登入的使用者名稱（預設值：
'anonymous'）。 如果給定，則建構函式會隱式呼叫login(host, passwd, acct)。passwd (str) – 登入時使用的密碼。 如果未給定，並且如果 passwd 是空字串或
"-"，則會自動生成密碼。acct (str) – 用於
ACCTFTP 命令的帳戶資訊。 很少有系統實現此功能。 有關更多詳細資訊，請參閱 RFC-959。context (
ssl.SSLContext) – 一個 SSL 上下文物件，它允許將 SSL 配置選項、證書和私鑰捆綁到一個可能長期存在的結構中。 請閱讀 安全注意事項 以瞭解最佳實踐。timeout (float | None) – 阻塞操作（如
connect()）的超時時間（以秒為單位）（預設值：全域性預設超時設定）。source_address (tuple | None) – 用於套接字在連線前繫結到的源地址的 2 元組
(host, port)。encoding (str) – 目錄和檔名的編碼（預設值：
'utf-8'）。
在版本 3.2 中新增。
在版本 3.3 中更改: 添加了 source_address 引數。
在版本 3.4 中更改: 該類現在支援使用
ssl.SSLContext.check_hostname和伺服器名稱指示（請參閱ssl.HAS_SNI）進行主機名檢查。在版本 3.9 中更改: 如果 timeout 引數設定為零，它將引發一個
ValueError以防止建立非阻塞套接字。添加了 encoding 引數，並且為了遵循 RFC 2640，預設值從 Latin-1 更改為 UTF-8。在版本 3.12 中更改: 已刪除已棄用的 keyfile 和 certfile 引數。
這是一個使用
FTP_TLS類的示例會話>>> 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']
FTP_TLS類繼承自FTP，定義了這些附加的方法和屬性- ssl_version¶
要使用的 SSL 版本（預設為
ssl.PROTOCOL_SSLv23）。
- auth()¶
透過使用 TLS 或 SSL（取決於
ssl_version屬性中指定的內容）建立安全的控制連線。在版本 3.4 中更改: 該方法現在支援使用
ssl.SSLContext.check_hostname和伺服器名稱指示（請參閱ssl.HAS_SNI）進行主機名檢查。
- ccc()¶
將控制通道恢復為純文字。這對於利用知道如何使用非安全 FTP 處理 NAT 的防火牆而無需開啟固定埠非常有用。
在 3.3 版本中新增。
- prot_p()¶
建立安全的資料連線。
- prot_c()¶
建立明文資料連線。
模組變數¶
- exception ftplib.error_reply¶
當從伺服器收到意外的回覆時引發的異常。
- exception ftplib.error_temp¶
當收到表示臨時錯誤的錯誤程式碼（響應程式碼在 400-499 範圍內）時引發的異常。
- exception ftplib.error_perm¶
當收到表示永久錯誤的錯誤程式碼（響應程式碼在 500-599 範圍內）時引發的異常。
- exception ftplib.error_proto¶
當從伺服器收到的回覆不符合檔案傳輸協議的響應規範（即，以 1-5 範圍內的數字開頭）時引發的異常。
- ftplib.all_errors¶
作為 FTP 連線問題（而不是呼叫者產生的程式設計錯誤）的結果，
FTP例項的方法可能引發的所有異常的集合（作為元組）。 此集合包括上面列出的四個異常，以及OSError和EOFError。
另請參閱
- 模組
netrc .netrc檔案格式的解析器。.netrc檔案通常由 FTP 客戶端在提示使用者之前載入使用者身份驗證資訊。