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)（其中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

由于FTPFTP连接的问题（与调用者编程错误相对），实例方法可能引发的所有异常（作为元组）的集合。该组包括上面列出的四个例外以及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()

设置明文数据连接。