ftplib — FTP 协议客户端¶
源代码： Lib/ftplib.py
此模块定义了类 FTP 和一些相关项目。 FTP 类实现了 FTP 协议的客户端。您可以使用它来编写执行各种自动化 FTP 作业的 Python 程序，例如镜像其他 FTP 服务器。它也被模块 urllib.request 使用来处理使用 FTP 的 URL。有关 FTP（文件传输协议）的更多信息，请参阅互联网 RFC 959。
默认编码为 UTF-8，遵循 RFC 2640。
可用性：不支持 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) – 用于登录的用户名（默认值：
'anonymous'）。如果给出，构造函数会隐式调用login(host, passwd, acct)。passwd (str) – 登录时使用的密码。如果未给出，并且如果 passwd 为空字符串或
"-"，则会自动生成密码。acct (str) – 用于
ACCTFTP 命令的帐户信息。很少有系统实现这一点。有关更多详细信息，请参阅 RFC-959。timeout (float | None) – 用于阻塞操作（如
connect()）的超时时间（以秒为单位）（默认值：全局默认超时设置）。source_address (tuple | None) – 套接字在连接之前绑定为其源地址的 2 元组
(host, port)。encoding (str) – 目录和文件名的编码（默认值：
'utf-8'）。
>>> 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以防止创建非阻塞套接字。添加了 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方法只能在成功建立连接后才能调用。- 参数：
引发带有参数
self、host、port的 审计事件ftplib.connect。在 3.3 版更改: 添加了 source_address 参数。
- getwelcome()¶
返回服务器在响应初始连接时发送的欢迎消息。（此消息有时包含可能与用户相关的免责声明或帮助信息。）
- login(user='anonymous', passwd='', acct='')¶
登录到已连接的 FTP 服务器。此函数应在每个实例中只调用一次，在建立连接后；如果在创建
FTP实例时已给出 host 和 user 参数，则不应调用此函数。大多数 FTP 命令只有在客户端登录后才允许使用。
- abort()¶
中止正在进行的文件传输。使用此方法并不总是有效，但值得一试。
- voidcmd(cmd)¶
向服务器发送一个简单的命令字符串并处理响应。如果响应代码对应于成功（代码在 200-299 范围内），则返回响应字符串。否则引发
error_reply。引发带有参数
self、cmd的 审计事件ftplib.sendcmd。
- retrbinary(cmd, callback, blocksize=8192, rest=None)¶
以二进制传输模式检索文件。
- retrlines(cmd, callback=None)¶
以初始化时 encoding 参数指定的编码检索文件或目录列表。cmd 应该是一个适当的
RETR命令（请参阅retrbinary()）或LIST或NLST等命令（通常只是字符串'LIST'）。LIST检索文件列表和有关这些文件的信息。NLST检索文件名列表。对于每一行，都会调用 callback 函数，该函数带有一个字符串参数，其中包含已删除尾随 CRLF 的行。默认的 callback 会将该行打印到sys.stdout。
- set_pasv(val)¶
如果 val 为 true，则启用“被动”模式，否则禁用被动模式。默认情况下，被动模式处于启用状态。
- storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)¶
以二进制传输模式存储文件。
- 参数：
在版本 3.2 中更改: 添加了 rest 参数。
- storlines(cmd, fp, callback=None)¶
以行模式存储文件。cmd 应该是合适的
STOR命令（请参阅storbinary()）。使用 文件对象 fp（以二进制模式打开）的readline()方法读取行，直到 EOF，以提供要存储的数据。callback 是一个可选的单参数可调用对象，在发送每一行后调用。
- transfercmd(cmd, rest=None)¶
通过数据连接启动传输。如果传输处于活动状态，则发送
EPRT或PORT命令和 cmd 指定的传输命令，并接受连接。如果服务器是被动的，则发送EPSV或PASV命令，连接到它，并启动传输命令。无论哪种方式，都返回连接的套接字。如果给出了可选的 rest，则向服务器发送
REST命令，并将 rest 作为参数传递。rest 通常是请求文件中的字节偏移量，告诉服务器从请求的偏移量开始重新发送文件的字节，跳过初始字节。但是请注意，transfercmd()方法使用初始化时指定的 encoding 参数将 rest 转换为字符串，但不对字符串的内容执行检查。如果服务器无法识别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 参数的限制，但不能保证服务器会返回所有请求的信息。3.3 版新增。
- nlst(argument[, ...])¶
返回
NLST命令返回的文件名列表。可选的 argument 是要列出的目录（默认为当前服务器目录）。可以使用多个参数将非标准选项传递给NLST命令。注意
如果您的服务器支持该命令，则
mlsd()提供了更好的 API。
- dir(argument[, ...])¶
生成
LIST命令返回的目录列表，并将其打印到标准输出。可选的 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命令未标准化，但许多常见的服务器实现都支持它。
FTP_TLS 对象¶
- class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')¶
一个
FTP子类，它按照 RFC 4217 中的描述为 FTP 添加了 TLS 支持。隐式连接到端口 21，在身份验证之前保护 FTP 控制连接的安全。注意
用户必须通过调用
prot_p()方法显式保护数据连接的安全。- 参数：
host (str) – 要连接的主机名。如果给出，构造函数会隐式调用
connect(host)。user (str) – 用于登录的用户名（默认值：
'anonymous'）。如果给出，构造函数会隐式调用login(host, passwd, acct)。passwd (str) – 登录时使用的密码。如果未给出，并且如果 passwd 为空字符串或
"-"，则会自动生成密码。acct (str) – 用于
ACCTFTP 命令的帐户信息。很少有系统实现这一点。有关更多详细信息，请参阅 RFC-959。context (
ssl.SSLContext) – 一个 SSL 上下文对象，允许将 SSL 配置选项、证书和私钥捆绑到一个可能长期存在的结构中。有关最佳实践，请阅读 安全注意事项。timeout (float | None) – 用于阻塞操作（如
connect()）的超时时间（以秒为单位）（默认值：全局默认超时设置）。source_address (tuple | None) – 套接字在连接之前绑定为其源地址的 2 元组
(host, port)。encoding (str) – 目录和文件名的编码（默认值：
'utf-8'）。
3.2 版新增。
在 3.3 版更改: 添加了 source_address 参数。
在 3.4 版更改: 该类现在支持使用
ssl.SSLContext.check_hostname和*服务器名称指示*（请参阅ssl.HAS_SNI）进行主机名检查。在 3.9 版更改: 如果将 timeout 参数设置为零，它将引发
ValueError以防止创建非阻塞套接字。添加了 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()¶
通过使用 TLS 或 SSL 建立安全的控制连接，具体取决于
ssl_version属性中的指定。在 3.4 版更改: 该方法现在支持使用
ssl.SSLContext.check_hostname和*服务器名称指示*（请参阅ssl.HAS_SNI）进行主机名检查。
- ccc()¶
将控制通道恢复为明文。这对于利用防火墙很有用，这些防火墙知道如何在不打开固定端口的情况下处理非安全 FTP 的 NAT。
3.3 版新增。
- prot_p()¶
建立安全的数据连接。
- prot_c()¶
建立明文数据连接。
模块变量¶
- 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 客户端在提示用户之前加载用户身份验证信息。