Skip to main content

21.13. ftplib — FTP协议客户端

源代码: Lib/ftplib.py


此模块定义类 FTP 和一些相关项。 FTP 类实现FTP协议的客户端。您可以使用它来编写执行各种自动FTP作业的Python程序,例如镜像其他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) (其中 passwdacct 在未给出时默认为空字符串)。可选的 timeout 参数指定阻塞操作(如连接尝试)的超时(如果未指定,将使用全局默认超时设置)。 source_address 是一个2元组 (host, port),用于在连接之前将套接字绑定为其源地址。

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 参数。

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配置选项,证书和私钥捆绑到单个(可能长期)结构中。请阅读 安全注意事项 的最佳做法。

keyfilecertfilecontext 的传统替代品 - 它们可以分别指向用于SSL连接的PEM格式的私钥和证书链文件。

3.2 新版功能.

在 3.3 版更改: 添加了 source_address 参数。

在 3.4 版更改: 该类现在支持使用 ssl.SSLContext.check_hostname服务器名称指示 进行主机名检查(请参阅 ssl.HAS_SNI)。

3.6 版后已移除: keyfilecertfile 不赞成使用 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='')

作为给定的 user 登录。 passwdacct 参数是可选的,默认为空字符串。如果没有指定 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())或一个命令,如 LISTNLST (通常只是字符串 'LIST')。 LIST 检索文件列表和有关这些文件的信息。 NLST 检索文件名列表。 callback 函数被调用每个行与一个字符串参数包含尾随CRLF剥离的行。默认 callback 将线打印到 sys.stdout

FTP.set_pasv(boolean)

如果 boolean 为真,则启用“被动”模式,其他禁用被动模式。被动模式默认为开启。

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

以二进制传输模式存储文件。 cmd 应该是一个合适的 STOR 命令:"STOR filename"fpfile object (以二进制模式打开),其在大小为 blocksize 的块中使用其 read() 方法读取直到EOF以提供要存储的数据。 blocksize 参数默认为8192. callback 是一个可选的单个参数可调用,它在每个数据块发送后调用。 rest 表示与 transfercmd() 方法中相同的事情。

在 3.2 版更改: rest 参数添加。

FTP.storlines(cmd, fp, callback=None)

以ASCII传输模式存储文件。 cmd 应该是一个合适的 STOR 命令(参见 storbinary())。读取行,直到来自 file object fp 的EOF(以二进制模式打开),使用其 readline() 方法提供要存储的数据。 callback 是可选的单个参数可调用,在发送后在每一行上调用。

FTP.transfercmd(cmd, rest=None)

通过数据连接启动传输。如果传输活动,请发送 EPRTPORT 命令和 cmd 指定的传输命令,并接受连接。如果服务器是被动的,发送 EPSVPASV 命令,连接到它,并启动传输命令。无论哪种方式,返回连接的套接字。

如果给出了可选的 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 将作为预期大小返回。 cmdrest 的含义与 transfercmd() 中的含义相同。

FTP.mlsd(path="", facts=[])

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

3.3 新版功能.

FTP.nlst(argument[, ...])

返回 NLST 命令返回的文件名列表。可选的 argument 是要列出的目录(默认是当前服务器目录)。多个参数可用于将非标准选项传递给 NLST 命令。

注解

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

FTP.dir(argument[, ...])

生成由 LIST 命令返回的目录列表,将其打印到标准输出。可选的 argument 是要列出的目录(默认是当前服务器目录)。多个参数可用于将非标准选项传递给 LIST 命令。如果最后一个参数是一个函数,则它被用作 retrlines()callback 函数;默认打印到 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()

根据 ssl_version 属性中指定的内容,使用TLS或SSL设置安全控制连接。

在 3.4 版更改: 该方法现在支持使用 ssl.SSLContext.check_hostname服务器名称指示 进行主机名检查(请参阅 ssl.HAS_SNI)。

FTP_TLS.ccc()

将控制通道恢复为纯文本。这可能有利于利用防火墙知道如何使用非安全FTP处理NAT,而无需打开固定端口。

3.3 新版功能.

FTP_TLS.prot_p()

设置安全数据连接。

FTP_TLS.prot_c()

设置明文数据连接。