ftplib ---FTP协议客户端

源代码: Lib/ftplib.py


此模块定义类 FTP 以及一些相关项目。这个 FTP 类实现ftp协议的客户端。您可以使用它来编写执行各种自动ftp任务(如镜像其他ftp服务器)的python程序。它也被模块使用 urllib.request 处理使用ftp的URL。有关ftp(文件传输协议)的详细信息,请参阅Internet。 RFC 959 .

默认编码是UTF-8,如下所示 RFC 2640 .

以下是使用 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
>>> 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()

该模块定义了以下各项:

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

返回的新实例 FTP 班级。什么时候? host 是给定的,方法调用 connect(host) 是做出来的。什么时候? user 另外,方法调用 login(user, passwd, acct) 被制造(在哪里) 通行证acct 未给定时默认为空字符串)。可选的 超时 参数指定阻塞操作(如连接尝试)的超时(以秒为单位)(如果未指定,将使用全局默认超时设置)。 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 已添加参数。

在 3.9 版更改: 如果 超时 参数设置为零,它将引发 ValueError 以防止创建非阻塞套接字。这个 编码 参数已添加,默认值已从Latin-1更改为UTF-8,如下所示 RFC 2640 .

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')

A FTP 向ftp添加tls支持的子类,如中所述 RFC 4217 . 像往常一样连接到端口21,在进行身份验证之前隐式地保护FTP控制连接。保护数据连接需要用户通过调用 prot_p() 方法。 context 是一个 ssl.SSLContext 对象,它允许将SSL配置选项、证书和私钥绑定到单个(可能是长期存在的)结构中。请阅读 安全注意事项 最佳实践。

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

3.2 新版功能.

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

在 3.4 版更改: 类现在支持主机名检查 ssl.SSLContext.check_hostname服务器名称指示 (见 ssl.HAS_SNI

3.6 版后已移除: 关键文件证书文件 被否决,赞成 context . 请使用 ssl.SSLContext.load_cert_chain() 相反,还是让 ssl.create_default_context() 为您选择系统的可信CA证书。

在 3.9 版更改: 如果 超时 参数设置为零,它将引发 ValueError 以防止创建非阻塞套接字。这个 编码 参数已添加,默认值已从Latin-1更改为UTF-8,如下所示 RFC 2640 .

以下是使用 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连接的问题而引发(与调用方所做的编程错误相反)。此集合包括上面列出的四个例外以及 OSErrorEOFError .

参见

模块 netrc

语法分析器 .netrc 文件格式。文件 .netrc 通常由ftp客户机用于在提示用户之前加载用户身份验证信息。

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) 以便在连接前将套接字绑定到作为其源地址。

提出一个 auditing event ftplib.connect 带着论据 selfhostport .

在 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)

向服务器发送一个简单的命令字符串并返回响应字符串。

提出一个 auditing event ftplib.sendcmd 带着论据 selfcmd .

FTP.voidcmd(cmd)

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

提出一个 auditing event ftplib.sendcmd 带着论据 selfcmd .

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

以二进制传输模式检索文件。 cmd 应该是适当的 RETR 命令: 'RETR filename' . 这个 回调 对接收到的每个数据块调用函数,并用一个单字节参数给出数据块。可选的 块状 参数指定在为进行实际传输而创建的低级套接字对象上要读取的最大块大小(它也是传递到的数据块的最大大小) 回调 )选择合理的违约。 rest 意思与 transfercmd() 方法。

FTP.retrlines(cmd, callback=None)

编码 初始化时的参数。 cmd 应该是适当的 RETR 命令(见) retrbinary() )或命令,如 LISTNLST (通常只是绳子 'LIST'LIST 检索文件列表和有关这些文件的信息。 NLST 检索文件名列表。这个 回调 为每行调用一个函数,该函数的字符串参数包含去掉尾随CRLF的行。默认值 回调 将行打印到 sys.stdout .

FTP.set_pasv(val)

启用“被动”模式,如果 val 为真,否则禁用被动模式。被动模式默认为打开。

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

以二进制传输模式存储文件。 cmd 应该是适当的 STOR 命令: "STOR filename" . fp 是一个 file object (以二进制模式打开)直到使用其 read() 块大小的方法 块状 提供要存储的数据。这个 块状 参数默认为8192。 回调 是一个可选的单参数可调用文件,在发送每个数据块后对其进行调用。 rest 意思与 transfercmd() 方法。

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

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

Store a file in line mode. cmd should be an appropriate STOR command (see storbinary()). Lines are read until EOF from the file object fp (opened in binary mode) using its readline() method to provide the data to be stored. callback is an optional single parameter callable that is called on each line after it is sent.

FTP.transfercmd(cmd, rest=None)

通过数据连接启动传输。如果传输处于活动状态,则发送 EPRTPORT 命令和指定的传输命令 cmd ,并接受连接。如果服务器是被动的,则发送一个 EPSVPASV 命令,连接到它,然后启动传输命令。无论哪种方式,都要返回连接的Socket。

如果可选 rest 给出了 REST 命令被发送到服务器,通过 rest 作为一个论点。 rest 通常是请求文件的字节偏移量,告诉服务器在请求的偏移量处重新发送文件的字节,跳过初始字节。但是请注意 transfercmd() 方法转换 rest 一根绳子 编码 初始化时指定的参数,但不检查字符串的内容。如果服务器无法识别 REST 命令 error_reply 将引发异常。如果发生这种情况,只需打电话 transfercmd() 没有 rest 争论。

FTP.ntransfercmd(cmd, rest=None)

类似于 transfercmd() ,但返回数据连接的元组和预期的数据大小。如果无法计算预期大小, None 将按预期大小返回。 cmdrest 意思和 transfercmd() .

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

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

3.3 新版功能.

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

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

注解

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

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

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

注解

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

FTP.rename(fromname, toname)

重命名文件 来自名字 在服务器上 托纳姆 .

FTP.delete(filename)

删除名为的文件 filename 从服务器。如果成功,则返回响应的文本,否则引发 error_perm 权限错误或 error_reply 其他错误。

FTP.cwd(pathname)

在服务器上设置当前目录。

FTP.mkd(pathname)

在服务器上创建新目录。

FTP.pwd()

返回服务器上当前目录的路径名。

FTP.rmd(dirname)

删除名为的目录 目录名 在服务器上。

FTP.size(filename)

请求名为的文件的大小 filename 在服务器上。一旦成功,文件的大小将作为整数返回,否则 None 返回。请注意 SIZE 命令不是标准化的,但许多常见的服务器实现都支持它。

FTP.quit()

发送一个 QUIT 命令并关闭连接。这是关闭连接的“礼貌”方式,但如果服务器对 QUIT 命令。这意味着调用 close() 呈现 FTP 实例对后续调用无效(请参见下文)。

FTP.close()

单方面关闭连接。这不应应用于已关闭的连接,例如在成功调用 quit() . 在这个调用之后 FTP 不应再使用实例(在调用 close()quit() 无法通过发出另一个连接来重新打开连接 login() 方法)。

FTPTTLS对象

FTP_TLS 类继承自 FTP ,定义这些附加对象:

FTP_TLS.ssl_version

要使用的SSL版本(默认为 ssl.PROTOCOL_SSLv23

FTP_TLS.auth()

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

在 3.4 版更改: 该方法现在支持主机名检查 ssl.SSLContext.check_hostname服务器名称指示 (见 ssl.HAS_SNI

FTP_TLS.ccc()

将控制通道还原为纯文本。这对于利用知道如何在不打开固定端口的情况下使用不安全的ftp处理nat的防火墙很有用。

3.3 新版功能.

FTP_TLS.prot_p()

设置安全数据连接。

FTP_TLS.prot_c()

设置明文数据连接。