ftplib --- FTP 協定用戶端

原始碼:Lib/ftplib.py


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

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

Availability:非 Emscripten、非 WASI。

此模組在 WebAssembly 平台 wasm32-emscriptenwasm32-wasi 上不起作用或無法使用。有關更多資訊,請參閱 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 方法有两种形式:一种用于处理文本文件而另一种用于二进制文件。 这些方法的名称与所用的命令相对应,文本版之后跟 lines 而二进制版之后跟 binary

FTP 實例具有以下方法:

set_debuglevel(level)

将实例的调试级别设为一个 int 值。 这将控制所打印的调试输出数据量。 调试级别包括:

  • 0 (默认): 无调试输出。

  • 1: 产生中等的调试输出数据量,通常为每个请求一行。

  • 2 或更高: 产生最大的调试输出数据量,记录在控制连接中发送和接收的每一行。

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

连接到给定的主机和端口。 此函数应当只为每个实例调用一次;如果在创建 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.

引發一個附帶引數 selfhostport稽核事件 ftplib.connect

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

getwelcome()

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

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

登录到已连接的 FTP 服务器。 在建立连接后,此函数应当只为每个实例调用一次;如果在创建 FTP 实例时给出了 hostuser 参数则不应调用该函数。 大多数 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)

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

引發一個附帶引數 selfcmd稽核事件 ftplib.sendcmd

voidcmd(cmd)

Send a simple command string to the server and handle the response. Return the response string if the response code corresponds to success (codes in the range 200--299). Raise error_reply otherwise.

引發一個附帶引數 selfcmd稽核事件 ftplib.sendcmd

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

以二进制传输模式获取一个文件。

參數:
  • cmd (str) -- 一个正确的 STOR 命令: "STOR filename"

  • callback (callable) -- 一个针对所接收的每个数据块被调用的单形参可调用对象,其唯一参数即 bytes 类型的数据。

  • blocksize (int) -- 在为进行实际传输而创建的底层 socket 对象上读取的块尺寸最大值。 这也对应于将要传给 callback 的数据尺寸最大值。 默认为 8192

  • rest (int) -- 要发送给服务器的 REST 命令。 参见 transfercmd() 方法的 rest 形参的文档。

retrlines(cmd, callback=None)

以在初始化时由 encoding 形参指定的编码格式获取文件或目录列表。 cmd 应为一个适当的 RETR 命令 (参见 retrbinary()) 或是像 LISTNLST 这样的命令 (通常即字符串 '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) -- 一个被读取直至 EOF 的文件对象(以二进制模式打开),使用其 read() 方法以大小为 blocksize 的块来提供要存储的数据。

  • 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) 模式,則發送 EPRTPORT 命令和 cmd 指定的傳輸命令,並接受連線。如果伺服器是被動 (passive) 模式,則發送 EPSVPASV 命令、連線、並啟動傳輸命令。無論哪種方式,都是回傳連線的 socket。

如果有給定可選的 rest,一個 REST 命令會被發送到伺服器,並以 rest 作為引數。rest 通常是請求檔案的一個位元組偏移量 (byte offset),告訴伺服器以請求的偏移量重新開始發送檔案的位元組,並跳過初始位元組。但是請注意,transfercmd() 方法將 rest 轉換為帶有初始化時指定的 encoding 參數的字串,但不會對字串的內容執行檢查。如果伺服器無法識別 REST 命令,則會引發 error_reply 例外。如果發生這種情況,只需在沒有 rest 引數的情況下呼叫 transfercmd()

ntransfercmd(cmd, rest=None)

類似於 transfercmd(),但回傳一個帶有資料連線和資料預期大小的元組。如果無法計算預期大小,則回傳 Nonecmdresttransfercmd() 中的含義相同。

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 命令所返回的结果,将其打印到标准输出。 可选的 argument 是要列出的目录(默认为当前服务器目录)。 可以使用多个参数将非标准选项传给 LIST 命令。 如果最后一个参数是个函数,它将被用作 callback 函数,与 retrlines() 的类似;默认将打印到 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 对象

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

一个为 FTP 添加如 RFC 4217 所描述的 TLS 支持的 FTP 的子类。 连接到 21 端口在身份验证之前隐式地确保 FTP 控制连接的安全。

備註

用户必须通过调用 prot_p() 方法显式地确保数据连接的安全。

參數:
  • 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.

  • context (ssl.SSLContext) -- 一个允许将 SSL 配置选项、证书和私钥打包至一个单独的、可以长久存在的结构体中的 SSL 上下文对象。 请参阅 安全考量 了解相关的最佳实践。

  • 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').

keyfilecertfilecontext 的傳統替代方案 -- 它們可以(分別)指向 SSL 連線的 PEM 格式私鑰和憑證鏈檔案。

在 3.2 版新加入.

在 3.3 版的變更: 增加了 source_address 形参。

在 3.4 版的變更: 该类现在支持使用 ssl.SSLContext.check_hostname服务器名称提示 (参见 ssl.HAS_SNI) 进行主机名检测。

在 3.6 版之後被棄用: keyfilecertfile 已棄用,取而代之的是 context。請改用 ssl.SSLContext.load_cert_chain(),或讓 ssl.create_default_context() 為你選擇系統的可信 CA 憑證。

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

這是一個使用 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服务器名称提示 (参见 ssl.HAS_SNI) 进行主机名称检测。

ccc()

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

在 3.3 版新加入.

prot_p()

設定安全資料連線。

prot_c()

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

模块变量

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 連線問題(相對於呼叫者的程式錯誤)而可能引發的所有例外集合(元組形式)。該集合包括上面列出的四個例外以及 OSErrorEOFError

也參考

netrc 模組

.netrc 檔案格式的剖析器。.netrc 檔案通常被 FTP 用戶端用來在提示使用者之前載入使用者身份驗證資訊。