1 :mod:`ftplib` --- FTP protocol client 2 ===================================== 3 4 .. module:: ftplib 5 :synopsis: FTP protocol client (requires sockets). 6 7 **Source code:** :source:`Lib/ftplib.py` 8 9 .. index:: 10 pair: FTP; protocol 11 single: FTP; ftplib (standard module) 12 13 -------------- 14 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 18 as mirroring other FTP servers. It is also used by the module 19 :mod:`urllib.request` to handle URLs that use FTP. For more information on FTP 20 (File Transfer Protocol), see Internet :rfc:`959`. 21 22 Here's a sample session using the :mod:`ftplib` module:: 23 24 >>> from ftplib import FTP 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.' 36 >>> ftp.retrbinary('RETR README', open('README', 'wb').write) 37 '226 Transfer complete.' 38 >>> ftp.quit() 39 40 41 The module defines the following items: 42 43 .. class:: FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None) 44 45 Return a new instance of the :class:`FTP` class. When *host* is given, the 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 50 connection attempt (if is not specified, the global default timeout setting 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. 53 54 The :class:`FTP` class supports the :keyword:`with` statement, e.g.: 55 56 >>> from ftplib import FTP 57 >>> with FTP("ftp1.at.proftpd.org") as ftp: 58 ... ftp.login() 59 ... ftp.dir() 60 ... # doctest: +SKIP 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 71 .. versionchanged:: 3.3 72 *source_address* parameter was added. 73 74 75 .. class:: FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None) 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 80 before authenticating. Securing the data connection requires the user to 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. 89 90 .. versionadded:: 3.2 91 92 .. versionchanged:: 3.3 93 *source_address* parameter was added. 94 95 .. versionchanged:: 3.4 96 The class now supports hostname check with 97 :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see 98 :data:`ssl.HAS_SNI`). 99 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 107 Here's a sample session using the :class:`FTP_TLS` class:: 108 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'] 116 117 118 .. exception:: error_reply 119 120 Exception raised when an unexpected reply is received from the server. 121 122 123 .. exception:: error_temp 124 125 Exception raised when an error code signifying a temporary error (response 126 codes in the range 400--499) is received. 127 128 129 .. exception:: error_perm 130 131 Exception raised when an error code signifying a permanent error (response 132 codes in the range 500--599) is received. 133 134 135 .. exception:: error_proto 136 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 141 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 147 four exceptions listed above as well as :exc:`OSError`. 148 149 150 .. seealso:: 151 152 Module :mod:`netrc` 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. 156 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 179 .. method:: FTP.connect(host='', port=0, timeout=None, source_address=None) 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. 187 The optional *timeout* parameter specifies a timeout in seconds for the 188 connection attempt. If no *timeout* is passed, the global default timeout 189 setting will be used. 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. 195 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 204 .. method:: FTP.login(user='anonymous', passwd='', acct='') 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 212 only allowed after the client has logged in. The *acct* parameter supplies 213 "accounting information"; few systems implement this. 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 222 .. method:: FTP.sendcmd(cmd) 223 224 Send a simple command string to the server and return the response string. 225 226 227 .. method:: FTP.voidcmd(cmd) 228 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. 232 233 234 .. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None) 235 236 Retrieve a file in binary transfer mode. *cmd* should be an appropriate 237 ``RETR`` command: ``'RETR filename'``. The *callback* function is called for 238 each block of data received, with a single bytes argument giving the data 239 block. The optional *blocksize* argument specifies the maximum chunk size to 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 246 .. method:: FTP.retrlines(cmd, callback=None) 247 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 250 ``LIST`` or ``NLST`` (usually just the string ``'LIST'``). 251 ``LIST`` retrieves a list of files and information about those files. 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``. 256 257 258 .. method:: FTP.set_pasv(val) 259 260 Enable "passive" mode if *val* is true, otherwise disable passive mode. 261 Passive mode is on by default. 262 263 264 .. method:: FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None) 265 266 Store a file in binary transfer mode. *cmd* should be an appropriate 267 ``STOR`` command: ``"STOR filename"``. *fp* is a :term:`file object` 268 (opened in binary mode) which is read until EOF using its :meth:`~io.IOBase.read` 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. 273 274 .. versionchanged:: 3.2 275 *rest* parameter added. 276 277 278 .. method:: FTP.storlines(cmd, fp, callback=None) 279 280 Store a file in ASCII transfer mode. *cmd* should be an appropriate 281 ``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the 282 :term:`file object` *fp* (opened in binary mode) using its :meth:`~io.IOBase.readline` 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. 285 286 287 .. method:: FTP.transfercmd(cmd, rest=None) 288 289 Initiate a transfer over the data connection. If the transfer is active, send an 290 ``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*, and 291 accept the connection. If the server is passive, send an ``EPSV`` or ``PASV`` 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, 298 skipping over the initial bytes. Note however that :rfc:`959` requires only that 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 307 .. method:: FTP.ntransfercmd(cmd, rest=None) 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 315 .. method:: FTP.mlsd(path="", facts=[]) 316 317 List a directory in a standardized format by using ``MLSD`` command 318 (:rfc:`3659`). If *path* is omitted the current directory is assumed. 319 *facts* is a list of strings representing the type of information desired 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. 325 326 .. versionadded:: 3.3 327 328 329 .. method:: FTP.nlst(argument[, ...]) 330 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. 335 336 .. note:: If your server supports the command, :meth:`mlsd` offers a better API. 337 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 348 .. note:: If your server supports the command, :meth:`mlsd` offers a better API. 349 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 394 "polite" way to close a connection, but it may raise an exception if the server 395 responds with an error to the ``QUIT`` command. This implies a call to the 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 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). 407 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 416 The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`). 417 418 .. method:: FTP_TLS.auth() 419 420 Set up a secure control connection by using TLS or SSL, depending on what 421 is specified in the :attr:`ssl_version` attribute. 422 423 .. versionchanged:: 3.4 424 The method now supports hostname check with 425 :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see 426 :data:`ssl.HAS_SNI`). 427 428 .. method:: FTP_TLS.ccc() 429 430 Revert control channel back to plaintext. This can be useful to take 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 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. 443
