python3 ftplib_python3从零学习-5.10.9、ftplib—FTP 协议客户端

源代码： Lib/ftplib.py

这个模块定义类FTP和一些相关项。FTP类实现FTP协议的客户端。您可以使用它编写Python程序来执行各种自动FTP作业，比如镜像其他FTP服务器。模块urllib也使用它。请求处理使用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)(其中passwd和acct在未给定时默认为空字符串)。可选的超时参数指定阻塞操作(如连接尝试)的超时时间(以秒为单位)(如果未指定，将使用全局默认超时设置)。source_address是套接字在连接之前要绑定到的一个2元组(主机、端口)。

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)

RFC 4217中描述的一个FTP子类，它将TLS支持添加到FTP中。像往常一样连接到端口21，在身份验证之前隐式地保护FTP控制连接。保护数据连接需要用户通过调用prot_p()方法显式地请求它。上下文是一个ssl。对象，允许将SSL配置选项、证书和私钥绑定到单个(可能是长期存在的)结构中。请阅读安全考虑最佳做法。

keyfile和certfile是上下文的遗留替代方案——它们可以(分别)指向SSL连接的py格式的私钥和证书链文件。

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。

FTP 对象

有两种方法可用:一种用于处理文本文件，另一种用于处理二进制文件。它们以命令命名，文本版本使用命令后跟行，二进制版本使用二进制。

FTP实例有以下方法:

FTP.set_debuglevel(level)

设置实例的调试级别。它控制打印的调试输出的数量。默认值0不产生任何调试输出。值为1会产生适当数量的调试输出，通常每个请求只有一行。2或更高的值将生成调试输出的最大数量，记录控制连接上发送和接收的每一行。

FTP.connect(host='', port=0, timeout=None, source_address=None)

连接到给定的主机和端口。默认端口号是21，由FTP协议规范指定。很少需要指定不同的端口号。对于每个实例，该函数只能调用一次;如果在创建实例时提供了主机，则根本不应该调用它。所有其他方法只能在建立连接之后使用。可选的超时参数指定连接尝试的超时时间(秒)。如果没有超时，将使用全局默认超时设置。source_address是套接字在连接之前要绑定到的一个2元组(主机、端口)。

FTP.getwelcome()

返回服务器为响应初始连接而发送的欢迎消息。(此消息有时包含可能与用户相关的免责声明或帮助信息。)

FTP.login(user='anonymous', passwd='', acct='')

作为给定的用户登录。passwd和acct参数是可选的，默认为空字符串。如果没有指定用户，默认为“匿名”。如果用户是“匿名”，默认密码是“anonymous@”。在建立连接之后，每个实例只应该调用该函数一次;如果在创建实例时提供了主机和用户，则根本不应该调用该实例。大多数FTP命令只允许在客户端登录后执行。会计参数提供“会计信息”;很少有系统实现这一点。

FTP.abort()

中止正在进行的文件传输。使用这种方法并不总是有效，但值得一试。

FTP.sendcmd(cmd)

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

FTP.voidcmd(cmd)

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

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

检索二进制传输模式的文件。cmd应该是一个适当的RETR命令:'RETR filename'。对接收到的每个数据块调用回调函数，并使用单个字节参数给出数据块。可选的blocksize参数指定在创建来执行实际传输的低级套接字对象上读取的最大块大小(它也将是传递给回调的数据块的最大大小)。选择一个合理的默认值。rest的意思与transfercmd()方法中的意思相同。

FTP.retrlines(cmd, callback=None)

检索ASCII传输模式下的文件或目录列表。cmd应该是一个合适的RETR命令(参见retrbinary())，或者一个命令，比如LIST或NLST(通常只是字符串'LIST')。LIST检索文件列表和有关这些文件的信息。NLST检索文件名列表。对每一行调用回调函数，其中的字符串参数包含尾部去掉CRLF的行。默认的回调将该行打印到sys.stdout。

FTP.set_pasv(val)

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

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

以二进制传输模式存储文件。cmd应该是一个合适的STOR命令:“STOR文件名”。fp是一个文件对象(以二进制模式打开)，直到EOF使用它的read()方法在区块大小块中提供要存储的数据。blocksize参数默认值为8192。callback是一个可调用的可选参数，在每个数据块被发送后被调用。rest的意思与transfercmd()方法中的意思相同。

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

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

FTP.transfercmd(cmd, rest=None)

启动数据连接上的传输。如果传输是活动的，发送EPRT或端口命令和cmd指定的传输命令，并接受连接。如果服务器是被动的，发送EPSV或PASV命令，连接到它，并启动transfer命令。无论哪种方式，都返回连接的套接字。

如果提供了可选的rest，则将rest命令发送到服务器，并将rest作为参数传递。rest通常是请求文件中的一个字节偏移量，它告诉服务器在请求的偏移量处重新开始发送文件的字节，跳过初始字节。但是请注意，RFC 959只要求rest是包含可打印范围从ASCII码33到ASCII码126的字符的字符串。因此，transfercmd()方法将rest转换为字符串，但是不检查字符串的内容。如果服务器不识别REST命令，将引发error_reply异常。如果发生这种情况，只需调用transfercmd()而不使用rest参数。

FTP.ntransfercmd(cmd, rest=None)

启动数据连接上的传输。如果传输是活动的，发送EPRT或端口命令和cmd指定的传输命令，并接受连接。如果服务器是被动的，发送EPSV或PASV命令，连接到它，并启动transfer命令。无论哪种方式，都返回连接的套接字。

与transfercmd()类似，但是返回数据连接的元组和数据的预期大小。如果无法计算预期大小，则不会返回预期大小。cmd和rest与transfercmd()中的意思相同。

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

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

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

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

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

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

FTP.rename(fromname, toname)

将服务器上的文件从name重命名为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的文件的大小。如果成功，文件的大小将以整数的形式返回，否则将不返回。注意，SIZE命令不是标准化的，但是许多常见的服务器实现都支持它。

FTP.quit()

向服务器发送一个QUIT命令并关闭连接。这是关闭连接的“礼貌”方式，但如果服务器对QUIT命令响应错误，则可能引发异常。这意味着对close()方法的调用将使FTP实例对后续调用无效(参见下面)。

FTP.close()

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