1:mod:`ftplib` --- FTP protocol client 2===================================== 3 4.. module:: ftplib 5 :synopsis: FTP protocol client (requires sockets). 6 7 8.. index:: 9 pair: FTP; protocol 10 single: FTP; ftplib (standard module) 11 12**Source code:** :source:`Lib/ftplib.py` 13 14-------------- 15 16This module defines the class :class:`FTP` and a few related items. The 17:class:`FTP` class implements the client side of the FTP protocol. You can use 18this to write Python programs that perform a variety of automated FTP jobs, such 19as mirroring other FTP servers. It is also used by the module :mod:`urllib` to 20handle URLs that use FTP. For more information on FTP (File Transfer Protocol), 21see Internet :rfc:`959`. 22 23Here's a sample session using the :mod:`ftplib` module:: 24 25 >>> from ftplib import FTP 26 >>> ftp = FTP('ftp.debian.org') # connect to host, default port 27 >>> ftp.login() # user anonymous, passwd anonymous@ 28 '230 Login successful.' 29 >>> ftp.cwd('debian') # change into "debian" directory 30 >>> ftp.retrlines('LIST') # list directory contents 31 -rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README 32 ... 33 drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool 34 drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project 35 drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools 36 '226 Directory send OK.' 37 >>> ftp.retrbinary('RETR README', open('README', 'wb').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]]]]]) 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). 53 54 .. versionchanged:: 2.6 55 *timeout* was added. 56 57 58.. class:: FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]]) 59 60 A :class:`FTP` subclass which adds TLS support to FTP as described in 61 :rfc:`4217`. 62 Connect as usual to port 21 implicitly securing the FTP control connection 63 before authenticating. Securing the data connection requires the user to 64 explicitly ask for it by calling the :meth:`prot_p` method. *context* 65 is a :class:`ssl.SSLContext` object which allows bundling SSL configuration 66 options, certificates and private keys into a single (potentially 67 long-lived) structure. Please read :ref:`ssl-security` for best practices. 68 69 *keyfile* and *certfile* are a legacy alternative to *context* -- they 70 can point to PEM-formatted private key and certificate chain files 71 (respectively) for the SSL connection. 72 73 .. versionadded:: 2.7 74 75 .. versionchanged:: 2.7.10 76 The *context* parameter was added. 77 78 Here's a sample session using the :class:`FTP_TLS` class: 79 80 >>> from ftplib import FTP_TLS 81 >>> ftps = FTP_TLS('ftp.python.org') 82 >>> ftps.login() # login anonymously before securing control channel 83 >>> ftps.prot_p() # switch to secure data connection 84 >>> ftps.retrlines('LIST') # list directory content securely 85 total 9 86 drwxr-xr-x 8 root wheel 1024 Jan 3 1994 . 87 drwxr-xr-x 8 root wheel 1024 Jan 3 1994 .. 88 drwxr-xr-x 2 root wheel 1024 Jan 3 1994 bin 89 drwxr-xr-x 2 root wheel 1024 Jan 3 1994 etc 90 d-wxrwxr-x 2 ftp wheel 1024 Sep 5 13:43 incoming 91 drwxr-xr-x 2 root wheel 1024 Nov 17 1993 lib 92 drwxr-xr-x 6 1094 wheel 1024 Sep 13 19:07 pub 93 drwxr-xr-x 3 root wheel 1024 Jan 3 1994 usr 94 -rw-r--r-- 1 root root 312 Aug 1 1994 welcome.msg 95 '226 Transfer complete.' 96 >>> ftps.quit() 97 >>> 98 99 100.. exception:: error_reply 101 102 Exception raised when an unexpected reply is received from the server. 103 104 105.. exception:: error_temp 106 107 Exception raised when an error code signifying a temporary error (response 108 codes in the range 400--499) is received. 109 110 111.. exception:: error_perm 112 113 Exception raised when an error code signifying a permanent error (response 114 codes in the range 500--599) is received. 115 116 117.. exception:: error_proto 118 119 Exception raised when a reply is received from the server that does not fit 120 the response specifications of the File Transfer Protocol, i.e. begin with a 121 digit in the range 1--5. 122 123 124.. data:: all_errors 125 126 The set of all exceptions (as a tuple) that methods of :class:`FTP` 127 instances may raise as a result of problems with the FTP connection (as 128 opposed to programming errors made by the caller). This set includes the 129 four exceptions listed above as well as :exc:`socket.error` and 130 :exc:`IOError`. 131 132 133.. seealso:: 134 135 Module :mod:`netrc` 136 Parser for the :file:`.netrc` file format. The file :file:`.netrc` is 137 typically used by FTP clients to load user authentication information 138 before prompting the user. 139 140 .. index:: single: ftpmirror.py 141 142 The file :file:`Tools/scripts/ftpmirror.py` in the Python source distribution is 143 a script that can mirror FTP sites, or portions thereof, using the :mod:`ftplib` 144 module. It can be used as an extended example that applies this module. 145 146 147.. _ftp-objects: 148 149FTP Objects 150----------- 151 152Several methods are available in two flavors: one for handling text files and 153another for binary files. These are named for the command which is used 154followed by ``lines`` for the text version or ``binary`` for the binary version. 155 156:class:`FTP` instances have the following methods: 157 158 159.. method:: FTP.set_debuglevel(level) 160 161 Set the instance's debugging level. This controls the amount of debugging 162 output printed. The default, ``0``, produces no debugging output. A value of 163 ``1`` produces a moderate amount of debugging output, generally a single line 164 per request. A value of ``2`` or higher produces the maximum amount of 165 debugging output, logging each line sent and received on the control connection. 166 167 168.. method:: FTP.connect(host[, port[, timeout]]) 169 170 Connect to the given host and port. The default port number is ``21``, as 171 specified by the FTP protocol specification. It is rarely needed to specify a 172 different port number. This function should be called only once for each 173 instance; it should not be called at all if a host was given when the instance 174 was created. All other methods can only be used after a connection has been 175 made. 176 177 The optional *timeout* parameter specifies a timeout in seconds for the 178 connection attempt. If no *timeout* is passed, the global default timeout 179 setting will be used. 180 181 .. versionchanged:: 2.6 182 *timeout* was added. 183 184 185.. method:: FTP.getwelcome() 186 187 Return the welcome message sent by the server in reply to the initial 188 connection. (This message sometimes contains disclaimers or help information 189 that may be relevant to the user.) 190 191 192.. method:: FTP.login([user[, passwd[, acct]]]) 193 194 Log in as the given *user*. The *passwd* and *acct* parameters are optional and 195 default to the empty string. If no *user* is specified, it defaults to 196 ``'anonymous'``. If *user* is ``'anonymous'``, the default *passwd* is 197 ``'anonymous@'``. This function should be called only once for each instance, 198 after a connection has been established; it should not be called at all if a 199 host and user were given when the instance was created. Most FTP commands are 200 only allowed after the client has logged in. The *acct* parameter supplies 201 "accounting information"; few systems implement this. 202 203 204.. method:: FTP.abort() 205 206 Abort a file transfer that is in progress. Using this does not always work, but 207 it's worth a try. 208 209 210.. method:: FTP.sendcmd(command) 211 212 Send a simple command string to the server and return the response string. 213 214 215.. method:: FTP.voidcmd(command) 216 217 Send a simple command string to the server and handle the response. Return 218 nothing if a response code corresponding to success (codes in the range 219 200--299) is received. Raise :exc:`error_reply` otherwise. 220 221 222.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]]) 223 224 Retrieve a file in binary transfer mode. *command* should be an appropriate 225 ``RETR`` command: ``'RETR filename'``. The *callback* function is called for 226 each block of data received, with a single string argument giving the data 227 block. The optional *maxblocksize* argument specifies the maximum chunk size to 228 read on the low-level socket object created to do the actual transfer (which 229 will also be the largest size of the data blocks passed to *callback*). A 230 reasonable default is chosen. *rest* means the same thing as in the 231 :meth:`transfercmd` method. 232 233 234.. method:: FTP.retrlines(command[, callback]) 235 236 Retrieve a file or directory listing in ASCII transfer mode. *command* 237 should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a 238 command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string 239 ``'LIST'``). ``LIST`` retrieves a list of files and information about those files. 240 ``NLST`` retrieves a list of file names. On some servers, ``MLSD`` retrieves 241 a machine readable list of files and information about those files. The *callback* 242 function is called for each line with a string argument containing the line with 243 the trailing CRLF stripped. The default *callback* prints the line to ``sys.stdout``. 244 245 246.. method:: FTP.set_pasv(boolean) 247 248 Enable "passive" mode if *boolean* is true, other disable passive mode. (In 249 Python 2.0 and before, passive mode was off by default; in Python 2.1 and later, 250 it is on by default.) 251 252 253.. method:: FTP.storbinary(command, file[, blocksize, callback, rest]) 254 255 Store a file in binary transfer mode. *command* should be an appropriate 256 ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is 257 read until EOF using its :meth:`read` method in blocks of size *blocksize* to 258 provide the data to be stored. The *blocksize* argument defaults to 8192. 259 *callback* is an optional single parameter callable that is called 260 on each block of data after it is sent. *rest* means the same thing as in 261 the :meth:`transfercmd` method. 262 263 .. versionchanged:: 2.1 264 default for *blocksize* added. 265 266 .. versionchanged:: 2.6 267 *callback* parameter added. 268 269 .. versionchanged:: 2.7 270 *rest* parameter added. 271 272.. method:: FTP.storlines(command, file[, callback]) 273 274 Store a file in ASCII transfer mode. *command* should be an appropriate 275 ``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the 276 open file object *file* using its :meth:`~file.readline` method to provide 277 the data to be stored. *callback* is an optional single parameter callable 278 that is called on each line after it is sent. 279 280 .. versionchanged:: 2.6 281 *callback* parameter added. 282 283 284.. method:: FTP.transfercmd(cmd[, rest]) 285 286 Initiate a transfer over the data connection. If the transfer is active, send an 287 ``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*, and 288 accept the connection. If the server is passive, send an ``EPSV`` or ``PASV`` 289 command, connect to it, and start the transfer command. Either way, return the 290 socket for the connection. 291 292 If optional *rest* is given, a ``REST`` command is sent to the server, passing 293 *rest* as an argument. *rest* is usually a byte offset into the requested file, 294 telling the server to restart sending the file's bytes at the requested offset, 295 skipping over the initial bytes. Note however that RFC 959 requires only that 296 *rest* be a string containing characters in the printable range from ASCII code 297 33 to ASCII code 126. The :meth:`transfercmd` method, therefore, converts 298 *rest* to a string, but no check is performed on the string's contents. If the 299 server does not recognize the ``REST`` command, an :exc:`error_reply` exception 300 will be raised. If this happens, simply call :meth:`transfercmd` without a 301 *rest* argument. 302 303 304.. method:: FTP.ntransfercmd(cmd[, rest]) 305 306 Like :meth:`transfercmd`, but returns a tuple of the data connection and the 307 expected size of the data. If the expected size could not be computed, ``None`` 308 will be returned as the expected size. *cmd* and *rest* means the same thing as 309 in :meth:`transfercmd`. 310 311 312.. method:: FTP.nlst(argument[, ...]) 313 314 Return a list of file names as returned by the ``NLST`` command. The 315 optional *argument* is a directory to list (default is the current server 316 directory). Multiple arguments can be used to pass non-standard options to 317 the ``NLST`` command. 318 319 320.. method:: FTP.dir(argument[, ...]) 321 322 Produce a directory listing as returned by the ``LIST`` command, printing it to 323 standard output. The optional *argument* is a directory to list (default is the 324 current server directory). Multiple arguments can be used to pass non-standard 325 options to the ``LIST`` command. If the last argument is a function, it is used 326 as a *callback* function as for :meth:`retrlines`; the default prints to 327 ``sys.stdout``. This method returns ``None``. 328 329 330.. method:: FTP.rename(fromname, toname) 331 332 Rename file *fromname* on the server to *toname*. 333 334 335.. method:: FTP.delete(filename) 336 337 Remove the file named *filename* from the server. If successful, returns the 338 text of the response, otherwise raises :exc:`error_perm` on permission errors or 339 :exc:`error_reply` on other errors. 340 341 342.. method:: FTP.cwd(pathname) 343 344 Set the current directory on the server. 345 346 347.. method:: FTP.mkd(pathname) 348 349 Create a new directory on the server. 350 351 352.. method:: FTP.pwd() 353 354 Return the pathname of the current directory on the server. 355 356 357.. method:: FTP.rmd(dirname) 358 359 Remove the directory named *dirname* on the server. 360 361 362.. method:: FTP.size(filename) 363 364 Request the size of the file named *filename* on the server. On success, the 365 size of the file is returned as an integer, otherwise ``None`` is returned. 366 Note that the ``SIZE`` command is not standardized, but is supported by many 367 common server implementations. 368 369 370.. method:: FTP.quit() 371 372 Send a ``QUIT`` command to the server and close the connection. This is the 373 "polite" way to close a connection, but it may raise an exception if the server 374 responds with an error to the ``QUIT`` command. This implies a call to the 375 :meth:`close` method which renders the :class:`FTP` instance useless for 376 subsequent calls (see below). 377 378 379.. method:: FTP.close() 380 381 Close the connection unilaterally. This should not be applied to an already 382 closed connection such as after a successful call to :meth:`~FTP.quit`. 383 After this call the :class:`FTP` instance should not be used any more (after 384 a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the 385 connection by issuing another :meth:`login` method). 386 387 388FTP_TLS Objects 389--------------- 390 391:class:`FTP_TLS` class inherits from :class:`FTP`, defining these additional objects: 392 393.. attribute:: FTP_TLS.ssl_version 394 395 The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`). 396 397.. method:: FTP_TLS.auth() 398 399 Set up secure control connection by using TLS or SSL, depending on what 400 specified in :meth:`ssl_version` attribute. 401 402.. method:: FTP_TLS.prot_p() 403 404 Set up secure data connection. 405 406.. method:: FTP_TLS.prot_c() 407 408 Set up clear text data connection. 409