21.13 ftplib - FTP协议客户端

源代码： Lib / ftplib.py

此模块定义类FTP和一些相关项目。FTP类实现FTP协议的客户端。您可以使用它来编写执行各种自动FTP作业的Python程序，例如镜像其他FTP服务器。模块urllib.request也使用它来处理使用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类的新实例。当给定主机时，将调用connect(host)的方法。当给定用户时，另外方法调用login（user， passwd， acct） t1>（当未给出时，passwd和acct默认为空字符串）。可选的timeout参数指定阻塞操作（例如连接尝试）的超时（如果未指定，将使用全局默认超时设置）。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参数已添加。

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

如 RFC 4217中所述的FTP子类，它为FTP添加了TLS支持。像往常一样连接到端口21，在认证之前隐式地保护FTP控制连接。保护数据连接需要用户通过调用prot_p()方法显式地要求它。上下文是一个ssl.SSLContext对象，允许将SSL配置选项，证书和私钥捆绑到单个（可能长期）结构中。有关最佳做法，请参阅Security considerations。

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

版本3.2中的新功能。

在版本3.3中已更改： source_address参数已添加。

在版本3.4中更改：此类现在支持使用ssl.SSLContext.check_hostname和服务器名称指示（请参阅ssl.HAS_SNI）。

以下是使用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连接问题而引发的所有异常（作为元组）的集合（而不是调用者发出的编程错误）。此集包括上面列出的四个异常以及OSError。

也可以看看

模块netrc

解析.netrc文件格式。文件.netrc通常由FTP客户端用于在提示用户之前加载用户认证信息。

21.13.1. FTP对象

有几种方法有两种类型：一种用于处理文本文件，另一种用于二进制文件。这些命令以命令的形式命名，后面紧跟lines用于文本版本，binary用于二进制版本。

FTP实例具有以下方法：

FTP.set_debuglevel(level)

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

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

连接到给定的主机和端口。默认端口号为21，由FTP协议规范指定。很少需要指定其他端口号。对于每个实例，此函数只应调用一次；如果在创建实例时给出了主机，则不应该调用它。所有其他方法只能在连接完成后使用。可选的timeout参数指定连接尝试的超时（以秒为单位）。如果未传递超时，将使用全局默认超时设置。source_address是套接字绑定到其源地址的2元组（host， port） 连接。

在版本3.3中已更改： source_address参数已添加。

FTP.getwelcome()

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

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

以给定的用户登录。passwd和acct参数是可选的，默认为空字符串。如果未指定用户，则默认为'anonymous'。如果用户为'anonymous'，则默认passwd为'anonymous@'。在建立连接后，每个实例只应调用一次此函数；如果在创建实例时给出了主机和用户，则不应该调用它。大多数FTP命令仅在客户端登录后才允许。acct参数提供“会计信息”；很少有系统实现这一点。

FTP.abort()

中止正在进行的文件传输。使用这并不总是工作，但它值得一试。

FTP.sendcmd(cmd)

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

FTP.voidcmd(cmd)

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

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

以二进制传输模式检索文件。cmd应为适当的RETR命令：'RETR filename'。对于接收的每个数据块，调用回调函数，其中一个字符串参数给出数据块。可选的块大小参数指定在创建进行实际传输的低级套接字对象上读取的最大块大小（这也是传递到回调）。选择合理的默认值。rest表示与transfercmd()方法中的相同。

FTP.retrlines(cmd, callback=None)

在ASCII传输模式下检索文件或目录列表。cmd t>>应为适当的RETR命令（见retrbinary()）或命令，例如LIST或NLST（通常只是字符串'LIST'）。LIST检索文件列表和有关这些文件的信息。NLST检索文件名列表。每个具有字符串参数的行调用回调函数，该参数包含尾随CRLF被剥离的行。默认的回调会将行打印到sys.stdout。

FTP.set_pasv(boolean)

如果boolean为true，则启用“被动”模式，其他禁用被动模式。被动模式默认为开启。

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

以二进制传输模式存储文件。cmd应为适当的STOR命令：“STOR filename”。fp是大小为的块中使用其read()方法读取的EOF之前读取的file object块大小以提供要存储的数据。blocksize参数默认为8192. callback是一个可选的单个参数可调用，在每个数据块发送后调用。rest表示与transfercmd()方法中的相同。

在版本3.2中更改： rest参数添加。

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

以ASCII传输模式存储文件。cmd应为适当的STOR命令（请参阅storbinary()）。从file object fp（以二进制模式打开）使用readline()方法读取行，直到EOF为止，以提供要存储的数据。callback是一个可选的单个参数callable，在每行发送后调用。

FTP.transfercmd(cmd, rest=None)

通过数据连接启动传输。如果传输处于活动状态，请发送EPRT或PORT命令和cmd指定的传输命令，并接受连接。如果服务器是被动的，发送EPSV或PASV命令，连接到它，并启动传输命令。无论哪种方式，返回连接的套接字。

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

FTP.ntransfercmd(cmd, rest=None)

像transfercmd()，但返回数据连接的元组和数据的预期大小。如果无法计算预期大小，则会将None作为预期大小返回。cmd和rest表示与transfercmd()中相同的内容。

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

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

版本3.3中的新功能。

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

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

注意

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

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

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

注意

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

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()方法）。

21.13.2. FTP_TLS对象

FTP_TLS类继承自FTP，定义这些其他对象：

FTP_TLS.ssl_version

要使用的SSL版本（默认为ssl.PROTOCOL_SSLv23）。

FTP_TLS.auth()

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

在版本3.4中更改：此方法现在支持使用ssl.SSLContext.check_hostname和服务器名称指示进行主机名检查（请参阅ssl.HAS_SNI）。

FTP_TLS.ccc()

将控制通道恢复为纯文本。这可以有利于利用防火墙知道如何使用非安全FTP处理NAT，而无需打开固定端口。

版本3.3中的新功能。

FTP_TLS.prot_p()

设置安全数据连接。

FTP_TLS.prot_c()

设置明文数据连接。