源程序代码:Lib/ftplib.py
本模块定义了类FTP和几个相关的项目。 FTP类实现 FTP 协议的客户端。您可以使用此编写执行各种自动化的 FTP 作业,如镜像其他 ftp 服务器的 Python 程序。它也利用模块urllib处理使用 FTP 的 Url。有关 FTP (文件传输协议) 的详细信息,请参阅互联网 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()
模块定义以下各项:
返回FTP类的新的实例。当主机,是由方法调用connect(host) 。当用户被授予,另外该方法调用登录 (用户, passwd, acct)由 (地方密码和帐户默认值为空字符串时不给出)。可选的超时参数指定超时值以秒计) 阻塞像连接尝试的操作 (如果未指定,则全局默认超时设置将被使用)。
2.6 版本中的更改:添加了超时。
其中添加了 TLS 支持 FTP 中所述的FTP子类 RFC 4217。像往常一样连接到端口 21 隐式地确保 FTP 控制连接之前进行身份验证。确保数据连接需要用户明确要求它通过调用prot_p()方法。密钥文件和certfile是可选的 — — 它们可以包含质子交换膜的格式化私人密钥和证书链文件名称为 SSL 连接。
在 2.7 版本新。
下面是使用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()
>>>
从服务器收到意外的答复时引发的异常。
当接收到错误代码表示一个暂时的错误 (在范围内 400-499 响应代码) 时引发的异常。
当接收到错误代码表示一个永久性的错误 (在范围内 500 — — 599 响应代码) 时引发的异常。
不适合响应规格的文件传输协议,即开始以数字 1-5 范围内的服务器收到答复时引发的异常。
(作为一个元组) FTP实例的方法可提高由于 FTP 连接 (而不是编程调用方所犯的错误) 的问题的所有异常的集合。这套包括socket.error和时发生 io 错误上面列出的四个例外。
请参见
Tools/scripts/ftpmirror.py文件中的 Python 源代码发行版是一个可以镜像 FTP 站点或其中的某些部分,使用ftplib模块的脚本。它可以用作一个适用于此模块的扩展示例。
提供的函数可分为两种用途: 一个用于处理文本的文件,另一个用于二进制文件。这些被命名为用后跟行的文本版本或二进制二进制版本的命令。
FTP实例具有以下方法:
设置该实例的调试级别。此参数控制调试输出打印的量。默认情况下, 0,不生成任何调试输出。 1的值产生适量的调试输出,通常每个请求的单个行。 2或更高的值会生成调试输出,测井控制连接上发送和接收的每一行的最大量。
连接到给定的主机和端口。默认端口号为21,由 FTP 协议规范。它很少需要指定一个不同的端口号。应该只有一次调用此函数,为每个实例 ;它不应调用根本如果主机被授予创建实例时。连接后,可以只使用所有其他方法。
可选的超时参数指定超时值以秒为单位的连接尝试。如果传递了没有超时,则将使用全局默认超时设置。
2.6 版本中的更改:添加了超时。
返回由回答在初始连接时服务器发送的欢迎消息。(此消息有时包含免责声明或帮助可能是与用户相关的信息。
给定的用户身份登录。密码和帐户的参数是可选的默认值为空字符串。如果用户没有指定,则默认为'无名氏'。如果用户是'无名氏',默认密码是' 匿名 @'。调用此函数应该只有一次为每个实例后已建立的连接 ;它不应调用根本如果主机和用户给出了创建实例时。大多数 FTP 命令只允许客户端登录后。Acct参数提供"会计信息";几个系统实现。
中止正在进行的文件传输。使用这不总是工作,但它是值得一试。
向服务器发送一个简单的命令字符串,并返回响应字符串。
向服务器发送一个简单的命令字符串和处理响应。返回接收到什么如果成功 (在 200-299 范围代码) 所对应的响应代码。否则提高error_reply 。
检索二进制传输模式中的一个文件。命令应适当的RETR命令: 'RETR 文件名'。对于每个接收与单个字符串参数,给数据块的数据块调用回调函数。可选的maxblocksize参数指定要创建的实际转移 (这也将传递到回调的数据块的最大大小) 的低级套接字对象上读取的最大块大小。一个合理的默认选择。其余的transfercmd()方法在相同的意思。
检索文件或目录清单中 ASCII 传输模式。命令应适当RETR命令 (见retrbinary()) 或命令,如列表、 NLST或MLSD (通常只是字符串'LIST')。列表中检索的文件和有关这些文件的信息的列表。 NLST检索文件名称的列表。在某些服务器上MLSD检索文件和有关这些文件的信息的机器可读的列表。使用字符串参数含尾随的 CRLF 剥线为每一行调用回调函数。默认回调打印到sys.stdout线。
如果布尔值为 true,其他禁用被动模式,请启用"被动"模式。(在 Python 2.0 和前被动模式是关闭默认情况下 ; 在 Python 2.1 及更高版本,它在默认情况下)。
2.1 版本中的更改: 块大小添加默认值。
2.6 版本中的更改:添加的回调参数。
2.7 版本中的更改:添加的其他参数。
将文件存储在 ASCII 传输模式。命令应适当STOR命令 (见storbinary())。直到 EOF 读取读取行,从打开的文件对象文件使用其readline ()方法来提供要存储的数据。回调是可选单个参数调用,发出后在每一行上调用。
2.6 版本中的更改:添加的回调参数。
在数据连接上启动传送。如果转让是活跃的发送本地或端口的命令和传输命令指定的cmd,并接受连接。如果该服务器是被动的发送一个EPSV或PASV命令,连接到它,并开始传输命令。无论哪种方式,返回连接的套接字。
如果给出可选的其余部分,其余的命令发送到服务器上,将其余部分作为参数传递。rest通常是字节偏移量,到所请求的文件,告诉服务器重新启动请求的偏移量,跳过初始字节发送文件的字节数。但是请注意 RFC 959 要求只有那其余部分必须包含 ASCII 码 126 ASCII 码 33 ~ 可打印的字符的字符串。 Transfercmd()方法,因此,将其余部分转换为字符串,但不执行检查字符串的内容。如果服务器不能识别其他命令,则将引发error_reply异常。如果发生这种情况,只需调用transfercmd()如果没有其余参数。
像transfercmd(),但返回一个元组的数据连接和数据的预期的大小。如果无法计算出料的粒度,没有将返回作为预期大小。cmd和休息意味着同样的事情,如transfercmd()所示。
返回的文件名作为NLST命令返回的列表。可选的参数是一个到列表中的目录 (默认为当前的服务器目录)。多个参数可以用于将非标准选项传递给NLST命令。
生成一个目录列表,返回的列表命令,打印到标准输出。可选的参数是一个到列表中的目录 (默认为当前的服务器目录)。多个参数可以用于将非标准选项传递到列表命令。如果最后一个参数是一个函数,它作为一个回调函数,至于retrlines();默认打印到sys.stdout。此方法返回None。
将文件fromname在服务器上重命名为toname。
删除指定的文件名从服务器的文件。如果成功,返回的响应文本,否则引发error_perm权限错误或其他错误error_reply 。
在服务器上设置的当前目录。
在服务器上创建一个新的目录。
返回服务器上的当前目录的路径名。
删除名为dirname的服务器上的目录。
请求指定服务器上的文件名的文件的大小。如果成功,文件的大小作为一个整数返回,否则没有返回。注意大小命令并不是标准化,但支持由很多常见的服务器实现。