ftplib —- FTP 协议客户端

源代码：Lib/ftplib.py

This module defines the class FTP and a few related items. TheFTP class implements the client side of the FTP protocol. You can usethis to write Python programs that perform a variety of automated FTP jobs, suchas mirroring other FTP servers. It is also used by the moduleurllib.request to handle URLs that use FTP. For more information on FTP(File Transfer Protocol), see Internet RFC 959.

Here's a sample session using the ftplib module:

  1. >>> from ftplib import FTP
  2. >>> ftp = FTP('ftp.debian.org')     # connect to host, default port
  3. >>> ftp.login()                     # user anonymous, passwd anonymous@
  4. '230 Login successful.'
  5. >>> ftp.cwd('debian')               # change into "debian" directory
  6. >>> ftp.retrlines('LIST')           # list directory contents
  7. -rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
  8. ...
  9. drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
  10. drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
  11. drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
  12. '226 Directory send OK.'
  13. >>> with open('README', 'wb') as fp:
  14. >>>     ftp.retrbinary('RETR README', fp.write)
  15. '226 Transfer complete.'
  16. >>> ftp.quit()

这个模块定义了以下内容：

  • class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None)
  • Return a new instance of the FTP class. When host is given, themethod call connect(host) is made. When user is given, additionallythe method call login(user, passwd, acct) is made (where passwd andacct default to the empty string when not given). The optional timeout_parameter specifies a timeout in seconds for blocking operations like theconnection attempt (if is not specified, the global default timeout settingwill be used). _source_address is a 2-tuple (host, port) for the socketto bind to as its source address before connecting.

The FTP class supports the with statement, e.g.:

  1. >>> from ftplib import FTP
  2. >>> with FTP("ftp1.at.proftpd.org") as ftp:
  3. ...     ftp.login()
  4. ...     ftp.dir()
  5. ... # doctest: +SKIP
  6. '230 Anonymous login ok, restrictions apply.'
  7. dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
  8. dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
  9. dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
  10. dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
  11. >>>

在 3.2 版更改: 支持了 with 语句。

在 3.3 版更改: source_address parameter was added.

  • class ftplib.FTPTLS(_host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)
  • A FTP subclass which adds TLS support to FTP as described inRFC 4217.Connect as usual to port 21 implicitly securing the FTP control connectionbefore authenticating. Securing the data connection requires the user toexplicitly ask for it by calling the prot_p() method. _context_is a ssl.SSLContext object which allows bundling SSL configurationoptions, certificates and private keys into a single (potentiallylong-lived) structure. Please read Security considerations for best practices.

keyfile and certfile are a legacy alternative to context — theycan point to PEM-formatted private key and certificate chain files(respectively) for the SSL connection.

3.2 新版功能.

在 3.3 版更改: source_address parameter was added.

在 3.4 版更改: The class now supports hostname check withssl.SSLContext.check_hostname and Server Name Indication (seessl.HAS_SNI).

3.6 版后已移除: keyfile and certfile are deprecated in favor of context.Please use ssl.SSLContext.load_cert_chain() instead, or letssl.create_default_context() select the system's trusted CAcertificates for you.

Here's a sample session using the FTP_TLS class:

  1. >>> ftps = FTP_TLS('ftp.pureftpd.org')
  2. >>> ftps.login()
  3. '230 Anonymous user logged in'
  4. >>> ftps.prot_p()
  5. '200 Data protection level set to "private"'
  6. >>> ftps.nlst()
  7. ['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 raised when an unexpected reply is received from the server.
  • exception ftplib.error_temp
  • Exception raised when an error code signifying a temporary error (responsecodes in the range 400—499) is received.
  • exception ftplib.error_perm
  • Exception raised when an error code signifying a permanent error (responsecodes in the range 500—599) is received.
  • exception ftplib.error_proto
  • Exception raised when a reply is received from the server that does not fitthe response specifications of the File Transfer Protocol, i.e. begin with adigit in the range 1—5.
  • ftplib.all_errors
  • The set of all exceptions (as a tuple) that methods of FTPinstances may raise as a result of problems with the FTP connection (asopposed to programming errors made by the caller). This set includes thefour exceptions listed above as well as OSError.

参见

  • Module netrc
  • Parser for the .netrc file format. The file .netrc istypically used by FTP clients to load user authentication informationbefore prompting the user.

FTP Objects

Several methods are available in two flavors: one for handling text files andanother for binary files. These are named for the command which is usedfollowed by lines for the text version or binary for the binary version.

FTP instances have the following methods:

  • FTP.setdebuglevel(_level)
  • Set the instance's debugging level. This controls the amount of debuggingoutput printed. The default, 0, produces no debugging output. A value of1 produces a moderate amount of debugging output, generally a single lineper request. A value of 2 or higher produces the maximum amount ofdebugging output, logging each line sent and received on the control connection.
  • FTP.connect(host='', port=0, timeout=None, source_address=None)
  • Connect to the given host and port. The default port number is 21, asspecified by the FTP protocol specification. It is rarely needed to specify adifferent port number. This function should be called only once for eachinstance; it should not be called at all if a host was given when the instancewas created. All other methods can only be used after a connection has beenmade.The optional timeout parameter specifies a timeout in seconds for theconnection attempt. If no timeout is passed, the global default timeoutsetting will be used.source_address is a 2-tuple (host, port) for the socket to bind to asits source address before connecting.

在 3.3 版更改: source_address parameter was added.

  • FTP.getwelcome()
  • Return the welcome message sent by the server in reply to the initialconnection. (This message sometimes contains disclaimers or help informationthat may be relevant to the user.)
  • FTP.login(user='anonymous', passwd='', acct='')
  • Log in as the given user. The passwd and acct parameters are optional anddefault to the empty string. If no user is specified, it defaults to'anonymous'. If user is 'anonymous', the default passwd is'anonymous@'. This function should be called only once for each instance,after a connection has been established; it should not be called at all if ahost and user were given when the instance was created. Most FTP commands areonly allowed after the client has logged in. The acct parameter supplies"accounting information"; few systems implement this.
  • FTP.abort()
  • Abort a file transfer that is in progress. Using this does not always work, butit's worth a try.
  • FTP.sendcmd(cmd)
  • Send a simple command string to the server and return the response string.
  • FTP.voidcmd(cmd)
  • Send a simple command string to the server and handle the response. Returnnothing if a response code corresponding to success (codes in the range200—299) is received. Raise error_reply otherwise.
  • FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
  • Retrieve a file in binary transfer mode. cmd should be an appropriateRETR command: 'RETR filename'. The callback function is called foreach block of data received, with a single bytes argument giving the datablock. The optional blocksize argument specifies the maximum chunk size toread on the low-level socket object created to do the actual transfer (whichwill also be the largest size of the data blocks passed to callback). Areasonable default is chosen. rest means the same thing as in thetransfercmd() method.
  • FTP.retrlines(cmd, callback=None)
  • Retrieve a file or directory listing in ASCII transfer mode. cmd should bean appropriate RETR command (see retrbinary()) or a command such asLIST or NLST (usually just the string 'LIST').LIST retrieves a list of files and information about those files.NLST retrieves a list of file names.The callback function is called for each line with a string argumentcontaining the line with the trailing CRLF stripped. The default _callback_prints the line to sys.stdout.
  • FTP.setpasv(_val)
  • Enable "passive" mode if val is true, otherwise disable passive mode.Passive mode is on by default.
  • FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)
  • Store a file in binary transfer mode. cmd should be an appropriateSTOR command: "STOR filename". fp is a file object(opened in binary mode) which is read until EOF using its read()method in blocks of size blocksize to provide the data to be stored.The blocksize argument defaults to 8192. callback is an optional singleparameter callable that is called on each block of data after it is sent.rest means the same thing as in the transfercmd() method.

在 3.2 版更改: rest parameter added.

  • FTP.storlines(cmd, fp, callback=None)
  • Store a file in ASCII transfer mode. cmd should be an appropriateSTOR command (see storbinary()). Lines are read until EOF from thefile objectfp (opened in binary mode) using its readline()method to provide the data to be stored. callback is an optional singleparameter callable that is called on each line after it is sent.
  • FTP.transfercmd(cmd, rest=None)
  • Initiate a transfer over the data connection. If the transfer is active, send anEPRT or PORT command and the transfer command specified by cmd, andaccept the connection. If the server is passive, send an EPSV or PASVcommand, connect to it, and start the transfer command. Either way, return thesocket for the connection.

If optional rest is given, a REST command is sent to the server, passingrest as an argument. rest is usually a byte offset into the requested file,telling the server to restart sending the file's bytes at the requested offset,skipping over the initial bytes. Note however that RFC 959 requires only thatrest be a string containing characters in the printable range from ASCII code33 to ASCII code 126. The transfercmd() method, therefore, convertsrest to a string, but no check is performed on the string's contents. If theserver does not recognize the REST command, an error_reply exceptionwill be raised. If this happens, simply call transfercmd() without arest argument.

  • FTP.ntransfercmd(cmd, rest=None)
  • Like transfercmd(), but returns a tuple of the data connection and theexpected size of the data. If the expected size could not be computed, Nonewill be returned as the expected size. cmd and rest means the same thing asin transfercmd().
  • FTP.mlsd(path="", facts=[])
  • List a directory in a standardized format by using MLSD command(RFC 3659). If path is omitted the current directory is assumed.facts is a list of strings representing the type of information desired(e.g. ["type", "size", "perm"]). Return a generator object yielding atuple of two elements for every file found in path. First element is thefile name, the second one is a dictionary containing facts about the filename. Content of this dictionary might be limited by the facts argumentbut server is not guaranteed to return all requested facts.

3.3 新版功能.

  • FTP.nlst(argument[, …])
  • Return a list of file names as returned by the NLST command. Theoptional argument is a directory to list (default is the current serverdirectory). Multiple arguments can be used to pass non-standard options tothe NLST command.

注解

If your server supports the command, mlsd() offers a better API.

  • FTP.dir(argument[, …])
  • Produce a directory listing as returned by the LIST command, printing it tostandard output. The optional argument is a directory to list (default is thecurrent server directory). Multiple arguments can be used to pass non-standardoptions to the LIST command. If the last argument is a function, it is usedas a callback function as for retrlines(); the default prints tosys.stdout. This method returns None.

注解

If your server supports the command, mlsd() offers a better API.

  • FTP.rename(fromname, toname)
  • Rename file fromname on the server to toname.
  • FTP.delete(filename)
  • Remove the file named filename from the server. If successful, returns thetext of the response, otherwise raises error_perm on permission errors orerror_reply on other errors.
  • FTP.cwd(pathname)
  • Set the current directory on the server.
  • FTP.mkd(pathname)
  • Create a new directory on the server.
  • FTP.pwd()
  • Return the pathname of the current directory on the server.
  • FTP.rmd(dirname)
  • Remove the directory named dirname on the server.
  • FTP.size(filename)
  • Request the size of the file named filename on the server. On success, thesize of the file is returned as an integer, otherwise None is returned.Note that the SIZE command is not standardized, but is supported by manycommon server implementations.
  • FTP.quit()
  • Send a QUIT command to the server and close the connection. This is the"polite" way to close a connection, but it may raise an exception if the serverresponds with an error to the QUIT command. This implies a call to theclose() method which renders the FTP instance useless forsubsequent calls (see below).
  • FTP.close()
  • Close the connection unilaterally. This should not be applied to an alreadyclosed connection such as after a successful call to quit().After this call the FTP instance should not be used any more (aftera call to close() or quit() you cannot reopen theconnection by issuing another login() method).

FTP_TLS Objects

FTP_TLS class inherits from FTP, defining these additional objects:

  • FTP_TLS.auth()
  • Set up a secure control connection by using TLS or SSL, depending on whatis specified in the ssl_version attribute.

在 3.4 版更改: The method now supports hostname check withssl.SSLContext.check_hostname and Server Name Indication (seessl.HAS_SNI).

  • FTP_TLS.ccc()
  • Revert control channel back to plaintext. This can be useful to takeadvantage of firewalls that know how to handle NAT with non-secure FTPwithout opening fixed ports.

3.3 新版功能.

  • FTP_TLS.prot_p()
  • Set up secure data connection.
  • FTP_TLS.prot_c()
  • Set up clear text data connection.