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 pooldrwxr-sr-x    4 1176     1176         4096 Nov 17  2008 projectdrwxr-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默认为空字符串，如果没有给出）。可选的timeout参数指定阻塞操作（如连接尝试）的超时秒数（如果未指定，则将使用全局默认超时设置）。source_address在连接之前，它是一个2元组(host, port)用于socketto绑定到它的源地址.

FTP类支持with语句，例如：

>>> from ftplib import FTP>>> with FTP("ftp1.at.proftpd.org") as ftp:...     ftp.login()...     ftp.dir()... # doctest: +SKIP"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 CentOSdr-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）

一个FTP子类，它添加了对FTP的TLS支持，如 RFC 4217 。像往常一样连接到端口21，在进行身份验证之前隐式保护FTP控制连接。保护数据连接需要用户通过调用prot_p()方法明确地要求它。context是一个ssl.SSLContext对象，它允许将SSL配置选项，证书和私钥捆绑到一个（可能是长寿命的）结构中。请阅读安全考虑以获得最佳实践.

keyfile和certfile是context的传统替代品 – 他们可以指向PEM-SSL连接的格式化私钥和证书链文件（分别）.

新版本3.2.

改版3.3：source_address参数被添加了

版本3.4更改：该类现在支持使用ssl.SSLContext.check_hostname和Server Name Indication（看到ssl.HAS_SNI）.

从版本3.6开始不推荐使用：keyfile和certfile不赞成使用context。请改用ssl.SSLContext.load_cert_chain()，或者让ssl.create_default_context()为您选择系统的可信任CA证书.

这是使用FTP_TLS class：

>>> 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客户端用于在提示用户之前加载用户认证信息.

FTP对象

有两种方法可供选择：一种用于处理文本文件和另一种方法用于二进制文件。这些命令的命名用于lines后面的文本版本或binary用于二进制版本.

FTP实例有以下方法：

FTP.set_debuglevel（level）

设置实例的调试级别。这可以控制打印的debuggingoutput数量。默认值0不产生调试输出。值1产生适量的调试输出，通常是单个线路请求。值2或更高产生最大量的调试输出，记录控制连接上发送和接收的每一行.

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

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

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

FTP.getwelcome ( )

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

FTP.login（user=”anonymous”, passwd=””, acct=””）

以给定的user登录。passwd和acct参数是可选的，默认为空字符串。如果没有指定user，则默认为"anonymous"。如果user是"anonymous"，默认的passwd是"anonymous@"。建立连接后，每个实例只应调用一次该函数;如果在创建实例时给出了ahost和user，则根本不应该调用它。客户端登录后，大多数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"。callback函数被称为foreach接收数据块，带有一个字节参数给出数据块。可选的blocksize参数指定在为实际传输而创建的低级套接字对象上读取的最大块大小（也将是传递给callback的数据块的最大大小）。选择合理的默认值。rest表示与transfercmd()方法相同的东西.

FTP.retrlines (cmd, callback=None)

在ASCII传输中检索文件或目录列表模式。cmd应该适当的RETR命令（见retrbinary()）或LIST或NLST之类的命令（通常只是字符串"LIST").LIST检索文件列表和有关这些文件的信息.NLST检索文件名列表.callback为每一行调用函数，其中一个字符串参数包含删除尾部CRLF的行。默认callback将行打印到sys.stdout.

FTP.set_pasv（val）

如果val是的，否则禁用被动模式。默认情况下启用分流模式.

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

以二进制传输模式存储文件。cmd应该是合适的STOR命令："STOR filename". fp是文件对象（以二进制模式打开），使用其read()方法在大小为blocksize的块中读取，直到EOF，以提供要存储的数据.blocksize参数默认为8192. callback是一个可选的单参数可调用，在发送后调用每个数据块.rest与中的含义相同transfercmd()方法。

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

FTP.storlines（cmd, fp, callback=None）

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

FTP.transfercmd (cmd, rest=None)

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

如果给出了可选的rest，则REST命令被发送到服务器，传递rest作为参数。rest通常是一个字节偏移到请求的文件中，告诉服务器重新开始在请求的偏移处发送文件的字节，跳过初始字节。但请注意 RFC 959 仅要求rest是一个字符串，其中包含从ASCII码33到ASCII码126的可打印范围内的字符.transfercmd()方法读取行直到EOF，因此转换rest到字符串，但不对字符串的内容执行检查。如果服务器无法识别REST命令，则会引发error_reply异常。如果发生这种情况，只需在没有transfercmd()的情况下拨打restargument

FTP.ntransfercmd// (cmd, rest=None）

像transfercmd()，但返回数据连接的元组和数据的预期大小。如果无法计算预期的大小，None将作为预期大小返回。cmd和rest与transfercmd().

FTP.mlsd（path=””, facts=[]）

使用MLSD命令（RFC 3659 ）。如果path省略当前目录.facts是表示所需信息类型的字符串列表（例如["type", "size", "perm"]）。返回一个生成器对象，为路径中找到的每个文件生成两个元素的元组。第一个元素是文件名，第二个元素是包含文件名的事实的字典。这本词典的内容可能受到facts参数但服务器不能保证返回所有请求的事实

新版本3.3.

FTP.nlst (argument [, …]）

返回NLST命令。可选的argument是要列出的目录（默认是当前的serverdirectory）。可以使用多个参数将非标准选项传递给NLST命令.

注意

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

FTP.dir(argument [, …])

生成LIST命令，打印它标准输出。可选的argument是要列出的目录（默认为当前服务器目录）。可以使用多个参数将非标准选项传递给LIST命令。如果最后一个参数是一个函数，则它用作callback函数和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的目录server.

FTP.size(filename)

请求服务器上名为filename的文件大小。成功时，文件的大小以整数形式返回，否则返回None。注意SIZE命令没有标准化，但是很多公共服务器实现都支持.

FTP.quit（）

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

FTP.close（）

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

FTP_TLS对象

FTP_TLS类继承自FTP，定义这些附加objects：

FTP_TLS.ssl_version

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

FTP_TLS.auth()

建立一个安全的控制连接使用TLS或SSL，取决于ssl_version属性中指定的内容

更改版本3.4：该方法现在支持使用ssl.SSLContext.check_hostname进行主机名检查和Server Name Indication（见ssl.HAS_SNI).

FTP_TLS.ccc()

将控制通道恢复为明文。这对于了解如何使用非安全FTP处理NAT而不打开固定端口的防火墙有用.

新版本3.3.

FTP_TLS.prot_p (）

设置安全数据连接.

FTP_TLS.prot_c ()

设置明文数据连接.

评论被关闭。