`ftplib` --- FTP 協定用戶端¶

原始碼：Lib/ftplib.py

這個模組定義了 FTP 類別和一些相關的項目。FTP 類別實作了 FTP 協定的用戶端。你可以使用它來編寫能夠執行各種 FTP 自動作業的 Python 程式，例如鏡像 (mirror) 其他 FTP 伺服器。urllib.request 模組也使用它來處理使用 FTP 的 URL。有關 FTP（檔案傳輸協定）的更多資訊，請參閱 RFC 959。

預設編碼是 UTF-8，遵循 RFC 2640。

可用性: not 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) -- 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 if passwd is the empty string or "-", a password will be automatically generated.
acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.
timeout (float | None) -- 如 connect() 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設超時設定）。
source_address (tuple | None) -- A 2-tuple (host, port) for the socket to bind to as its source address before connecting.
encoding (str) -- The encoding for directories and filenames (default: 'utf-8').

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

>>> 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 以防止建立非阻塞 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 its source 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 if passwd is the empty string or "-", a password will be automatically generated.
acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for 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 指令："RETR filename"。
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 指令："STOR filename"。
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(

ftplib --- FTP 協定用戶端¶

參考¶

FTP 物件¶

`ftplib` --- FTP 協定用戶端¶