21.13. ftplib — FTP 协议客户端

源代码： :source:`Lib/ftplib.py`

该模块定义了类 FTP 和一些相关项目。 FTP 类实现了 FTP 协议的客户端。您可以使用它来编写 Python 程序来执行各种自动 FTP 作业，例如镜像其他 FTP 服务器。模块 urllib.request 也使用它来处理使用 FTP 的 URL。有关 FTP（文件传输协议）的更多信息，请参阅 Internet RFC 959。

这是使用 ftplib 模块的示例会话：

>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org')     # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
>>> 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.'
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()

该模块定义了以下项目：

class ftplib.FTP(host=, user=, passwd=, acct=, timeout=None, source_address=None)

返回 FTP 类的新实例。当给出 host 时，进行方法调用 connect(host)。当给出 user 时，另外进行方法调用 login(user, passwd, acct)（其中 passwd 和 acct 在未给出时默认为空字符串）。可选的 timeout 参数指定阻塞操作（如连接尝试）的超时（以秒为单位）（如果未指定，将使用全局默认超时设置）。 source_address 是一个 2 元组 (host, port)，用于套接字在连接之前绑定到其源地址。

FTP 类支持 [X36X]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 参数。

class ftplib.FTP_TLS(host=, user=, passwd=, acct=, keyfile=None, certfile=None, context=None, timeout=None, source_address=None)

FTP 子类，为 FTP 添加了 TLS 支持，如 RFC 4217 中所述。像往常一样连接到端口 21，在验证之前隐式保护 FTP 控制连接。保护数据连接需要用户通过调用 prot_p() 方法明确要求它。 context 是一个 ssl.SSLContext 对象，它允许将 SSL 配置选项、证书和私钥捆绑到一个（可能是长期存在的）结构中。请阅读安全注意事项以获得最佳实践。

keyfile 和 certfile 是 context 的传统替代方案——它们可以指向 PEM 格式的私钥和证书链文件（分别）用于 SSL 连接。

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 证书。

这是使用 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']

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。

也可以看看

模块 netrc: .netrc 文件格式的解析器。文件 .netrc 通常由 FTP 客户端用于在提示用户之前加载用户身份验证信息。

21.13.1. FTP 对象

几种方法有两种可用：一种用于处理文本文件，另一种用于处理二进制文件。它们以使用的命令命名，后跟 lines 表示文本版本或 binary 表示二进制版本。

FTP实例有以下方法：

FTP.set_debuglevel(level): 设置实例的调试级别。这控制打印的调试输出量。默认值 0 不产生调试输出。 1 的值会产生适量的调试输出，通常每个请求只有一行。 2 或更高的值会产生最大数量的调试输出，记录控制连接上发送和接收的每一行。

FTP.connect(host=, port=0, timeout=None, source_address=None): 连接到给定的主机和端口。默认端口号为 21，如 FTP 协议规范所指定。很少需要指定不同的端口号。每个实例只应调用一次此函数；如果在创建实例时提供了主机，则根本不应调用它。所有其他方法只能在建立连接后使用。可选的 timeout 参数指定连接尝试的超时时间（以秒为单位）。如果没有传递 timeout，则将使用全局默认超时设置。 source_address 是一个 2 元组 (host, port)，用于套接字在连接之前绑定到其源地址。

3.3 版更改：添加了 source_address 参数。

FTP.getwelcome(): 返回服务器发送的欢迎消息以回复初始连接。（此消息有时包含可能与用户相关的免责声明或帮助信息。）

FTP.login(user='anonymous', passwd=, acct=): 作为给定的用户登录。 passwd 和 acct 参数是可选的，默认为空字符串。如果未指定 user，则默认为 'anonymous'。如果 user 为 'anonymous'，则默认 passwd 为 'anonymous@'。在建立连接后，对于每个实例只应调用一次此函数；如果在创建实例时提供了主机和用户，则根本不应调用它。大多数 FTP 命令仅在客户端登录后才允许。 acct 参数提供“会计信息”；很少有系统实现这一点。

FTP.abort(): 中止正在进行的文件传输。使用它并不总是有效，但值得一试。

FTP.sendcmd(cmd): 向服务器发送一个简单的命令字符串并返回响应字符串。

FTP.voidcmd(cmd): 向服务器发送一个简单的命令字符串并处理响应。如果收到与成功对应的响应代码（范围为 200-299 的代码），则不返回任何内容。否则提高 error_reply。

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None): 以二进制传输模式检索文件。 cmd 应该是一个合适的 RETR 命令：'RETR filename'。 callback 函数为接收到的每个数据块调用，使用单个字节参数给出数据块。可选的 blocksize 参数指定在创建以进行实际传输的低级套接字对象上读取的最大块大小（这也是传递给 callback 的数据块的最大大小]）。选择了合理的默认值。 rest 与 transfercmd() 方法中的含义相同。

FTP.retrlines(cmd, callback=None): 以 ASCII 传输模式检索文件或目录列表。 cmd 应该是一个合适的 RETR 命令（见 retrbinary()）或一个命令如 LIST 或 NLST（通常只是字符串 'LIST'）。 LIST 检索文件列表和有关这些文件的信息。 NLST 检索文件名列表。 callback 函数为每一行调用，其中包含一个字符串参数，其中包含删除了尾随 CRLF 的行。默认的 callback 将行打印到 sys.stdout。

FTP.set_pasv(val): 如果 val 为真，则启用“被动”模式，否则禁用被动模式。被动模式默认开启。

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None): 以二进制传输模式存储文件。 cmd 应该是一个合适的 STOR 命令："STOR filename"。 fp 是一个文件对象（以二进制模式打开），使用其 read() 方法在大小为 blocksize 的块中读取直到 EOF要存储的数据。 blocksize 参数默认为 8192。 callback 是一个可选的单个参数 callable，它在发送后在每个数据块上调用。 rest 与 transfercmd() 方法中的含义相同。

3.2 版更改：添加了 rest 参数。

FTP.storlines(cmd, fp, callback=None): 以 ASCII 传输模式存储文件。 cmd 应该是一个合适的 STOR 命令（见 storbinary()）。使用其 readline() 方法从文件对象 fp（以二进制模式打开）读取行直到 EOF，以提供要存储的数据。 callback 是一个可选的单参数 callable，在发送后在每一行上调用。

FTP.transfercmd(cmd, rest=None)

通过数据连接启动传输。如果传输处于活动状态，则发送 EPRT 或 PORT 命令和 cmd 指定的传输命令，并接受连接。如果服务器是被动的，发送 EPSV 或 PASV 命令，连接到它，并启动传输命令。无论哪种方式，返回连接的套接字。

如果给出了可选的 rest，则将 REST 命令发送到服务器，并将 rest 作为参数传递。 rest 通常是请求文件的字节偏移量，告诉服务器在请求的偏移量处重新发送文件的字节，跳过初始字节。但是请注意，RFC 959 仅要求 rest 是包含可打印范围内的字符的字符串，从 ASCII 代码 33 到 ASCII 代码 126。因此，transfercmd() 方法将 rest 转换为字符串，但不对字符串的内容执行检查。如果服务器无法识别 REST 命令，则会引发 error_reply 异常。如果发生这种情况，只需调用 transfercmd() 而不带 rest 参数。

FTP.ntransfercmd(cmd, rest=None): 类似于 transfercmd()，但返回数据连接的元组和数据的预期大小。如果无法计算预期大小，None 将作为预期大小返回。 cmd 和 rest 与 transfercmd() 中的含义相同。

FTP.mlsd(path=, facts=[]): 使用 MLSD 命令 (RFC 3659) 以标准化格式列出目录。如果省略 path，则假定当前目录。 facts 是表示所需信息类型的字符串列表（例如 ["type", "size", "perm"]）。返回一个生成器对象，为路径中找到的每个文件生成一个包含两个元素的元组。第一个元素是文件名，第二个元素是包含有关文件名的事实的字典。此字典的内容可能受 facts 参数的限制，但不保证服务器返回所有请求的事实。

3.3 版中的新功能。

FTP.nlst(argument[, ...]): 返回由 NLST 命令返回的文件名列表。可选的参数是要列出的目录（默认为当前服务器目录）。可以使用多个参数将非标准选项传递给 NLST 命令。

笔记

如果您的服务器支持该命令，mlsd() 提供了更好的 API。

FTP.dir(argument[, ...]): 生成由 LIST 命令返回的目录列表，并将其打印到标准输出。可选的参数是要列出的目录（默认为当前服务器目录）。可以使用多个参数将非标准选项传递给 LIST 命令。如果最后一个参数是一个函数，它被用作 callback 函数作为 retrlines(); 默认打印到 sys.stdout。此方法返回 None。

笔记

如果您的服务器支持该命令，mlsd() 提供了更好的 API。

FTP.rename(fromname, toname): 将服务器上的文件 fromname 重命名为 toname。

FTP.delete(filename): 从服务器中删除名为 filename 的文件。如果成功，返回响应文本，否则在权限错误时引发 error_perm 或在其他错误时引发 error_reply。

FTP.cwd(pathname): 设置服务器上的当前目录。

FTP.mkd(pathname): 在服务器上创建一个新目录。

FTP.pwd(): 返回服务器上当前目录的路径名。

FTP.rmd(dirname): 删除服务器上名为 dirname 的目录。

FTP.size(filename): 请求服务器上名为 filename 的文件的大小。成功时，文件的大小作为整数返回，否则返回 None。请注意，SIZE 命令不是标准化的，但许多常见的服务器实现都支持。

FTP.quit(): 向服务器发送 QUIT 命令并关闭连接。这是关闭连接的“礼貌”方式，但如果服务器对 QUIT 命令响应错误，则可能会引发异常。这意味着调用 close() 方法，该方法使 FTP 实例对后续调用无用（见下文）。

FTP.close(): 单方面关闭连接。这不应应用于已经关闭的连接，例如在成功调用 quit() 之后。在此调用之后，不应再使用 FTP 实例（在调用 close() 或 quit() 之后，您不能通过发出另一个login() 方法）。

21.13.2. FTP_TLS 对象

FTP_TLS 类继承自 FTP，定义了这些附加对象：

FTP_TLS.ssl_version: 要使用的 SSL 版本（默认为 ssl.PROTOCOL_SSLv23）。

FTP_TLS.auth(): 使用 TLS 或 SSL 设置安全控制连接，具体取决于 ssl_version 属性中指定的内容。

在 3.4 版更改：该方法现在支持使用 ssl.SSLContext.check_hostname 和 Server Name Indication 进行主机名检查（请参阅 ssl.HAS_SNI ）。

FTP_TLS.ccc(): 将控制通道恢复为明文。这对于利用知道如何通过非安全 FTP 处理 NAT 而不打开固定端口的防火墙很有用。

3.3 版中的新功能。

FTP_TLS.prot_p(): 设置安全数据连接。

FTP_TLS.prot_c(): 设置明文数据连接。

21.13. ftplib — FTP 协议客户端 — Python 文档

21.13. ftplib — FTP 协议客户端

21.13.1. FTP 对象

21.13.2. FTP_TLS 对象