ftplib — FTP 协议客户端¶
源代码: Lib/ftplib.py
该模块定义了 FTP 类和一些相关项。FTP 类实现了 FTP 协议的客户端部分。 你可以使用它来编写执行各种自动化 FTP 作业的 Python 程序，例如镜像其他 FTP 服务器。 它也被模块 urllib.request 用于处理使用 FTP 的 URL。 有关 FTP（文件传输协议）的更多信息，请参阅互联网 RFC 959。
默认编码是 UTF-8，遵循 RFC 2640。
可用性: 非 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) – 用于登录的用户名（默认值：
'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方法。- 参数：
引发一个审计事件
ftplib.connect，参数为self、host和port。在 3.3 版本中更改: 添加了 source_address 参数。
- getwelcome()¶
返回服务器在初始连接时发送的欢迎消息。（此消息有时包含可能与用户相关的免责声明或帮助信息。）
- login(user='anonymous', passwd='', acct='')¶
登录到连接的 FTP 服务器。此函数对于每个实例应仅调用一次，在建立连接后调用；如果在创建
FTP实例时已提供 host 和 user 参数，则不应调用此函数。大多数 FTP 命令仅在客户端登录后才允许执行。
- abort()¶
中止正在进行的文件传输。使用此方法并非总是有效，但值得一试。
- voidcmd(cmd)¶
向服务器发送一个简单的命令字符串并处理响应。如果响应代码对应于成功（代码范围在 200-299 之间），则返回响应字符串。否则，引发
error_reply异常。引发一个审计事件
ftplib.sendcmd，参数为self和cmd。
- 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()）。使用readline()方法从 文件对象 fp（以二进制模式打开）中读取行，直到 EOF，以提供要存储的数据。 callback 是一个可选的单参数可调用对象，在每行发送后调用。
- transfercmd(cmd, rest=None)¶
通过数据连接启动传输。如果传输处于活动状态，则发送
EPRT或PORT命令和 cmd 指定的传输命令，并接受连接。如果服务器处于被动模式，则发送EPSV或PASV命令，连接到它并启动传输命令。无论哪种方式，都返回连接的套接字。如果提供了可选的 rest 参数，则会向服务器发送一个
REST命令，并将 rest 作为参数传递。rest 通常是请求文件中的字节偏移量，告诉服务器从请求的偏移量处重新开始发送文件的字节，跳过初始字节。但请注意，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 参数的限制，但不保证服务器返回所有请求的信息。在 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 参数，并且为了遵循 RFC 2640，默认值从 Latin-1 更改为 UTF-8。在版本 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 客户端在提示用户之前加载用户身份验证信息。