合规国际互联网加速 OSASE为企业客户提供高速稳定SD-WAN国际加速解决方案。 广告
### 导航 - [索引](../genindex.xhtml "总目录") - [模块](../py-modindex.xhtml "Python 模块索引") | - [下一页](poplib.xhtml "poplib --- POP3 protocol client") | - [上一页](http.client.xhtml "http.client --- HTTP协议客户端") | - ![](https://box.kancloud.cn/a721fc7ec672275e257bbbfde49a4d4e_16x16.png) - [Python](https://www.python.org/) » - zh\_CN 3.7.3 [文档](../index.xhtml) » - [Python 标准库](index.xhtml) » - [互联网协议和支持](internet.xhtml) » - $('.inline-search').show(0); | # [`ftplib`](#module-ftplib "ftplib: FTP protocol client (requires sockets).") --- FTP protocol client **Source code:** [Lib/ftplib.py](https://github.com/python/cpython/tree/3.7/Lib/ftplib.py) \[https://github.com/python/cpython/tree/3.7/Lib/ftplib.py\] - - - - - - This module defines the class [`FTP`](#ftplib.FTP "ftplib.FTP") and a few related items. The [`FTP`](#ftplib.FTP "ftplib.FTP") class implements the client side of the FTP protocol. You can use this to write Python programs that perform a variety of automated FTP jobs, such as mirroring other FTP servers. It is also used by the module [`urllib.request`](urllib.request.xhtml#module-urllib.request "urllib.request: Extensible library for opening URLs.") to handle URLs that use FTP. For more information on FTP (File Transfer Protocol), see Internet [**RFC 959**](https://tools.ietf.org/html/rfc959.html) \[https://tools.ietf.org/html/rfc959.html\]. Here's a sample session using the [`ftplib`](#module-ftplib "ftplib: FTP protocol client (requires sockets).") module: ``` >>> 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=None*, *source\_address=None*)Return a new instance of the [`FTP`](#ftplib.FTP "ftplib.FTP") class. When *host* is given, the method call `connect(host)` is made. When *user* is given, additionally the method call `login(user, passwd, acct)` is made (where *passwd* and *acct* default to the empty string when not given). The optional *timeout*parameter specifies a timeout in seconds for blocking operations like the connection attempt (if is not specified, the global default timeout setting will be used). *source\_address* is a 2-tuple `(host, port)` for the socket to bind to as its source address before connecting. The [`FTP`](#ftplib.FTP "ftplib.FTP") class supports the [`with`](../reference/compound_stmts.xhtml#with) statement, e.g.: ``` >>> from ftplib import FTP >>> with FTP("ftp1.at.proftpd.org") as ftp: ... ftp.login() ... ftp.dir() ... # doctest: +SKIP '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`](../reference/compound_stmts.xhtml#with) 语句。 在 3.3 版更改: *source\_address* parameter was added. *class* `ftplib.``FTP_TLS`(*host=''*, *user=''*, *passwd=''*, *acct=''*, *keyfile=None*, *certfile=None*, *context=None*, *timeout=None*, *source\_address=None*)A [`FTP`](#ftplib.FTP "ftplib.FTP") subclass which adds TLS support to FTP as described in [**RFC 4217**](https://tools.ietf.org/html/rfc4217.html) \[https://tools.ietf.org/html/rfc4217.html\]. Connect as usual to port 21 implicitly securing the FTP control connection before authenticating. Securing the data connection requires the user to explicitly ask for it by calling the [`prot_p()`](#ftplib.FTP_TLS.prot_p "ftplib.FTP_TLS.prot_p") method. *context*is a [`ssl.SSLContext`](ssl.xhtml#ssl.SSLContext "ssl.SSLContext") object which allows bundling SSL configuration options, certificates and private keys into a single (potentially long-lived) structure. Please read [Security considerations](ssl.xhtml#ssl-security) for best practices. *keyfile* and *certfile* are a legacy alternative to *context* -- they can 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 with [`ssl.SSLContext.check_hostname`](ssl.xhtml#ssl.SSLContext.check_hostname "ssl.SSLContext.check_hostname") and *Server Name Indication* (see [`ssl.HAS_SNI`](ssl.xhtml#ssl.HAS_SNI "ssl.HAS_SNI")). 3\.6 版后已移除: *keyfile* and *certfile* are deprecated in favor of *context*. Please use [`ssl.SSLContext.load_cert_chain()`](ssl.xhtml#ssl.SSLContext.load_cert_chain "ssl.SSLContext.load_cert_chain") instead, or let [`ssl.create_default_context()`](ssl.xhtml#ssl.create_default_context "ssl.create_default_context") select the system's trusted CA certificates for you. Here's a sample session using the [`FTP_TLS`](#ftplib.FTP_TLS "ftplib.FTP_TLS") class: ``` >>> 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 raised when an unexpected reply is received from the server. *exception* `ftplib.``error_temp`Exception raised when an error code signifying a temporary error (response codes in the range 400--499) is received. *exception* `ftplib.``error_perm`Exception raised when an error code signifying a permanent error (response codes in the range 500--599) is received. *exception* `ftplib.``error_proto`Exception raised when a reply is received from the server that does not fit the response specifications of the File Transfer Protocol, i.e. begin with a digit in the range 1--5. `ftplib.``all_errors`The set of all exceptions (as a tuple) that methods of [`FTP`](#ftplib.FTP "ftplib.FTP")instances may raise as a result of problems with the FTP connection (as opposed to programming errors made by the caller). This set includes the four exceptions listed above as well as [`OSError`](exceptions.xhtml#OSError "OSError"). 参见 Module [`netrc`](netrc.xhtml#module-netrc "netrc: Loading of .netrc files.")Parser for the `.netrc` file format. The file `.netrc` is typically used by FTP clients to load user authentication information before prompting the user. ## FTP Objects Several methods are available in two flavors: one for handling text files and another for binary files. These are named for the command which is used followed by `lines` for the text version or `binary` for the binary version. [`FTP`](#ftplib.FTP "ftplib.FTP") instances have the following methods: `FTP.``set_debuglevel`(*level*)Set the instance's debugging level. This controls the amount of debugging output printed. The default, `0`, produces no debugging output. A value of `1` produces a moderate amount of debugging output, generally a single line per request. A value of `2` or higher produces the maximum amount of debugging 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`, as specified by the FTP protocol specification. It is rarely needed to specify a different port number. This function should be called only once for each instance; it should not be called at all if a host was given when the instance was created. All other methods can only be used after a connection has been made. The optional *timeout* parameter specifies a timeout in seconds for the connection attempt. If no *timeout* is passed, the global default timeout setting will be used. *source\_address* is a 2-tuple `(host, port)` for the socket to bind to as its 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 initial connection. (This message sometimes contains disclaimers or help information that 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 and default 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 a host and user were given when the instance was created. Most FTP commands are only 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, but it'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. Return nothing if a response code corresponding to success (codes in the range 200--299) is received. Raise [`error_reply`](#ftplib.error_reply "ftplib.error_reply") otherwise. `FTP.``retrbinary`(*cmd*, *callback*, *blocksize=8192*, *rest=None*)Retrieve a file in binary transfer mode. *cmd* should be an appropriate `RETR` command: `'RETR filename'`. The *callback* function is called for each block of data received, with a single bytes argument giving the data block. The optional *blocksize* argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to *callback*). A reasonable default is chosen. *rest* means the same thing as in the [`transfercmd()`](#ftplib.FTP.transfercmd "ftplib.FTP.transfercmd") method. `FTP.``retrlines`(*cmd*, *callback=None*)Retrieve a file or directory listing in ASCII transfer mode. *cmd* should be an appropriate `RETR` command (see [`retrbinary()`](#ftplib.FTP.retrbinary "ftplib.FTP.retrbinary")) or a command such as `LIST` 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 argument containing the line with the trailing CRLF stripped. The default *callback*prints the line to `sys.stdout`. `FTP.``set_pasv`(*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 appropriate `STOR` command: `"STOR filename"`. *fp* is a [file object](../glossary.xhtml#term-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 single parameter callable that is called on each block of data after it is sent. *rest* means the same thing as in the [`transfercmd()`](#ftplib.FTP.transfercmd "ftplib.FTP.transfercmd") method. 在 3.2 版更改: *rest* parameter added. `FTP.``storlines`(*cmd*, *fp*, *callback=None*)Store a file in ASCII transfer mode. *cmd* should be an appropriate `STOR` command (see [`storbinary()`](#ftplib.FTP.storbinary "ftplib.FTP.storbinary")). Lines are read until EOF from the [file object](../glossary.xhtml#term-file-object) *fp* (opened in binary mode) using its [`readline()`](io.xhtml#io.IOBase.readline "io.IOBase.readline")method to provide the data to be stored. *callback* is an optional single parameter 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 an `EPRT` or `PORT` command and the transfer command specified by *cmd*, and accept the connection. If the server is passive, send an `EPSV` or `PASV`command, connect to it, and start the transfer command. Either way, return the socket for the connection. If optional *rest* is given, a `REST` command is sent to the server, passing *rest* 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**](https://tools.ietf.org/html/rfc959.html) \[https://tools.ietf.org/html/rfc959.html\] requires only that *rest* be a string containing characters in the printable range from ASCII code 33 to ASCII code 126. The [`transfercmd()`](#ftplib.FTP.transfercmd "ftplib.FTP.transfercmd") method, therefore, converts *rest* to a string, but no check is performed on the string's contents. If the server does not recognize the `REST` command, an [`error_reply`](#ftplib.error_reply "ftplib.error_reply") exception will be raised. If this happens, simply call [`transfercmd()`](#ftplib.FTP.transfercmd "ftplib.FTP.transfercmd") without a *rest* argument. `FTP.``ntransfercmd`(*cmd*, *rest=None*)Like [`transfercmd()`](#ftplib.FTP.transfercmd "ftplib.FTP.transfercmd"), but returns a tuple of the data connection and the expected size of the data. If the expected size could not be computed, `None`will be returned as the expected size. *cmd* and *rest* means the same thing as in [`transfercmd()`](#ftplib.FTP.transfercmd "ftplib.FTP.transfercmd"). `FTP.``mlsd`(*path=""*, *facts=\[\]*)List a directory in a standardized format by using `MLSD` command ([**RFC 3659**](https://tools.ietf.org/html/rfc3659.html) \[https://tools.ietf.org/html/rfc3659.html\]). 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 a tuple of two elements for every file found in path. First element is the file name, the second one is a dictionary containing facts about the file name. Content of this dictionary might be limited by the *facts* argument but 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. The optional *argument* is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the `NLST` command. 注解 If your server supports the command, [`mlsd()`](#ftplib.FTP.mlsd "ftplib.FTP.mlsd") offers a better API. `FTP.``dir`(*argument*\[, *...*\])Produce a directory listing as returned by the `LIST` command, printing it to standard output. The optional *argument* is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the `LIST` command. If the last argument is a function, it is used as a *callback* function as for [`retrlines()`](#ftplib.FTP.retrlines "ftplib.FTP.retrlines"); the default prints to `sys.stdout`. This method returns `None`. 注解 If your server supports the command, [`mlsd()`](#ftplib.FTP.mlsd "ftplib.FTP.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 the text of the response, otherwise raises [`error_perm`](#ftplib.error_perm "ftplib.error_perm") on permission errors or [`error_reply`](#ftplib.error_reply "ftplib.error_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, the size of the file is returned as an integer, otherwise `None` is returned. Note that the `SIZE` command is not standardized, but is supported by many common 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 server responds with an error to the `QUIT` command. This implies a call to the [`close()`](#ftplib.FTP.close "ftplib.FTP.close") method which renders the [`FTP`](#ftplib.FTP "ftplib.FTP") instance useless for subsequent calls (see below). `FTP.``close`()Close the connection unilaterally. This should not be applied to an already closed connection such as after a successful call to [`quit()`](#ftplib.FTP.quit "ftplib.FTP.quit"). After this call the [`FTP`](#ftplib.FTP "ftplib.FTP") instance should not be used any more (after a call to [`close()`](#ftplib.FTP.close "ftplib.FTP.close") or [`quit()`](#ftplib.FTP.quit "ftplib.FTP.quit") you cannot reopen the connection by issuing another [`login()`](#ftplib.FTP.login "ftplib.FTP.login") method). ## FTP\_TLS Objects [`FTP_TLS`](#ftplib.FTP_TLS "ftplib.FTP_TLS") class inherits from [`FTP`](#ftplib.FTP "ftplib.FTP"), defining these additional objects: `FTP_TLS.``ssl_version`The SSL version to use (defaults to [`ssl.PROTOCOL_SSLv23`](ssl.xhtml#ssl.PROTOCOL_SSLv23 "ssl.PROTOCOL_SSLv23")). `FTP_TLS.``auth`()Set up a secure control connection by using TLS or SSL, depending on what is specified in the [`ssl_version`](#ftplib.FTP_TLS.ssl_version "ftplib.FTP_TLS.ssl_version") attribute. 在 3.4 版更改: The method now supports hostname check with [`ssl.SSLContext.check_hostname`](ssl.xhtml#ssl.SSLContext.check_hostname "ssl.SSLContext.check_hostname") and *Server Name Indication* (see [`ssl.HAS_SNI`](ssl.xhtml#ssl.HAS_SNI "ssl.HAS_SNI")). `FTP_TLS.``ccc`()Revert control channel back to plaintext. This can be useful to take advantage of firewalls that know how to handle NAT with non-secure FTP without opening fixed ports. 3\.3 新版功能. `FTP_TLS.``prot_p`()Set up secure data connection. `FTP_TLS.``prot_c`()Set up clear text data connection. ### 导航 - [索引](../genindex.xhtml "总目录") - [模块](../py-modindex.xhtml "Python 模块索引") | - [下一页](poplib.xhtml "poplib --- POP3 protocol client") | - [上一页](http.client.xhtml "http.client --- HTTP协议客户端") | - ![](https://box.kancloud.cn/a721fc7ec672275e257bbbfde49a4d4e_16x16.png) - [Python](https://www.python.org/) » - zh\_CN 3.7.3 [文档](../index.xhtml) » - [Python 标准库](index.xhtml) » - [互联网协议和支持](internet.xhtml) » - $('.inline-search').show(0); | © [版权所有](../copyright.xhtml) 2001-2019, Python Software Foundation. Python 软件基金会是一个非盈利组织。 [请捐助。](https://www.python.org/psf/donations/) 最后更新于 5月 21, 2019. [发现了问题](../bugs.xhtml)? 使用[Sphinx](http://sphinx.pocoo.org/)1.8.4 创建。