ftplib --- FTP 协议客户端¶
源代码： Lib/ftplib.py
此模块定义了 FTP 类和一些相关的条目。FTP 类实现了 FTP 协议的客户端。你可以用它来编写 Python 程序，执行各种自动化的 FTP 任务，比如镜像其他 FTP 服务器。它也被 urllib.request 模块用于处理使用 FTP 的 URL。有关 FTP（文件传输协议）的更多信息，请参阅互联网 RFC 959。
遵循 RFC 2640，默认编码为 UTF-8。
可用性：非 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 是空字符串或
"-"，则会自动生成一个密码。timeout (float | None) -- 阻塞操作（如
connect()）的超时时间，单位为秒（默认：全局默认超时设置）。source_address (tuple | None) -- 一个二元组
(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 为真，启用“被动”模式，否则禁用被动模式。被动模式默认开启。
- 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)¶
以行模式存储文件。cmd 应该是一个合适的
STOR命令（参见storbinary()）。使用 file object 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"]）。返回一个生成器对象，为在 path 中找到的每个文件生成一个包含两个元素的元组。第一个元素是文件名，第二个元素是一个包含有关文件名事实的字典。此字典的内容可能受 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 是空字符串或
"-"，则会自动生成一个密码。context (
ssl.SSLContext) -- 一个 SSL 上下文对象，允许将 SSL 配置选项、证书和私钥捆绑到一个单一的、可能长期存在的结构中。请阅读 安全考量 以了解最佳实践。timeout (float | None) -- 阻塞操作（如
connect()）的超时时间，单位为秒（默认：全局默认超时设置）。source_address (tuple | None) -- 一个二元组
(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()¶
根据
ssl_version属性中的指定，使用 TLS 或 SSL 建立一个安全的控制连接。在 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文件格式的解析器。FTP 客户端通常使用.netrc文件在提示用户之前加载用户认证信息。