ftplib
ftplib — FTP protocol client
源代码:
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)
(其中passwd
和acct
在未给出时默认为空字符串)。可选的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
keyfile
和certfile
是上下文
的传统替代方案- 它们可以指向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
由于FTP
FTP
连接的问题(与调用者编程错误相对),实例方法可能引发的所有异常(作为元组)的集合。该组包括上面列出的四个例外以及socket.error
和IOError
。
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()
)或诸如命令
LIST
,NLST
或者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])
通过数据连接启动传输。如果传输是有效的,发送一个EPRT
或PORT
命令,并通过指定的传输命令CMD
,并接受该连接。如果服务器是被动的,则发送EPSV
或PASV
命令,连接到它并启动传输命令。无论哪种方式,返回连接的套接字。
如果给出可选休息
,则将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()
设置明文数据连接。