"ftplib" --- FTP 協定用戶端
***************************

**原始碼：**Lib/ftplib.py

======================================================================

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

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

Availability：非 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(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 物件
------------

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

   An "FTP" subclass which adds TLS support to FTP as described in
   **RFC 4217**. Connect to port 21 implicitly securing the FTP
   control connection before authenticating.

   備註:

     The user must explicitly secure the data connection by calling
     the "prot_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 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") -- An SSL context object which
        allows bundling SSL configuration options, certificates and
        private keys into a single, potentially long-lived, structure.
        Please read Security considerations for best practices.

      * **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'").

   在 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) 連線。


模組變數
--------

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 用戶端用來在提
     示使用者之前載入使用者身份驗證資訊。
