Help on module ftplib:
NAME
ftplib - An FTP client class and some helper functions.
名字：
ftplib 模块 - 一个FTP客户端类 和 一些辅助的方法
FILE
c:python27libftplib.py
DESCRIPTION
Based on RFC 959: File Transfer Protocol (FTP), by J. Postel and J. Reynolds
Example:
>>> from ftplib import FTP
>>> ftp = FTP('ftp.python.org') # connect to host, default port
>>> ftp.login() # default, i.e.: user anonymous, passwd anonymous@
'230 Guest login ok, access restrictions apply.'
>>> ftp.retrlines('LIST') # list directory contents
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.'
>>> ftp.quit()
'221 Goodbye.'
>>>
A nice test that reveals some of the network dialogue would be:
python ftplib.py -d localhost -l -p -l
CLASSES
FTP
FTP_TLS
Netrc
class FTP
| An FTP client class. FTP定义了一个FTP客户端的类
|
| To create a connection, call the class using these arguments: 调用下面这些参数来创建FTP连接：
| host, user, passwd, acct, timeout host, user, passed, acct, timeout
|
| The first four arguments are all strings, and have default value ''. 前四个参数都是字符串，默认值都是''.
| timeout must be numeric and defaults to None if not passed, timeout必须指向数字对象，如果没有设置的话timeout的默认值为None,
| meaning that no timeout will be set on any ftp socket(s) 这意味着在ftp通信中，没有设置超时时长。
| If a timeout is passed, then this is now the default timeout for all ftp 如果timeout设置了， 那么这个值就是所有ftp通信操作的超时时长。
| socket operations for this instance.
|
| Then use self.connect() with optional host and port argument. 用self.connect()函数和参数host(可选)、port(可选)来建立连接。
|
| To download a file, use ftp.retrlines('RETR ' + filename), 用ftp.retrlines('RETR ' + filename)或者ftp.retrbinary()来下载一个文件。
| or ftp.retrbinary() with slightly different arguments.
| To upload a file, use ftp.storlines() or ftp.storbinary(), 用ftp.storlines()或者ftp.storbinary(),来上传一个文件。具体用法可见下文。
| which have an open file as argument (see their definitions
| below for details).
| The download/upload functions first issue appropriate TYPE
| and PORT or PASV commands.
|
| Methods defined here:
|
| __init__(self, host='', user='', passwd='', acct='', timeout=<object object>)
| # Initialization method (called by class instantiation). 初始化方法（这个方法会在实例化的时候自动调用）。
| # Initialize host to localhost, port to standard ftp port
| # Optional arguments are host (for connect()),
| # and user, passwd, acct (for login())
|
| abort(self) 方法abort()
| Abort a file transfer. Uses out-of-band data. 废弃一个文件传输。
| This does not follow the procedure from the RFC to send Telnet
| IP and Synch; that doesn't seem to work with the servers I've
| tried. Instead, just send the ABOR command as OOB data.
|
| acct(self, password)
| Send new account name.
|
| close(self)
| Close the connection without assuming anything about it. 关闭连接。
|
| connect(self, host='', port=0, timeout=-999) 建立连接。
| Connect to host. Arguments are:
| - host: hostname to connect to (string, default previous host)
| - port: port to connect to (integer, default previous port)
|
| cwd(self, dirname)
| Change to a directory. change到当前目录。
|
| debug = set_debuglevel(self, level)
|
| delete(self, filename) delete一个文件。
| Delete a file.
|
| dir(self, *args)
| List a directory in long form. 在一个长表中列出已个列表
| By default list current directory to stdout. 默认是列出当前目录下的文件
| Optional last argument is callback function; all 可选的最后一个参数是回调函数；所有在它之前的非空参数都是同级的。
| non-empty arguments before it are concatenated to the
| LIST command. (This *should* only be used for a pathname.)
|
| getline(self)
| # Internal: return one line from the server, stripping CRLF. 内部函数： 从服务器中返回一行，且自动滤去回车符。
| # Raise EOFError if the connection is closed
|
| getmultiline(self)
| # Internal: get a response from the server, which may possibly 内部函数：从服务器中返回多行，多行组成一个字符串，
| # consist of multiple lines. Return a single string with no 字符串中每行以'
'分隔开，且字符串最后滤去回车符。
| # trailing CRLF. If the response consists of multiple lines,
| # these are separated by '
' characters in the string
|
| getresp(self)
| # Internal: get a response from the server. 从服务器中得到一个反馈
| # Raise various errors if the response indicates an error
|
| getwelcome(self)
| Get the welcome message from the server. 从服务器中返回一个欢迎信息。
| (this is read and squirreled away by connect())
|
| login(self, user='', passwd='', acct='')
| Login, default anonymous. 登录函数，默认是匿名用户。
|
| makepasv(self)
|
| makeport(self)
| Create a new socket and send a PORT command for it. 新建一个通信并为其发一个PORT命令。
|
| mkd(self, dirname)
| Make a directory, return its full pathname. 创建一个目录， 返回它的全路径。
|
| nlst(self, *args)
| Return a list of files in a given directory (default the current). 给定文件目录，返回目录下面的所有文件。
| 默认是返回一个列表，列表中都是当前文件目录下的所有文件名。
| ntransfercmd(self, cmd, rest=None)
| Initiate a transfer over the data connection.
|
| If the transfer is active, send a port command and the 如果传输端是主动的模式，发送一个端口命令和传输命令， 并接受连接。
| transfer command, and accept the connection. If the server is 如果服务器是被动的模式， 发送一个pasv的命令，连接到它，并且开始传输端的命令。
| passive, send a pasv command, connect to it, and start the
| transfer command. Either way, return the socket for the 无论哪种方式，释放连接通信和传输端要求的空间。 如果没有定义参数rest, 这个空间大小默认None
| connection and the expected size of the transfer. The
| expected size may be None if it could not be determined.
|
| Optional `rest' argument can be a string that is sent as the 可选的‘rest’参数是一个字符串， 该参数被当做是一个REST command发送。
| argument to a REST command. This is essentially a server
| marker used to tell the server to skip over any data up to the 它本质上是一个服务标记，用来告诉服务器是否略过任何数据。
| given marker.
|
| putcmd(self, line)
| # Internal: send one command to the server (through putline()) 内部：发送一个命令给服务器。
|
| putline(self, line)
| # Internal: send one line to the server, appending CRLF 内部： 发送一行字符串到服务器中，并在末尾加上回车符。
|
| pwd(self)
| Return current working directory. 返回当前工作路径。
|
| quit(self)
| Quit, and close the connection. 退出并且关闭连接。
|
| rename(self, fromname, toname)
| Rename a file. 重命名一个文件。
|
| retrbinary(self, cmd, callback, blocksize=8192, rest=None)
| Retrieve data in binary mode. A new port is created for you. 用二进制模式返回数据。会创建一个新的端口。
|
| Args: 参数：
| cmd: A RETR command. cmd: 一个RETR命令
| callback: A single parameter callable to be called on each callback: 一个可调用的参数，在读每个板块的数据的时候被调用。
| block of data read.
| blocksize: The maximum number of bytes to read from the blocksize: 一次通信中最大的可读字节数。[默认：8192个字节]
| socket at one time. [default: 8192]
| rest: Passed to transfercmd(). [default: None] rest: ???
|
| Returns:
| The response code. 响应代码
|
| retrlines(self, cmd, callback=None)
| Retrieve data in line mode. A new port is created for you. 一行一行的返回数据。 会创建一个新的端口
|
| Args: 参数：
| cmd: A RETR, LIST, NLST, or MLSD command. cmd: 一个RETR LIST NLST 或者是MLSD命令。
| callback: An optional single parameter callable that is called callback: 一个可选的参数，每行尾部除去回车符。[默认:print_line()]
| for each line with the trailing CRLF stripped.
| [default: print_line()]
|
| Returns:
| The response code.
|
| rmd(self, dirname)
| Remove a directory. 删除一个目录
|
| sanitize(self, s)
| # Internal: "sanitize" a string for printing 内部：
|
| sendcmd(self, cmd)
| Send a command and return the response. 发送一个命令和返回响应
|
| sendeprt(self, host, port)
| Send a EPRT command with the current host and the given port number. 就当前的host和port端口号，发送一个EPRT 命令
|
| sendport(self, host, port)
| Send a PORT command with the current host and the given 就当前的host和port端口号， 发送一个PORT命令
| port number.
|
| set_debuglevel(self, level)
| Set the debugging level. 设置debugging级别
| The required argument level means: 一下数字对应不同级别：
| 0: no debugging output (default) 0： 不输出debugging(默认值)
| 1: print commands and responses but not body text etc. 1: 打印命令和响应，但不打印主体内容
| 2: also print raw lines read and sent before stripping CR/LF 2： 打印raw行， 在去除回车符之前读和发送 ？？？
|
| set_pasv(self, val)
| Use passive or active mode for data transfers. 用被动或者主动模式来传送数据。
| With a false argument, use the normal PORT mode, 参数是false的时候，用正常的PORT模式，
| With a true argument, use the PASV command. 参数是true的时候，用PASV命令。
|
| size(self, filename)
| Retrieve the size of a file. 返回文件的大小。
|
| storbinary(self, cmd, fp, blocksize=8192, callback=None, rest=None)
| Store a file in binary mode. A new port is created for you. 用二进制模式存储一个文件。新的端口将会被创建。
|
| Args:
| cmd: A STOR command. cmd: 一个STOR命令
| fp: A file-like object with a read(num_bytes) method. fp: 一个类似文件的对象，并且已经处于可读状态
| blocksize: The maximum data size to read from fp and send over blocksize: 一次 从文件fp读数据的最大数据量 和 发送到连接上的最大数据量[默认: 8192]
| the connection at once. [default: 8192]
| callback: An optional single parameter callable that is called on callback: 一个可选参数，
| each block of data after it is sent. [default: None]
| rest: Passed to transfercmd(). [default: None] rest: ？？
|
| Returns:
| The response code.
|
| storlines(self, cmd, fp, callback=None)
| Store a file in line mode. A new port is created for you. 一行一行保存一个文件。一个新的端口将会被创建
|
| Args:
| cmd: A STOR command. cmd: 一个STOR命令
| fp: A file-like object with a readline() method. fp: 一个类似文件的对象，并且已经处于可读状态
| callback: An optional single parameter callable that is called on
| each line after it is sent. [default: None]
|
| Returns:
| The response code.
|
| transfercmd(self, cmd, rest=None)
| Like ntransfercmd() but returns only the socket.
|
| voidcmd(self, cmd)
| Send a command and expect a response beginning with '2'.
|
| voidresp(self)
| Expect a response beginning with '2'.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| debugging = 0
|
| file = None
|
| host = ''
|
| maxline = 8192
|
| passiveserver = 1
|
| port = 21
|
| sock = None
|
| welcome = None
class FTP_TLS(FTP)
| A FTP subclass which adds TLS support to FTP as described
| in RFC-4217.
|
| Connect as usual to port 21 implicitly securing the FTP control
| connection before authenticating.
|
| Securing the data connection requires user to explicitly ask
| for it by calling prot_p() method.
|
| Usage example:
| >>> from ftplib import FTP_TLS
| >>> ftps = FTP_TLS('ftp.python.org')
| >>> ftps.login() # login anonymously previously securing control channel
| '230 Guest login ok, access restrictions apply.'
| >>> ftps.prot_p() # switch to secure data connection
| '200 Protection level set to P'
| >>> 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()
| '221 Goodbye.'
| >>>
|
| Methods defined here:
|
| __init__(self, host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=<object object>, source_address=None)
|
| auth(self)
| Set up secure control connection by using TLS/SSL.
|
| login(self, user='', passwd='', acct='', secure=True)
|
| ntransfercmd(self, cmd, rest=None)
|
| prot_c(self)
| Set up clear text data connection.
|
| prot_p(self)
| Set up secure data connection.
|
| retrbinary(self, cmd, callback, blocksize=8192, rest=None)
|
| retrlines(self, cmd, callback=None)
|
| storbinary(self, cmd, fp, blocksize=8192, callback=None, rest=None)
|
| storlines(self, cmd, fp, callback=None)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| ssl_version = 2
|
| ----------------------------------------------------------------------
| Methods inherited from FTP:
|
| abort(self)
| Abort a file transfer. Uses out-of-band data.
| This does not follow the procedure from the RFC to send Telnet
| IP and Synch; that doesn't seem to work with the servers I've
| tried. Instead, just send the ABOR command as OOB data.
|
| acct(self, password)
| Send new account name.
|
| close(self)
| Close the connection without assuming anything about it.
|
| connect(self, host='', port=0, timeout=-999)
| Connect to host. Arguments are:
| - host: hostname to connect to (string, default previous host)
| - port: port to connect to (integer, default previous port)
|
| cwd(self, dirname)
| Change to a directory.
|
| debug = set_debuglevel(self, level)
| Set the debugging level.
| The required argument level means:
| 0: no debugging output (default)
| 1: print commands and responses but not body text etc.
| 2: also print raw lines read and sent before stripping CR/LF
|
| delete(self, filename)
| Delete a file.
|
| dir(self, *args)
| List a directory in long form.
| By default list current directory to stdout.
| Optional last argument is callback function; all
| non-empty arguments before it are concatenated to the
| LIST command. (This *should* only be used for a pathname.)
|
| getline(self)
| # Internal: return one line from the server, stripping CRLF.
| # Raise EOFError if the connection is closed
|
| getmultiline(self)
| # Internal: get a response from the server, which may possibly
| # consist of multiple lines. Return a single string with no
| # trailing CRLF. If the response consists of multiple lines,
| # these are separated by '
' characters in the string
|
| getresp(self)
| # Internal: get a response from the server.
| # Raise various errors if the response indicates an error
|
| getwelcome(self)
| Get the welcome message from the server.
| (this is read and squirreled away by connect())
|
| makepasv(self)
|
| makeport(self)
| Create a new socket and send a PORT command for it.
|
| mkd(self, dirname)
| Make a directory, return its full pathname.
|
| nlst(self, *args)
| Return a list of files in a given directory (default the current).
|
| putcmd(self, line)
| # Internal: send one command to the server (through putline())
|
| putline(self, line)
| # Internal: send one line to the server, appending CRLF
|
| pwd(self)
| Return current working directory.
|
| quit(self)
| Quit, and close the connection.
|
| rename(self, fromname, toname)
| Rename a file.
|
| rmd(self, dirname)
| Remove a directory.
|
| sanitize(self, s)
| # Internal: "sanitize" a string for printing
|
| sendcmd(self, cmd)
| Send a command and return the response.
|
| sendeprt(self, host, port)
| Send a EPRT command with the current host and the given port number.
|
| sendport(self, host, port)
| Send a PORT command with the current host and the given
| port number.
|
| set_debuglevel(self, level)
| Set the debugging level.
| The required argument level means:
| 0: no debugging output (default)
| 1: print commands and responses but not body text etc.
| 2: also print raw lines read and sent before stripping CR/LF
|
| set_pasv(self, val)
| Use passive or active mode for data transfers.
| With a false argument, use the normal PORT mode,
| With a true argument, use the PASV command.
|
| size(self, filename)
| Retrieve the size of a file.
|
| transfercmd(self, cmd, rest=None)
| Like ntransfercmd() but returns only the socket.
|
| voidcmd(self, cmd)
| Send a command and expect a response beginning with '2'.
|
| voidresp(self)
| Expect a response beginning with '2'.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FTP:
|
| debugging = 0
|
| file = None
|
| host = ''
|
| maxline = 8192
|
| passiveserver = 1
|
| port = 21
|
| sock = None
|
| welcome = None
class Netrc
| Class to parse & provide access to 'netrc' format files.
|
| See the netrc(4) man page for information on the file format.
|
| WARNING: This class is obsolete -- use module netrc instead.
|
| Methods defined here:
|
| __init__(self, filename=None)
|
| get_account(self, host)
| Returns login information for the named host.
|
| The return value is a triple containing userid,
| password, and the accounting field.
|
| get_hosts(self)
| Return a list of hosts mentioned in the .netrc file.
|
| get_macro(self, macro)
| Return a sequence of lines which define a named macro.
|
| get_macros(self)
| Return a list of all defined macro names.
DATA
__all__ = ['FTP', 'Netrc', 'FTP_TLS']