"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-emscripten" 和 "wasm32-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.

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

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

   getwelcome()

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

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

      登录到已连接的 FTP 服务器。 在建立连接后，此函数应当只为每个实例
      调用一次；如果在创建 "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)

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

      參數:
         * **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()") 或是像
      "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*) -- 一个被读取直至 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) 模式，則發送
      "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" 命令所返回的结果，将其打印到标准输出。
      可选的 *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'").

   *keyfile* 和 *certfile* 是 *context* 的傳統替代方案 -- 它們可以（分
   別）指向 SSL 連線的 PEM 格式私鑰和憑證鏈檔案。

   在 3.2 版新加入.

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

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

   在 3.6 版之後被棄用: *keyfile* 和 *certfile* 已棄用，取而代之的是
   *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 連線問題（相對於呼叫者的程式錯誤）而可能引發
   的所有例外集合（元組形式）。該集合包括上面列出的四個例外以及
   "OSError" 和 "EOFError"。

也參考:

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