ftplib

源代码: Lib / ftplib.py

这个模块定义了类FTP和一些相关的项目。的FTP类实现FTP协议的客户端。您可以使用它来编写执行各种自动FTP作业的Python程序,例如镜像其他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]]]]])

返回FTP该类的新实例。当给出主机时,进行方法调用connect(host)。当给出用户时,另外进行方法调用login(user, passwd, acct)(其中passwdacct在未给出时默认为空字符串)。可选的timeout参数指定阻止诸如连接尝试之类的操作的超时时间(以秒为单位)(如果未指定,则将使用全局默认超时设置)。

在版本2.6中更改:添加了超时

class ftplib.FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])

RFC 4217中FTP所述,将TLS支持添加到FTP的子类。照常连接到端口21,在认证之前隐式保护FTP控制连接。保护数据连接需要用户通过调用方法明确要求它。上下文是一个允许将SSL配置选项,证书和私钥绑定到一个(可能长寿命)的结构中的对象。请阅读最佳实践的安全考虑事项。prot_p()ssl.SSLContext

keyfilecertfile上下文的传统替代方案- 它们可以指向PEM格式的私钥和证书链文件(分别为SSL连接)。

2.7版本的新功能。

在版本2.7.10中更改:已添加上下文参数。

以下是使用FTP_TLS该类的示例会话:

>>> from ftplib import FTP_TLS
>>> ftps = FTP_TLS('ftp.python.org')
>>> ftps.login()           # login anonymously before securing control channel
>>> ftps.prot_p()          # switch to secure data connection
>>> ftps.retrlines('LIST') # list directory content securely
total 9
drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 .
drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 ..
drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 bin
drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 etc
d-wxrwxr-x   2 ftp      wheel        1024 Sep  5 13:43 incoming
drwxr-xr-x   2 root     wheel        1024 Nov 17  1993 lib
drwxr-xr-x   6 1094     wheel        1024 Sep 13 19:07 pub
drwxr-xr-x   3 root     wheel        1024 Jan  3  1994 usr
-rw-r--r--   1 root     root          312 Aug  1  1994 welcome.msg
'226 Transfer complete.'
>>> ftps.quit()
>>>

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

由于FTPFTP连接的问题(与调用者编程错误相对),实例方法可能引发的所有异常(作为元组)的集合。该组包括上面列出的四个例外以及socket.errorIOError

1. FTP对象

有两种方法可用,一种用于处理文本文件,另一种用于处理二进制文件。这些命令用于lines文本版本或binary二进制版本所使用的命令。

FTP 实例具有以下方法:

FTP.set_debuglevel(level)

设置实例的调试级别。这将控制打印的调试输出量。缺省值,0不会产生调试输出。一个值1会产生适量的调试输出,通常每个请求只有一行。值2或更高值会产生最大量的调试输出,记录控制连接上发送和接收的每条线路。

FTP.connect(host[, port[, timeout]])

连接到给定的主机和端口。默认端口号是21由FTP协议规范指定的。很少需要指定不同的端口号。每个实例只能调用一次该函数; 如果在创建实例时提供主机,则根本不应该调用它。所有其他方法只能在连接完成后使用。

可选的timeout参数指定连接尝试的超时时间(以秒为单位)。如果没有超时通过,则将使用全局默认超时设置。

在版本2.6中更改:添加了超时

FTP.getwelcome()

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

FTP.login([user[, passwd[, acct]]])

以给定的用户身份登录。将passwd文件ACCT参数是可选的,默认为空字符串。如果没有指定用户,则默认为'anonymous'。如果用户'anonymous',则默认密码'anonymous@'。连接建立后,每个实例只能调用一次该函数; 如果在创建实例时提供主机和用户,则根本不应该调用它。大多数FTP命令仅在客户端登录后才被允许。acct参数提供“会计信息”; 很少有系统实施这个。

FTP.abort()

中止正在进行的文件传输。使用它并不总是奏效,但值得一试。

FTP.sendcmd(command)

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

FTP.voidcmd(command)

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

FTP.retrbinary(command, callback[, maxblocksize[, rest]])

以二进制传输模式检索文件。命令应该是一个合适的RETR命令:'RETR filename'。该回调函数被调用用于接收,具有一个字符串参数给出数据块的每个数据块。可选的maxblocksize参数指定要在执行实际传输(也将传递给回调的数据块的最大大小)时创建的低级套接字对象上读取的最大块大小。选择合理的默认值。休息意味着与该transfercmd()方法中的相同。

FTP.retrlines(command[, callback])

以ASCII传输模式检索文件或目录列表。命令应该是一个适当的RETR命令(参见retrbinary())或诸如命令LISTNLST或者MLSD(通常只是字符串'LIST')。LIST检索文件列表和关于这些文件的信息。NLST检索文件名列表。在某些服务器上,MLSD检索机器可读的文件列表和关于这些文件的信息。该回调函数被调用用含有与剥离尾部CRLF行字符串参数的每一行。默认回调打印该行sys.stdout

FTP.set_pasv(val)

如果val为true,则启用“被动”模式,否则禁用被动模式。(在Python 2.0和之前的版本中,默认情况下被动模式是关闭的;在Python 2.1和更高版本中,默认情况下它是开启的。)

FTP.storbinary(command, fp[, blocksize, callback, rest])

以二进制传输模式存储文件。命令应该是一个合适的STOR命令:"STOR filename"fp是一个打开的文件对象,使用它的read()方法以块大小块的形式读取,直到EOF ,以提供要存储的数据。该块大小参数默认为8192。回调是一个可选的单参数调用它被发送后调用数据的每块上。休息意味着与该transfercmd()方法中的相同。

在版本2.1中进行了更改:添加了块大小的默认值。

在版本2.6中更改:添加了回调参数。

在版本2.7中更改:添加了rest参数。

FTP.storlines(command, fp[, callback])

以ASCII传输模式存储文件。命令应该是一个合适的STOR命令(参见storbinary())。从打开的文件对象fp使用其readline()方法提供要存储的数据读取直到EOF 。回调函数是一个可选的单个参数,在每一行发送后都会调用它。

在版本2.6中更改:添加了回调参数。

FTP.transfercmd(cmd[, rest])

通过数据连接启动传输。如果传输是有效的,发送一个EPRTPORT命令,并通过指定的传输命令CMD,并接受该连接。如果服务器是被动的,则发送EPSVPASV命令,连接到它并启动传输命令。无论哪种方式,返回连接的套接字。

如果给出可选休息,则将REST命令发送到服务器,并将休息作为参数传递。休息通常是一个字节偏移到请求的文件,告诉服务器重新启动发送文件的字节在请求的偏移量,跳过最初的字节。但请注意,RFC 959仅要求其余字符包含ASCII码33到ASCII码126的可打印范围内的字符transfercmd()。因此,该方法将rest转换为字符串,但不对字符串的内容执行检查。如果服务器不能识别该REST命令,error_reply则会引发异常。如果发生这种情况,只需拨打transfercmd()没有休息 论据。

FTP.ntransfercmd(cmd[, rest])

就像transfercmd(),但返回数据连接的元组和数据的预期大小。如果无法计算预期的大小,None将按预期的大小返回。cmd休息意味着与在中相同的东西transfercmd()

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

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

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

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

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()方法重新打开连接)。

2. FTP_TLS Objects

FTP_TLS类继承FTP,定义这些额外的对象:

FTP_TLS.ssl_version

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

FTP_TLS.auth()

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

FTP_TLS.prot_p()

建立安全的数据连接。

FTP_TLS.prot_c()

设置明文数据连接。

扫码关注云+社区

领取腾讯云代金券