ftplib — FTP 协议 Client 端

源代码： Lib/ftplib.py

---

该模块定义了FTP类和一些相关项。 FTP类实现 FTP 协议的 Client 端。您可以使用它来编写执行各种自动 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.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.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 *参数指定以秒为单位的超时，用于阻止诸如连接try之类的操作(如果未指定，将使用全局默认超时设置)。 * source_address *是 2Tuples(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 *)
  • FTP子类，如 RFC 4217中所述向 FTP 添加 TLS 支持。像往常一样连接到端口 21，以在身份验证之前隐式保护 FTP 控制连接。保护数据连接需要用户pass调用prot_p()方法来明确要求它。 * context *是ssl.SSLContext对象，它允许将 SSL 配置选项，证书和私钥 Binding 到一个(可能是长期存在的)结构中。请阅读Security considerations了解最佳做法。

• keyfile 和 certfile 是 context *的传统替代方案–它们可以分别指向 PEM 格式的私钥和证书链文件以进行 SSL 连接。

3.2 版中的新Function。

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

在版本 3.4 中进行了更改：该类现在支持使用ssl.SSLContext.check_hostname和服务器名称指示(请参阅ssl.HAS_SNI)检查主机名。

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

这是使用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 连接问题(与调用程序所犯的编程错误相对)而引发的所有异常(作为 Tuples)的集合。该集合包括上面列出的四个异常以及OSError和EOFError。

FTP Objects

有两种方法可以使用两种方法：一种用于处理文本文件，另一种用于二进制文件。它们是为所使用的命令命名的，后面跟着lines代表文本版本或binary代表二进制版本。

FTP个实例具有以下方法：

• FTP. set_debuglevel(级别)

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

• FTP. connect(* host =''， port = 0 ， timeout = None ， source_address = None *)

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

用参数self，host，port引发auditing event ftplib.connect。

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

• FTP. getwelcome ( )

  • 返回服务器发送的欢迎消息以回复初始连接。 (此消息有时包含与用户相关的免责语句或帮助信息.)

• FTP. login(* user ='anonymous'， passwd =''， acct =''*)

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

• FTP. abort ( )

  • 中止正在进行的文件传输。使用此方法并不总是有效，但值得try。

• FTP. sendcmd(* cmd *)

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

用参数self，cmd引发auditing event ftplib.sendcmd。

• FTP. voidcmd(* cmd *)
  • 将简单的命令字符串发送到服务器并处理响应。如果收到与成功相对应的响应代码(范围在 200-299 之间的代码)，则不返回任何内容。否则提高error_reply。

用参数self，cmd引发auditing event ftplib.sendcmd。

• FTP. retrbinary(* cmd ， callback ， blocksize = 8192 ， rest = None *)

  • 以二进制传输模式检索文件。 * cmd 应该是适当的RETR命令：'RETR filename'。对于每个接收到的数据块，将调用 callback 函数，并使用单个字节参数给出数据块。可选的 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 *为 true，则启用“被动”模式，否则禁用被动模式。默认情况下，被动模式是打开的。

• FTP. storbinary(* cmd ， fp ， blocksize = 8192 ， callback = None ， rest = None *)

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

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

• FTP. storlines(* cmd ， fp ， callback = None *)

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

• FTP. transfercmd(* cmd ， rest = None *)

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

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

• FTP. ntransfercmd(* cmd ， rest = None *)

  • 类似于transfercmd()，但返回数据连接的 Tuples 和数据的预期大小。如果无法计算预期大小，则将None作为预期大小返回。 * cmd 和 rest *与transfercmd()中的含义相同。

• FTP. mlsd(* path =“” ， facts = [] *)

  • 使用MLSD命令( RFC 3659)以标准格式列出目录。如果Ellipsis* path ，则使用当前目录。 事实是代表所需信息类型的字符串列表(例如["type", "size", "perm"])。返回一个生成器对象，该对象为在 path 中找到的每个文件生成两个元素的 Tuples。第一个元素是文件名，第二个元素是包含有关文件名事实的字典。该词典的内容可能受 facts *参数的限制，但是不能保证服务器返回所有请求的事实。

版本 3.3 中的新Function。

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

• FTP. dir(* argument * [，* ... *])
  • 产生一个由LIST命令返回的目录列表，并将其打印到标准输出中。可选的* argument 是要列出的目录(默认为当前服务器目录)。可以使用多个参数将非标准选项传递给LIST命令。如果最后一个参数是一个函数，则它用作retrlines()的 callback *函数；默认打印到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()之后，您将无法pass发出另一个login()方法来重新打开连接)。

FTP_TLS Objects

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 中的新Function。

• FTP_TLS. prot_p ( )

  • 设置安全数据连接。

• FTP_TLS. prot_c ( )

  • 设置明文数据连接。