FTP 物件¶

classftplib.FTP(host='',user='',passwd='',acct='',timeout=None,source_address=None,*,encoding='utf-8')¶

回傳一個新的FTP 類別實例。

參數:

• host (str) -- 要連接的主機名稱。如果有給定，connect(host) 會由建構函式來隱式地呼叫。

• user (str) -- The username to log in with (default:'anonymous'). 如果有給定，login(host,passwd,acct) 會由建構函式來隱式地呼叫。

• passwd (str) -- The password to use when logging in.If not given, and ifpasswd is the empty string or"-",a password will be automatically generated.

• acct (str) -- Account information to be used for theACCT FTP command.Few systems implement this.SeeRFC-959for more details.

• timeout (float |None) -- 如connect() 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設超時設定）。

• source_address (tuple |None) -- A 2-tuple(host,port) for the socket to bind to as itssource address before connecting.

• encoding (str) -- The encoding for directories and filenames (default:'utf-8').

FTP 類別支援with 陳述式，例如：

>>>fromftplibimportFTP>>>withFTP("ftp1.at.proftpd.org")asftp:...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 CentOSdr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora>>>

在 3.2 版的變更:新增了對with 陳述式的支援。

在 3.3 版的變更:新增source_address 參數。

在 3.9 版的變更:如果timeout 參數設定為零，它將引發ValueError 以防止建立非阻塞 socket。新增了encoding 參數，預設值從 Latin-1 更改為 UTF-8 以遵循RFC 2640。

FTP 的多個可用方法大致有分為兩個方向：一種用於處理文本檔案 (text files)，另一種用於二進位檔案 (binary files)。這些以在文本檔案的lines 或二進位檔案的binary 前使用的命令命名。

FTP 實例具有以下方法：

set_debuglevel(level)¶

將實例的偵錯級別設定為一個int，這控制印出的偵錯訊息輸出量。

• 0（預設值）：不產生偵錯輸出。

• 1：會產生適量的偵錯輸出，通常是每個請求輸出一行。

• 2 或更高的值：會產生最大量的偵錯輸出，以日誌紀錄下控制連線發送和接收的每個步驟。

connect(host='',port=0,timeout=None,source_address=None)¶

連線到給定的主機 (host) 和連接埠 (port)。每個實例只應呼叫此函式一次；如果在建立FTP 實例時有給定host 引數，則不應呼叫它。所有其他的FTP 方法只能在成功建立連線後使用。

參數:

• host (str) -- 要連接的主機。

• port (int) -- 要連接的 TCP 連接埠（預設值：21，由 FTP 協定規範指定）。很少需要指定不同的連接埠號碼。

• timeout (float |None) -- 連線嘗試的超時設定，以秒為單位（預設：全域預設超時設定）。

• source_address (tuple |None) -- A 2-tuple(host,port) for the socket to bind to as itssource address before connecting.

引發一個附帶引數self、host、port 的稽核事件ftplib.connect。

在 3.3 版的變更:新增source_address 參數。

getwelcome()¶

回傳伺服器為回應初始連線而發送的歡迎訊息。（此訊息有時會包含與使用者相關的免責聲明或幫助資訊。）

login(user='anonymous',passwd='',acct='')¶

在以連線的伺服器上登入。在建立連線後，每個實例只應呼叫此函式一次；如果在建立FTP 實例時有給定host 和user 引數，則不應呼叫它。大多數 FTP 命令僅在用戶端登錄後才允許使用

參數:

• user (str) -- The username to log in with (default:'anonymous').

• passwd (str) -- The password to use when logging in.If not given, and ifpasswd is the empty string or"-",a password will be automatically generated.

• acct (str) -- Account information to be used for theACCT FTP command.Few systems implement this.SeeRFC-959for more details.

abort()¶

中止正在進行的檔案傳輸。使用它並不是都會成功，但值得一試。

sendcmd(cmd)¶

向伺服器發送一個簡單的命令字串並回傳回應字串。

引發一個附帶引數self、cmd 的稽核事件ftplib.sendcmd。

voidcmd(cmd)¶

向伺服器發送一個簡單的命令字串並處理回應。如果收到代表成功的回應狀態碼（範圍為 200--299 的狀態碼），則回傳回應字串，否則引發error_reply。

引發一個附帶引數self、cmd 的稽核事件ftplib.sendcmd。

retrbinary(cmd,callback,blocksize=8192,rest=None)¶

以二進位傳輸模式 (binary transfer mode) 取得檔案。

參數:

• cmd (str) -- 一個正確的RETR 指令："RETRfilename"。

• callback (callable) -- 為接收到的每個資料區塊呼叫的單一參數可呼叫物件，其單一引數是以bytes 為形式的資料。

• blocksize (int) -- 在執行實際傳輸時所建立的低階socket 物件上讀取的最大分塊 (chunk) 大小。這也對應於將傳遞給callback 的最大資料大小。預設為8192。

• rest (int) -- 一個要發送到伺服器的REST 命令。參見transfercmd() 方法之rest 參數的文件。

retrlines(cmd,callback=None)¶

在初始化時以encoding 參數指定的編碼來取得檔案或目錄列表。cmd 要是一個正確的RETR 命令（見retrbinary()）或者一個像LIST 或NLST 的命令（通常只是字串'LIST' )。LIST 會取得檔案列表和這些檔案的相關資訊。NLST 取得檔案名稱列表。會為每一行以一個字串引數呼叫callback 函式，其引數包含已經刪除尾隨 CRLF 的一行。預設的callback 會將各行印出到sys.stdout。

set_pasv(val)¶

如果val 為真，則啟用「被動」模式，否則禁用被動模式。被動模式預設開啟。

storbinary(cmd,fp,blocksize=8192,callback=None,rest=None)¶

以二進位傳輸模式儲存檔案。

參數:

• cmd (str) -- 一個正確的STOR 指令："STORfilename"。

• fp (file object) -- 一個檔案物件（以二進位模式開啟），在大小為blocksize 的區塊中使用其read() 方法讀取直到 EOF 來提供要儲存的資料。

• blocksize (int) -- 讀取區塊大小。預設為8192。

• callback (callable) -- 為發送的每個資料區塊來呼叫的單一參數可呼叫物件，其單一引數是以bytes 為形式的資料。

• rest (int) -- 一個要發送到伺服器的REST 命令。參見transfercmd() 方法之rest 參數的文件。

在 3.2 版的變更:新增rest 參數。

storlines(cmd,fp,callback=None)¶

以行模式 (line mode) 儲存檔案。cmd 應是一個正確的STOR 命令（參見storbinary()）。使用其readline() 方法從檔案物件fp （以二進位模式打開）讀取各行、直到 EOF，以提供要儲存的資料。callback 是可選的單參數可呼叫物件，於發送後以各行進行呼叫。

transfercmd(cmd,rest=None)¶

通過資料連線啟動傳輸。如果傳輸為主動 (active) 模式，則發送EPRT 或PORT 命令和cmd 指定的傳輸命令，並接受連線。如果伺服器是被動 (passive) 模式，則發送EPSV 或PASV 命令、連線、並啟動傳輸命令。無論哪種方式，都是回傳連線的 socket。

如果有給定可選的rest，一個REST 命令會被發送到伺服器，並以rest 作為引數。rest 通常是請求檔案的一個位元組偏移量 (byte offset)，告訴伺服器以請求的偏移量重新開始發送檔案的位元組，並跳過初始位元組。但是請注意，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的字典。該字典的內容可能受facts 引數限制，但不保證伺服器會回傳所有請求的 facts。

在 3.3 版被加入.

nlst(argument[,...])¶

回傳由NLST 命令回傳的檔案名稱列表。可選的argument 是要列出的目錄（預設為目前伺服器目錄）。多個引數可用於將非標準選項傳遞給NLST 命令。

備註

如果你的伺服器支援該命令，mlsd() 會提供更好的 API。

dir(argument[,...])¶

生成由LIST 命令回傳的目錄列表，並將其印出到標準輸出 (standard output)。可選的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 命令不是標準化的，但被許多常見的伺服器實作支援。

quit()¶

向伺服器發送QUIT 命令並關閉連線。這是關閉連線的「禮貌」方式，但如果伺服器對QUIT 命令作出錯誤回應，它可能會引發例外。這意味著呼叫close() 方法使FTP 實例無法用於後續呼叫（見下文）。

close()¶

單方面關閉連線。這不應該使用於已經關閉的連線，例如在成功呼叫quit() 之後。呼叫後就不應該再次使用FTP 實例（在呼叫close() 或quit() 後，你不能通過發出另一個login() 方法重新打開連線）。

FTP_TLS 物件¶

classftplib.FTP_TLS(host='',user='',passwd='',acct='',*,context=None,timeout=None,source_address=None,encoding='utf-8')¶

AnFTP subclass which adds TLS support to FTP as described inRFC 4217.Connect to port 21 implicitly securing the FTP control connectionbefore authenticating.

備註

The user must explicitly secure the data connectionby calling theprot_p() method.

參數:

• host (str) -- 要連接的主機名稱。如果有給定，connect(host) 會由建構函式來隱式地呼叫。

• user (str) -- The username to log in with (default:'anonymous'). 如果有給定，login(host,passwd,acct) 會由建構函式來隱式地呼叫。

• passwd (str) -- The password to use when logging in.If not given, and ifpasswd is the empty string or"-",a password will be automatically generated.

• acct (str) -- Account information to be used for theACCT FTP command.Few systems implement this.SeeRFC-959for more details.

• context (ssl.SSLContext) -- An SSL context object which allows bundling SSL configuration options,certificates and private keys into a single, potentially long-lived,structure.Please readSecurity considerations for best practices.

• timeout (float |None) -- 如connect() 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設超時設定）。

• source_address (tuple |None) -- A 2-tuple(host,port) for the socket to bind to as itssource address before connecting.

• encoding (str) -- The encoding for directories and filenames (default:'utf-8').

在 3.2 版被加入.

在 3.3 版的變更:新增source_address 參數。

在 3.4 版的變更:該類別現在支援使用ssl.SSLContext.check_hostname 和Server Name Indication 進行主機名 (hostname) 檢查（參見ssl.HAS_SNI）。

在 3.9 版的變更:如果timeout 參數設定為零，它將引發ValueError 以防止建立非阻塞 socket。新增了encoding 參數，預設值從 Latin-1 更改為 UTF-8 以遵循RFC 2640。

在 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()¶

根據ssl_version 屬性中指定的內容，使用 TLS 或 SSL 設定安全控制連線。

在 3.4 版的變更:該方法現在支援使用ssl.SSLContext.check_hostname 和Server Name Indication 進行主機名檢查（參見ssl.HAS_SNI）。

ccc()¶

將控制通道恢復為純文本。這對於利用知道如何在不打開固定連接埠的情況下使用非安全 (non-secure) FTP 以處理 NAT 的防火牆很有用。

在 3.3 版被加入.

prot_p()¶

設定安全資料連線。

prot_c()¶

設定明文資料 (clear text data) 連線。

模組變數¶

exceptionftplib.error_reply¶

伺服器收到意外回覆時所引發的例外。

exceptionftplib.error_temp¶

當收到表示暫時錯誤的錯誤碼（400--499 範圍內的回應狀態碼）時引發的例外。

exceptionftplib.error_perm¶

當收到表示永久錯誤的錯誤碼（500--599 範圍內的回應狀態碼）時引發的例外。

exceptionftplib.error_proto¶

當從伺服器收到不符合檔案傳輸協定回應規範的回覆時引發例外，即 1--5 範圍內的數字開頭。

ftplib.all_errors¶

FTP 實例方法由於 FTP 連線問題（相對於呼叫者的程式錯誤）而可能引發的所有例外集合（元組形式）。該集合包括上面列出的四個例外以及OSError 和EOFError。