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