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