Docs4dev
Docs
python / 2.7.15 / all / library-ftplib.html

20.8. ftplib — FTP 协议 Client 端

源代码： Lib/ftplib.py

该模块定义了FTP类和一些相关项。 FTP类实现 FTP 协议的 Client 端。您可以使用它来编写执行各种自动 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类的新实例。给定* host 时，将进行方法调用connect(host)。当给定 user 时，另外进行方法调用login(user, passwd, acct)(未给定时，其中 passwd 和 acct 默认为空字符串)。可选的 timeout *参数指定以秒为单位的超时，用于阻止诸如连接try之类的操作(如果未指定，将使用全局默认超时设置)。

在 2.6 版中进行了更改：添加了“超时”。

    • class * ftplib. FTP_TLS([* host * [，* user * [，* passwd * [，* acct * [，* keyfile * [，* certfile * [，* context * [，* timeout *]]]]]] ]]]))
    • FTP子类，如 RFC 4217中所述向 FTP 添加 TLS 支持。像往常一样连接到端口 21，以在身份验证之前隐式保护 FTP 控制连接。保护数据连接需要用户pass调用prot_p()方法来明确要求它。 * context *是ssl.SSLContext对象，它允许将 SSL 配置选项，证书和私钥 Binding 到一个(可能是长期存在的)结构中。请阅读Security considerations了解最佳做法。
  • keyfile 和 certfile 是 context *的传统替代方案–它们可以分别指向 PEM 格式的私钥和证书链文件以进行 SSL 连接。

2.7 版的新Function。

在 2.7.10 版中更改：添加了* context *参数。

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

See also

  • Module netrc

  • .netrc文件格式的解析器。 FTPClient 端通常使用文件.netrc提示用户之前加载用户身份验证信息。

Python 源代码分发中的文件Tools/scripts/ftpmirror.py是一个脚本，可以使用ftplib模块来镜像 FTP 站点或其部分。可以用作应用此模块的扩展示例。

20.8.1. FTP 对象

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

FTP个实例具有以下方法：

  • FTP. set_debuglevel(级别)

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

  • FTP. connect(* host * [，* port * [，* timeout *]])

    • 连接到给定的主机和端口。默认端口号是21，由 FTP 协议规范指定。很少需要指定其他端口号。每个实例只能调用一次该函数；如果在创建实例时给出了主机，则根本不应调用它。所有其他方法只能在构建连接后使用。

可选的* timeout 参数指定连接try的超时时间(以秒为单位)。如果未传递 timeout *，将使用全局默认超时设置。

在 2.6 版中进行了更改：添加了“超时”。

  • FTP. getwelcome ( )

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

  • FTP. login([* user * [，* passwd * [，* acct *]]])

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

  • FTP. abort ( )

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

  • FTP. sendcmd(* command *)

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

  • FTP. voidcmd(* command *)

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

  • FTP. retrbinary(* command ， callback * [，* maxblocksize * [，* rest *]])

    • 以二进制传输模式检索文件。 * command 应该是适当的RETR命令：'RETR filename'。对每个接收到的数据块调用 callback 函数，并使用单个字符串参数给出该数据块。可选的 maxblocksize 参数指定在为进行实际传输而创建的低级套接字对象上读取的最大块大小(这也是传递给 callback *的数据块的最大大小)。选择一个合理的默认值。 * rest *的含义与transfercmd()方法相同。

  • FTP. retrlines(* command * [，* callback *])

    • 以 ASCII 传输模式检索文件或目录列表。 * command 应该是适当的RETR命令(请参阅retrbinary())或诸如LIST，NLST或MLSD之类的命令(通常只是字符串'LIST')。 LIST检索文件列表以及有关这些文件的信息。 NLST检索文件名列表。在某些服务器上，MLSD检索文件的机器可读列表以及有关这些文件的信息。为每一行调用 callback 函数，该函数带有一个字符串参数，其中包含尾随 CRLF 的行被去除。默认的 callback *将行打印到sys.stdout。

  • FTP. set_pasv(* val *)

    • 如果* val *为 true，则启用“被动”模式，否则禁用被动模式。 (在 Python 2.0 和更低版本中，默认情况下为被动模式；在 Python 2.1 和更高版本中，默认情况下为被动模式.)

  • FTP. storbinary(* command ， fp * [，* blocksize ， callback ， rest *])

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

在 2.1 版中进行了更改：默认添加了* blocksize *。

在 2.6 版中进行了更改：添加了* callback *参数。

在 2.7 版中进行了更改：添加了* rest *参数。

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

在 2.6 版中进行了更改：添加了* callback *参数。

  • FTP. transfercmd(* cmd * [，* rest *])
    • 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 *])

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

  • 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()方法来重新打开连接)。

20.8.2. FTP_TLS 对象

FTP_TLS类继承自FTP，定义了以下其他对象：

  • FTP_TLS. ssl_version

  • FTP_TLS. auth ( )

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

  • FTP_TLS. prot_p ( )

    • 设置安全数据连接。

  • FTP_TLS. prot_c ( )

    • 设置明文数据连接。