Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`ftplib` --- FTP protocol client |
| 2 | ===================================== |
| 3 | |
| 4 | .. module:: ftplib |
| 5 | :synopsis: FTP protocol client (requires sockets). |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | **Source code:** :source:`Lib/ftplib.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | .. index:: |
| 10 | pair: FTP; protocol |
| 11 | single: FTP; ftplib (standard module) |
| 12 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 13 | -------------- |
| 14 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | This module defines the class :class:`FTP` and a few related items. The |
| 16 | :class:`FTP` class implements the client side of the FTP protocol. You can use |
| 17 | this to write Python programs that perform a variety of automated FTP jobs, such |
Martin Panter | fe289c0 | 2016-05-28 02:20:39 +0000 | [diff] [blame] | 18 | as mirroring other FTP servers. It is also used by the module |
Senthil Kumaran | aca8fd7 | 2008-06-23 04:41:59 +0000 | [diff] [blame] | 19 | :mod:`urllib.request` to handle URLs that use FTP. For more information on FTP |
| 20 | (File Transfer Protocol), see Internet :rfc:`959`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | |
| 22 | Here's a sample session using the :mod:`ftplib` module:: |
| 23 | |
| 24 | >>> from ftplib import FTP |
Georg Brandl | 036e41d | 2013-10-06 18:17:56 +0200 | [diff] [blame] | 25 | >>> ftp = FTP('ftp.debian.org') # connect to host, default port |
| 26 | >>> ftp.login() # user anonymous, passwd anonymous@ |
| 27 | '230 Login successful.' |
| 28 | >>> ftp.cwd('debian') # change into "debian" directory |
| 29 | >>> ftp.retrlines('LIST') # list directory contents |
| 30 | -rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README |
| 31 | ... |
| 32 | drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool |
| 33 | drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project |
| 34 | drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools |
| 35 | '226 Directory send OK.' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | >>> ftp.retrbinary('RETR README', open('README', 'wb').write) |
| 37 | '226 Transfer complete.' |
| 38 | >>> ftp.quit() |
| 39 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
Benjamin Peterson | 5e55b3e | 2010-02-03 02:35:45 +0000 | [diff] [blame] | 41 | The module defines the following items: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
Giampaolo Rodolà | 396ff06 | 2011-02-28 19:19:51 +0000 | [diff] [blame] | 43 | .. class:: FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
| 45 | Return a new instance of the :class:`FTP` class. When *host* is given, the |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 46 | method call ``connect(host)`` is made. When *user* is given, additionally |
| 47 | the method call ``login(user, passwd, acct)`` is made (where *passwd* and |
| 48 | *acct* default to the empty string when not given). The optional *timeout* |
| 49 | parameter specifies a timeout in seconds for blocking operations like the |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 50 | connection attempt (if is not specified, the global default timeout setting |
Giampaolo Rodolà | 396ff06 | 2011-02-28 19:19:51 +0000 | [diff] [blame] | 51 | will be used). *source_address* is a 2-tuple ``(host, port)`` for the socket |
| 52 | to bind to as its source address before connecting. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
Martin Panter | 828123c | 2015-11-21 22:03:08 +0000 | [diff] [blame] | 54 | The :class:`FTP` class supports the :keyword:`with` statement, e.g.: |
Giampaolo Rodolà | bd576b7 | 2010-05-10 14:53:29 +0000 | [diff] [blame] | 55 | |
| 56 | >>> from ftplib import FTP |
| 57 | >>> with FTP("ftp1.at.proftpd.org") as ftp: |
| 58 | ... ftp.login() |
| 59 | ... ftp.dir() |
Zachary Ware | 9f8b3a0 | 2016-08-10 00:59:59 -0500 | [diff] [blame] | 60 | ... # doctest: +SKIP |
Giampaolo Rodolà | bd576b7 | 2010-05-10 14:53:29 +0000 | [diff] [blame] | 61 | '230 Anonymous login ok, restrictions apply.' |
| 62 | dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 . |
| 63 | dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 .. |
| 64 | dr-xr-xr-x 5 ftp ftp 4096 May 6 10:43 CentOS |
| 65 | dr-xr-xr-x 3 ftp ftp 18 Jul 10 2008 Fedora |
| 66 | >>> |
| 67 | |
| 68 | .. versionchanged:: 3.2 |
| 69 | Support for the :keyword:`with` statement was added. |
| 70 | |
Giampaolo Rodolà | 396ff06 | 2011-02-28 19:19:51 +0000 | [diff] [blame] | 71 | .. versionchanged:: 3.3 |
| 72 | *source_address* parameter was added. |
Giampaolo Rodolà | bd576b7 | 2010-05-10 14:53:29 +0000 | [diff] [blame] | 73 | |
Giampaolo Rodolà | 396ff06 | 2011-02-28 19:19:51 +0000 | [diff] [blame] | 74 | |
| 75 | .. class:: FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None) |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 76 | |
| 77 | A :class:`FTP` subclass which adds TLS support to FTP as described in |
| 78 | :rfc:`4217`. |
| 79 | Connect as usual to port 21 implicitly securing the FTP control connection |
Benjamin Peterson | 5e55b3e | 2010-02-03 02:35:45 +0000 | [diff] [blame] | 80 | before authenticating. Securing the data connection requires the user to |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 81 | explicitly ask for it by calling the :meth:`prot_p` method. *context* |
| 82 | is a :class:`ssl.SSLContext` object which allows bundling SSL configuration |
| 83 | options, certificates and private keys into a single (potentially |
| 84 | long-lived) structure. Please read :ref:`ssl-security` for best practices. |
| 85 | |
| 86 | *keyfile* and *certfile* are a legacy alternative to *context* -- they |
| 87 | can point to PEM-formatted private key and certificate chain files |
| 88 | (respectively) for the SSL connection. |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 89 | |
Benjamin Peterson | 5e55b3e | 2010-02-03 02:35:45 +0000 | [diff] [blame] | 90 | .. versionadded:: 3.2 |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 91 | |
Giampaolo Rodolà | 396ff06 | 2011-02-28 19:19:51 +0000 | [diff] [blame] | 92 | .. versionchanged:: 3.3 |
| 93 | *source_address* parameter was added. |
| 94 | |
Christian Heimes | e5b5edf | 2013-12-02 02:56:02 +0100 | [diff] [blame] | 95 | .. versionchanged:: 3.4 |
| 96 | The class now supports hostname check with |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 97 | :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see |
| 98 | :data:`ssl.HAS_SNI`). |
Christian Heimes | e5b5edf | 2013-12-02 02:56:02 +0100 | [diff] [blame] | 99 | |
Christian Heimes | d048637 | 2016-09-10 23:23:33 +0200 | [diff] [blame] | 100 | .. deprecated:: 3.6 |
| 101 | |
| 102 | *keyfile* and *certfile* are deprecated in favor of *context*. |
| 103 | Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let |
| 104 | :func:`ssl.create_default_context` select the system's trusted CA |
| 105 | certificates for you. |
| 106 | |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 107 | Here's a sample session using the :class:`FTP_TLS` class:: |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 108 | |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 109 | >>> ftps = FTP_TLS('ftp.pureftpd.org') |
| 110 | >>> ftps.login() |
| 111 | '230 Anonymous user logged in' |
| 112 | >>> ftps.prot_p() |
| 113 | '200 Data protection level set to "private"' |
| 114 | >>> ftps.nlst() |
| 115 | ['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'] |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 116 | |
| 117 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 118 | .. exception:: error_reply |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 120 | Exception raised when an unexpected reply is received from the server. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
| 122 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 123 | .. exception:: error_temp |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 125 | Exception raised when an error code signifying a temporary error (response |
| 126 | codes in the range 400--499) is received. |
| 127 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 128 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 129 | .. exception:: error_perm |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 131 | Exception raised when an error code signifying a permanent error (response |
| 132 | codes in the range 500--599) is received. |
| 133 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 134 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 135 | .. exception:: error_proto |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 137 | Exception raised when a reply is received from the server that does not fit |
| 138 | the response specifications of the File Transfer Protocol, i.e. begin with a |
| 139 | digit in the range 1--5. |
| 140 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
Benjamin Peterson | 5e55b3e | 2010-02-03 02:35:45 +0000 | [diff] [blame] | 142 | .. data:: all_errors |
| 143 | |
| 144 | The set of all exceptions (as a tuple) that methods of :class:`FTP` |
| 145 | instances may raise as a result of problems with the FTP connection (as |
| 146 | opposed to programming errors made by the caller). This set includes the |
Antoine Pitrou | 5574c30 | 2011-10-12 17:53:43 +0200 | [diff] [blame] | 147 | four exceptions listed above as well as :exc:`OSError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 149 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | .. seealso:: |
| 151 | |
| 152 | Module :mod:`netrc` |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 153 | Parser for the :file:`.netrc` file format. The file :file:`.netrc` is |
| 154 | typically used by FTP clients to load user authentication information |
| 155 | before prompting the user. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | |
| 158 | .. _ftp-objects: |
| 159 | |
| 160 | FTP Objects |
| 161 | ----------- |
| 162 | |
| 163 | Several methods are available in two flavors: one for handling text files and |
| 164 | another for binary files. These are named for the command which is used |
| 165 | followed by ``lines`` for the text version or ``binary`` for the binary version. |
| 166 | |
| 167 | :class:`FTP` instances have the following methods: |
| 168 | |
| 169 | |
| 170 | .. method:: FTP.set_debuglevel(level) |
| 171 | |
| 172 | Set the instance's debugging level. This controls the amount of debugging |
| 173 | output printed. The default, ``0``, produces no debugging output. A value of |
| 174 | ``1`` produces a moderate amount of debugging output, generally a single line |
| 175 | per request. A value of ``2`` or higher produces the maximum amount of |
| 176 | debugging output, logging each line sent and received on the control connection. |
| 177 | |
| 178 | |
Giampaolo Rodolà | 396ff06 | 2011-02-28 19:19:51 +0000 | [diff] [blame] | 179 | .. method:: FTP.connect(host='', port=0, timeout=None, source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
| 181 | Connect to the given host and port. The default port number is ``21``, as |
| 182 | specified by the FTP protocol specification. It is rarely needed to specify a |
| 183 | different port number. This function should be called only once for each |
| 184 | instance; it should not be called at all if a host was given when the instance |
| 185 | was created. All other methods can only be used after a connection has been |
| 186 | made. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | The optional *timeout* parameter specifies a timeout in seconds for the |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 188 | connection attempt. If no *timeout* is passed, the global default timeout |
| 189 | setting will be used. |
Giampaolo Rodolà | 396ff06 | 2011-02-28 19:19:51 +0000 | [diff] [blame] | 190 | *source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as |
| 191 | its source address before connecting. |
| 192 | |
| 193 | .. versionchanged:: 3.3 |
| 194 | *source_address* parameter was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 195 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 196 | |
| 197 | .. method:: FTP.getwelcome() |
| 198 | |
| 199 | Return the welcome message sent by the server in reply to the initial |
| 200 | connection. (This message sometimes contains disclaimers or help information |
| 201 | that may be relevant to the user.) |
| 202 | |
| 203 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 204 | .. method:: FTP.login(user='anonymous', passwd='', acct='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | |
| 206 | Log in as the given *user*. The *passwd* and *acct* parameters are optional and |
| 207 | default to the empty string. If no *user* is specified, it defaults to |
| 208 | ``'anonymous'``. If *user* is ``'anonymous'``, the default *passwd* is |
| 209 | ``'anonymous@'``. This function should be called only once for each instance, |
| 210 | after a connection has been established; it should not be called at all if a |
| 211 | host and user were given when the instance was created. Most FTP commands are |
Benjamin Peterson | 8719ad5 | 2009-09-11 22:24:02 +0000 | [diff] [blame] | 212 | only allowed after the client has logged in. The *acct* parameter supplies |
| 213 | "accounting information"; few systems implement this. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 214 | |
| 215 | |
| 216 | .. method:: FTP.abort() |
| 217 | |
| 218 | Abort a file transfer that is in progress. Using this does not always work, but |
| 219 | it's worth a try. |
| 220 | |
| 221 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 222 | .. method:: FTP.sendcmd(cmd) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 223 | |
| 224 | Send a simple command string to the server and return the response string. |
| 225 | |
| 226 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 227 | .. method:: FTP.voidcmd(cmd) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 228 | |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 229 | Send a simple command string to the server and handle the response. Return |
| 230 | nothing if a response code corresponding to success (codes in the range |
| 231 | 200--299) is received. Raise :exc:`error_reply` otherwise. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
| 233 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 234 | .. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 236 | Retrieve a file in binary transfer mode. *cmd* should be an appropriate |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | ``RETR`` command: ``'RETR filename'``. The *callback* function is called for |
Jelle Zijlstra | 9e52c90 | 2017-03-12 19:51:27 -0700 | [diff] [blame] | 238 | each block of data received, with a single bytes argument giving the data |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 239 | block. The optional *blocksize* argument specifies the maximum chunk size to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | read on the low-level socket object created to do the actual transfer (which |
| 241 | will also be the largest size of the data blocks passed to *callback*). A |
| 242 | reasonable default is chosen. *rest* means the same thing as in the |
| 243 | :meth:`transfercmd` method. |
| 244 | |
| 245 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 246 | .. method:: FTP.retrlines(cmd, callback=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 248 | Retrieve a file or directory listing in ASCII transfer mode. *cmd* should be |
| 249 | an appropriate ``RETR`` command (see :meth:`retrbinary`) or a command such as |
Giampaolo Rodola' | d78def9 | 2011-05-06 19:49:08 +0200 | [diff] [blame] | 250 | ``LIST`` or ``NLST`` (usually just the string ``'LIST'``). |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 251 | ``LIST`` retrieves a list of files and information about those files. |
Giampaolo Rodola' | d78def9 | 2011-05-06 19:49:08 +0200 | [diff] [blame] | 252 | ``NLST`` retrieves a list of file names. |
| 253 | The *callback* function is called for each line with a string argument |
| 254 | containing the line with the trailing CRLF stripped. The default *callback* |
| 255 | prints the line to ``sys.stdout``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 256 | |
| 257 | |
Jelle Zijlstra | 7bb6ac7 | 2017-03-12 19:19:00 -0700 | [diff] [blame] | 258 | .. method:: FTP.set_pasv(val) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 259 | |
Jelle Zijlstra | 7bb6ac7 | 2017-03-12 19:19:00 -0700 | [diff] [blame] | 260 | Enable "passive" mode if *val* is true, otherwise disable passive mode. |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 261 | Passive mode is on by default. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 262 | |
| 263 | |
Berker Peksag | b2fdafe | 2014-10-08 13:15:04 +0300 | [diff] [blame] | 264 | .. method:: FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 265 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 266 | Store a file in binary transfer mode. *cmd* should be an appropriate |
Berker Peksag | b2fdafe | 2014-10-08 13:15:04 +0300 | [diff] [blame] | 267 | ``STOR`` command: ``"STOR filename"``. *fp* is a :term:`file object` |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 268 | (opened in binary mode) which is read until EOF using its :meth:`~io.IOBase.read` |
Ezio Melotti | cbd449b | 2012-10-05 14:09:59 +0300 | [diff] [blame] | 269 | method in blocks of size *blocksize* to provide the data to be stored. |
| 270 | The *blocksize* argument defaults to 8192. *callback* is an optional single |
| 271 | parameter callable that is called on each block of data after it is sent. |
| 272 | *rest* means the same thing as in the :meth:`transfercmd` method. |
Antoine Pitrou | 648bcd7 | 2009-11-27 13:23:26 +0000 | [diff] [blame] | 273 | |
| 274 | .. versionchanged:: 3.2 |
| 275 | *rest* parameter added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 276 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 277 | |
Berker Peksag | b2fdafe | 2014-10-08 13:15:04 +0300 | [diff] [blame] | 278 | .. method:: FTP.storlines(cmd, fp, callback=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 279 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 280 | Store a file in ASCII transfer mode. *cmd* should be an appropriate |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 281 | ``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the |
Berker Peksag | b2fdafe | 2014-10-08 13:15:04 +0300 | [diff] [blame] | 282 | :term:`file object` *fp* (opened in binary mode) using its :meth:`~io.IOBase.readline` |
Ezio Melotti | cbd449b | 2012-10-05 14:09:59 +0300 | [diff] [blame] | 283 | method to provide the data to be stored. *callback* is an optional single |
| 284 | parameter callable that is called on each line after it is sent. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
| 286 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 287 | .. method:: FTP.transfercmd(cmd, rest=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 288 | |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 289 | Initiate a transfer over the data connection. If the transfer is active, send an |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 290 | ``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*, and |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 291 | accept the connection. If the server is passive, send an ``EPSV`` or ``PASV`` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 292 | command, connect to it, and start the transfer command. Either way, return the |
| 293 | socket for the connection. |
| 294 | |
| 295 | If optional *rest* is given, a ``REST`` command is sent to the server, passing |
| 296 | *rest* as an argument. *rest* is usually a byte offset into the requested file, |
| 297 | telling the server to restart sending the file's bytes at the requested offset, |
Serhiy Storchaka | 0a36ac1 | 2018-05-31 07:39:00 +0300 | [diff] [blame] | 298 | skipping over the initial bytes. Note however that :rfc:`959` requires only that |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 299 | *rest* be a string containing characters in the printable range from ASCII code |
| 300 | 33 to ASCII code 126. The :meth:`transfercmd` method, therefore, converts |
| 301 | *rest* to a string, but no check is performed on the string's contents. If the |
| 302 | server does not recognize the ``REST`` command, an :exc:`error_reply` exception |
| 303 | will be raised. If this happens, simply call :meth:`transfercmd` without a |
| 304 | *rest* argument. |
| 305 | |
| 306 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 307 | .. method:: FTP.ntransfercmd(cmd, rest=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 308 | |
| 309 | Like :meth:`transfercmd`, but returns a tuple of the data connection and the |
| 310 | expected size of the data. If the expected size could not be computed, ``None`` |
| 311 | will be returned as the expected size. *cmd* and *rest* means the same thing as |
| 312 | in :meth:`transfercmd`. |
| 313 | |
| 314 | |
Giampaolo Rodola' | d78def9 | 2011-05-06 19:49:08 +0200 | [diff] [blame] | 315 | .. method:: FTP.mlsd(path="", facts=[]) |
| 316 | |
Gregory P. Smith | f1b3134 | 2015-12-13 22:10:28 -0800 | [diff] [blame] | 317 | List a directory in a standardized format by using ``MLSD`` command |
Giampaolo Rodola' | a55efb3 | 2011-05-07 16:06:59 +0200 | [diff] [blame] | 318 | (:rfc:`3659`). If *path* is omitted the current directory is assumed. |
Giampaolo Rodola' | d78def9 | 2011-05-06 19:49:08 +0200 | [diff] [blame] | 319 | *facts* is a list of strings representing the type of information desired |
Giampaolo Rodola' | a55efb3 | 2011-05-07 16:06:59 +0200 | [diff] [blame] | 320 | (e.g. ``["type", "size", "perm"]``). Return a generator object yielding a |
| 321 | tuple of two elements for every file found in path. First element is the |
| 322 | file name, the second one is a dictionary containing facts about the file |
| 323 | name. Content of this dictionary might be limited by the *facts* argument |
| 324 | but server is not guaranteed to return all requested facts. |
Giampaolo Rodola' | d78def9 | 2011-05-06 19:49:08 +0200 | [diff] [blame] | 325 | |
| 326 | .. versionadded:: 3.3 |
| 327 | |
| 328 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 329 | .. method:: FTP.nlst(argument[, ...]) |
| 330 | |
Georg Brandl | 392c92a | 2010-10-15 19:46:19 +0000 | [diff] [blame] | 331 | Return a list of file names as returned by the ``NLST`` command. The |
| 332 | optional *argument* is a directory to list (default is the current server |
| 333 | directory). Multiple arguments can be used to pass non-standard options to |
| 334 | the ``NLST`` command. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 335 | |
Gregory P. Smith | f1b3134 | 2015-12-13 22:10:28 -0800 | [diff] [blame] | 336 | .. note:: If your server supports the command, :meth:`mlsd` offers a better API. |
Giampaolo Rodola' | d78def9 | 2011-05-06 19:49:08 +0200 | [diff] [blame] | 337 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 338 | |
| 339 | .. method:: FTP.dir(argument[, ...]) |
| 340 | |
| 341 | Produce a directory listing as returned by the ``LIST`` command, printing it to |
| 342 | standard output. The optional *argument* is a directory to list (default is the |
| 343 | current server directory). Multiple arguments can be used to pass non-standard |
| 344 | options to the ``LIST`` command. If the last argument is a function, it is used |
| 345 | as a *callback* function as for :meth:`retrlines`; the default prints to |
| 346 | ``sys.stdout``. This method returns ``None``. |
| 347 | |
Gregory P. Smith | f1b3134 | 2015-12-13 22:10:28 -0800 | [diff] [blame] | 348 | .. note:: If your server supports the command, :meth:`mlsd` offers a better API. |
Giampaolo Rodola' | d78def9 | 2011-05-06 19:49:08 +0200 | [diff] [blame] | 349 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 350 | |
| 351 | .. method:: FTP.rename(fromname, toname) |
| 352 | |
| 353 | Rename file *fromname* on the server to *toname*. |
| 354 | |
| 355 | |
| 356 | .. method:: FTP.delete(filename) |
| 357 | |
| 358 | Remove the file named *filename* from the server. If successful, returns the |
| 359 | text of the response, otherwise raises :exc:`error_perm` on permission errors or |
| 360 | :exc:`error_reply` on other errors. |
| 361 | |
| 362 | |
| 363 | .. method:: FTP.cwd(pathname) |
| 364 | |
| 365 | Set the current directory on the server. |
| 366 | |
| 367 | |
| 368 | .. method:: FTP.mkd(pathname) |
| 369 | |
| 370 | Create a new directory on the server. |
| 371 | |
| 372 | |
| 373 | .. method:: FTP.pwd() |
| 374 | |
| 375 | Return the pathname of the current directory on the server. |
| 376 | |
| 377 | |
| 378 | .. method:: FTP.rmd(dirname) |
| 379 | |
| 380 | Remove the directory named *dirname* on the server. |
| 381 | |
| 382 | |
| 383 | .. method:: FTP.size(filename) |
| 384 | |
| 385 | Request the size of the file named *filename* on the server. On success, the |
| 386 | size of the file is returned as an integer, otherwise ``None`` is returned. |
| 387 | Note that the ``SIZE`` command is not standardized, but is supported by many |
| 388 | common server implementations. |
| 389 | |
| 390 | |
| 391 | .. method:: FTP.quit() |
| 392 | |
| 393 | Send a ``QUIT`` command to the server and close the connection. This is the |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 394 | "polite" way to close a connection, but it may raise an exception if the server |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 395 | responds with an error to the ``QUIT`` command. This implies a call to the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 396 | :meth:`close` method which renders the :class:`FTP` instance useless for |
| 397 | subsequent calls (see below). |
| 398 | |
| 399 | |
| 400 | .. method:: FTP.close() |
| 401 | |
| 402 | Close the connection unilaterally. This should not be applied to an already |
Jesus Cea | c73f863 | 2012-12-26 16:47:03 +0100 | [diff] [blame] | 403 | closed connection such as after a successful call to :meth:`~FTP.quit`. |
| 404 | After this call the :class:`FTP` instance should not be used any more (after |
| 405 | a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the |
| 406 | connection by issuing another :meth:`login` method). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 407 | |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 408 | |
| 409 | FTP_TLS Objects |
| 410 | --------------- |
| 411 | |
| 412 | :class:`FTP_TLS` class inherits from :class:`FTP`, defining these additional objects: |
| 413 | |
| 414 | .. attribute:: FTP_TLS.ssl_version |
| 415 | |
Benjamin Peterson | bab69bf | 2014-12-30 15:17:03 -0600 | [diff] [blame] | 416 | The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`). |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 417 | |
| 418 | .. method:: FTP_TLS.auth() |
| 419 | |
Martin Panter | 2e4571a | 2015-11-14 01:07:43 +0000 | [diff] [blame] | 420 | Set up a secure control connection by using TLS or SSL, depending on what |
| 421 | is specified in the :attr:`ssl_version` attribute. |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 422 | |
Christian Heimes | e5b5edf | 2013-12-02 02:56:02 +0100 | [diff] [blame] | 423 | .. versionchanged:: 3.4 |
| 424 | The method now supports hostname check with |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 425 | :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see |
| 426 | :data:`ssl.HAS_SNI`). |
Christian Heimes | e5b5edf | 2013-12-02 02:56:02 +0100 | [diff] [blame] | 427 | |
Giampaolo Rodola' | 096dcb1 | 2011-06-27 11:17:51 +0200 | [diff] [blame] | 428 | .. method:: FTP_TLS.ccc() |
| 429 | |
Florent Xicluna | 6d57d21 | 2011-10-23 22:23:57 +0200 | [diff] [blame] | 430 | Revert control channel back to plaintext. This can be useful to take |
Giampaolo Rodola' | 096dcb1 | 2011-06-27 11:17:51 +0200 | [diff] [blame] | 431 | advantage of firewalls that know how to handle NAT with non-secure FTP |
| 432 | without opening fixed ports. |
| 433 | |
| 434 | .. versionadded:: 3.3 |
| 435 | |
Antoine Pitrou | f988cd0 | 2009-11-17 20:21:14 +0000 | [diff] [blame] | 436 | .. method:: FTP_TLS.prot_p() |
| 437 | |
| 438 | Set up secure data connection. |
| 439 | |
| 440 | .. method:: FTP_TLS.prot_c() |
| 441 | |
| 442 | Set up clear text data connection. |