Doc/library/ftplib.rst

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