Doc/library/ftplib.rst

   1
   2 :mod:`ftplib` --- FTP protocol client
   3 =====================================
   4
   5 .. module:: ftplib
   6    :synopsis: FTP protocol client (requires sockets).
   7
   8
   9 .. index::
  10    pair: FTP; protocol
  11    single: FTP; ftplib (standard module)
  12
  13 This module defines the class :class:`FTP` and a few related items. The
  14 :class:`FTP` class implements the client side of the FTP protocol.  You can use
  15 this to write Python programs that perform a variety of automated FTP jobs, such
  16 as mirroring other ftp servers.  It is also used by the module :mod:`urllib` to
  17 handle URLs that use FTP.  For more information on FTP (File Transfer Protocol),
  18 see Internet :rfc:`959`.
  19
  20 Here's a sample session using the :mod:`ftplib` module::
  21
  22    >>> from ftplib import FTP
  23    >>> ftp = FTP('ftp.cwi.nl')   # connect to host, default port
  24    >>> ftp.login()               # user anonymous, passwd anonymous@
  25    >>> ftp.retrlines('LIST')     # list directory contents
  26    total 24418
  27    drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
  28    dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
  29    -rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
  30     .
  31     .
  32     .
  33    >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
  34    '226 Transfer complete.'
  35    >>> ftp.quit()
  36
  37 The module defines the following items:
  38
  39
  40 .. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
  41
  42    Return a new instance of the :class:`FTP` class.  When *host* is given, the
  43    method call ``connect(host)`` is made.  When *user* is given, additionally
  44    the method call ``login(user, passwd, acct)`` is made (where *passwd* and
  45    *acct* default to the empty string when not given).  The optional *timeout*
  46    parameter specifies a timeout in seconds for blocking operations like the
  47    connection attempt (if is not specified, or passed as None, the global
  48    default timeout setting will be used).
  49
  50    .. versionchanged:: 2.6
  51       *timeout* was added.
  52
  53
  54    .. attribute:: all_errors
  55
  56       The set of all exceptions (as a tuple) that methods of :class:`FTP`
  57       instances may raise as a result of problems with the FTP connection (as
  58       opposed to programming errors made by the caller).  This set includes the
  59       four exceptions listed below as well as :exc:`socket.error` and
  60       :exc:`IOError`.
  61
  62
  63    .. exception:: error_reply
  64
  65       Exception raised when an unexpected reply is received from the server.
  66
  67
  68    .. exception:: error_temp
  69
  70       Exception raised when an error code in the range 400--499 is received.
  71
  72
  73    .. exception:: error_perm
  74
  75       Exception raised when an error code in the range 500--599 is received.
  76
  77
  78    .. exception:: error_proto
  79
  80       Exception raised when a reply is received from the server that does not
  81       begin with a digit in the range 1--5.
  82
  83
  84 .. seealso::
  85
  86    Module :mod:`netrc`
  87       Parser for the :file:`.netrc` file format.  The file :file:`.netrc` is typically
  88       used by FTP clients to load user authentication information before prompting the
  89       user.
  90
  91    .. index:: single: ftpmirror.py
  92
  93    The file :file:`Tools/scripts/ftpmirror.py` in the Python source distribution is
  94    a script that can mirror FTP sites, or portions thereof, using the :mod:`ftplib`
  95    module. It can be used as an extended example that applies this module.
  96
  97
  98 .. _ftp-objects:
  99
 100 FTP Objects
 101 -----------
 102
 103 Several methods are available in two flavors: one for handling text files and
 104 another for binary files.  These are named for the command which is used
 105 followed by ``lines`` for the text version or ``binary`` for the binary version.
 106
 107 :class:`FTP` instances have the following methods:
 108
 109
 110 .. method:: FTP.set_debuglevel(level)
 111
 112    Set the instance's debugging level.  This controls the amount of debugging
 113    output printed.  The default, ``0``, produces no debugging output.  A value of
 114    ``1`` produces a moderate amount of debugging output, generally a single line
 115    per request.  A value of ``2`` or higher produces the maximum amount of
 116    debugging output, logging each line sent and received on the control connection.
 117
 118
 119 .. method:: FTP.connect(host[, port[, timeout]])
 120
 121    Connect to the given host and port.  The default port number is ``21``, as
 122    specified by the FTP protocol specification.  It is rarely needed to specify a
 123    different port number.  This function should be called only once for each
 124    instance; it should not be called at all if a host was given when the instance
 125    was created.  All other methods can only be used after a connection has been
 126    made.
 127
 128    The optional *timeout* parameter specifies a timeout in seconds for the
 129    connection attempt. If is not specified, or passed as None, the object
 130    timeout is used (the timeout that you passed when instantiating the class);
 131    if the object timeout is also None, the global default timeout setting will
 132    be used.
 133
 134    .. versionchanged:: 2.6
 135       *timeout* was added.
 136
 137
 138 .. method:: FTP.getwelcome()
 139
 140    Return the welcome message sent by the server in reply to the initial
 141    connection.  (This message sometimes contains disclaimers or help information
 142    that may be relevant to the user.)
 143
 144
 145 .. method:: FTP.login([user[, passwd[, acct]]])
 146
 147    Log in as the given *user*.  The *passwd* and *acct* parameters are optional and
 148    default to the empty string.  If no *user* is specified, it defaults to
 149    ``'anonymous'``.  If *user* is ``'anonymous'``, the default *passwd* is
 150    ``'anonymous@'``.  This function should be called only once for each instance,
 151    after a connection has been established; it should not be called at all if a
 152    host and user were given when the instance was created.  Most FTP commands are
 153    only allowed after the client has logged in.
 154
 155
 156 .. method:: FTP.abort()
 157
 158    Abort a file transfer that is in progress.  Using this does not always work, but
 159    it's worth a try.
 160
 161
 162 .. method:: FTP.sendcmd(command)
 163
 164    Send a simple command string to the server and return the response string.
 165
 166
 167 .. method:: FTP.voidcmd(command)
 168
 169    Send a simple command string to the server and handle the response. Return
 170    nothing if a response code in the range 200--299 is received. Raise an exception
 171    otherwise.
 172
 173
 174 .. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
 175
 176    Retrieve a file in binary transfer mode.  *command* should be an appropriate
 177    ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
 178    each block of data received, with a single string argument giving the data
 179    block. The optional *maxblocksize* argument specifies the maximum chunk size to
 180    read on the low-level socket object created to do the actual transfer (which
 181    will also be the largest size of the data blocks passed to *callback*).  A
 182    reasonable default is chosen. *rest* means the same thing as in the
 183    :meth:`transfercmd` method.
 184
 185
 186 .. method:: FTP.retrlines(command[, callback])
 187
 188    Retrieve a file or directory listing in ASCII transfer mode.  *command*
 189    should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
 190    command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
 191    ``'LIST'``).  The *callback* function is called for each line, with the
 192    trailing CRLF stripped.  The default *callback* prints the line to
 193    ``sys.stdout``.
 194
 195
 196 .. method:: FTP.set_pasv(boolean)
 197
 198    Enable "passive" mode if *boolean* is true, other disable passive mode.  (In
 199    Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
 200    it is on by default.)
 201
 202
 203 .. method:: FTP.storbinary(command, file[, blocksize, callback])
 204
 205    Store a file in binary transfer mode.  *command* should be an appropriate
 206    ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
 207    read until EOF using its :meth:`read` method in blocks of size *blocksize* to
 208    provide the data to be stored.  The *blocksize* argument defaults to 8192.
 209    *callback* is an optional single parameter callable that is called
 210    on each block of data after it is sent.
 211
 212    .. versionchanged:: 2.1
 213       default for *blocksize* added.
 214
 215    .. versionchanged:: 2.6
 216       *callback* parameter added.
 217
 218
 219 .. method:: FTP.storlines(command, file[, callback])
 220
 221    Store a file in ASCII transfer mode.  *command* should be an appropriate
 222    ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
 223    open file object *file* using its :meth:`readline` method to provide the data to
 224    be stored.  *callback* is an optional single parameter callable
 225    that is called on each line after it is sent.
 226
 227    .. versionchanged:: 2.6
 228       *callback* parameter added.
 229
 230
 231 .. method:: FTP.transfercmd(cmd[, rest])
 232
 233    Initiate a transfer over the data connection.  If the transfer is active, send a
 234    ``EPRT`` or  ``PORT`` command and the transfer command specified by *cmd*, and
 235    accept the connection.  If the server is passive, send a ``EPSV`` or ``PASV``
 236    command, connect to it, and start the transfer command.  Either way, return the
 237    socket for the connection.
 238
 239    If optional *rest* is given, a ``REST`` command is sent to the server, passing
 240    *rest* as an argument.  *rest* is usually a byte offset into the requested file,
 241    telling the server to restart sending the file's bytes at the requested offset,
 242    skipping over the initial bytes.  Note however that RFC 959 requires only that
 243    *rest* be a string containing characters in the printable range from ASCII code
 244    33 to ASCII code 126.  The :meth:`transfercmd` method, therefore, converts
 245    *rest* to a string, but no check is performed on the string's contents.  If the
 246    server does not recognize the ``REST`` command, an :exc:`error_reply` exception
 247    will be raised.  If this happens, simply call :meth:`transfercmd` without a
 248    *rest* argument.
 249
 250
 251 .. method:: FTP.ntransfercmd(cmd[, rest])
 252
 253    Like :meth:`transfercmd`, but returns a tuple of the data connection and the
 254    expected size of the data.  If the expected size could not be computed, ``None``
 255    will be returned as the expected size.  *cmd* and *rest* means the same thing as
 256    in :meth:`transfercmd`.
 257
 258
 259 .. method:: FTP.nlst(argument[, ...])
 260
 261    Return a list of files as returned by the ``NLST`` command.  The optional
 262    *argument* is a directory to list (default is the current server directory).
 263    Multiple arguments can be used to pass non-standard options to the ``NLST``
 264    command.
 265
 266
 267 .. method:: FTP.dir(argument[, ...])
 268
 269    Produce a directory listing as returned by the ``LIST`` command, printing it to
 270    standard output.  The optional *argument* is a directory to list (default is the
 271    current server directory).  Multiple arguments can be used to pass non-standard
 272    options to the ``LIST`` command.  If the last argument is a function, it is used
 273    as a *callback* function as for :meth:`retrlines`; the default prints to
 274    ``sys.stdout``.  This method returns ``None``.
 275
 276
 277 .. method:: FTP.rename(fromname, toname)
 278
 279    Rename file *fromname* on the server to *toname*.
 280
 281
 282 .. method:: FTP.delete(filename)
 283
 284    Remove the file named *filename* from the server.  If successful, returns the
 285    text of the response, otherwise raises :exc:`error_perm` on permission errors or
 286    :exc:`error_reply` on other errors.
 287
 288
 289 .. method:: FTP.cwd(pathname)
 290
 291    Set the current directory on the server.
 292
 293
 294 .. method:: FTP.mkd(pathname)
 295
 296    Create a new directory on the server.
 297
 298
 299 .. method:: FTP.pwd()
 300
 301    Return the pathname of the current directory on the server.
 302
 303
 304 .. method:: FTP.rmd(dirname)
 305
 306    Remove the directory named *dirname* on the server.
 307
 308
 309 .. method:: FTP.size(filename)
 310
 311    Request the size of the file named *filename* on the server.  On success, the
 312    size of the file is returned as an integer, otherwise ``None`` is returned.
 313    Note that the ``SIZE`` command is not  standardized, but is supported by many
 314    common server implementations.
 315
 316
 317 .. method:: FTP.quit()
 318
 319    Send a ``QUIT`` command to the server and close the connection. This is the
 320    "polite" way to close a connection, but it may raise an exception of the server
 321    reponds with an error to the ``QUIT`` command.  This implies a call to the
 322    :meth:`close` method which renders the :class:`FTP` instance useless for
 323    subsequent calls (see below).
 324
 325
 326 .. method:: FTP.close()
 327
 328    Close the connection unilaterally.  This should not be applied to an already
 329    closed connection such as after a successful call to :meth:`quit`.  After this
 330    call the :class:`FTP` instance should not be used any more (after a call to
 331    :meth:`close` or :meth:`quit` you cannot reopen the connection by issuing
 332    another :meth:`login` method).
 333