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