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.  The *acct* parameter supplies
 151    "accounting information"; few systems implement this.
 152
 153
 154 .. method:: FTP.abort()
 155
 156    Abort a file transfer that is in progress.  Using this does not always work, but
 157    it's worth a try.
 158
 159
 160 .. method:: FTP.sendcmd(command)
 161
 162    Send a simple command string to the server and return the response string.
 163
 164
 165 .. method:: FTP.voidcmd(command)
 166
 167    Send a simple command string to the server and handle the response. Return
 168    nothing if a response code in the range 200--299 is received. Raise an exception
 169    otherwise.
 170
 171
 172 .. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
 173
 174    Retrieve a file in binary transfer mode.  *command* should be an appropriate
 175    ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
 176    each block of data received, with a single string argument giving the data
 177    block. The optional *maxblocksize* argument specifies the maximum chunk size to
 178    read on the low-level socket object created to do the actual transfer (which
 179    will also be the largest size of the data blocks passed to *callback*).  A
 180    reasonable default is chosen. *rest* means the same thing as in the
 181    :meth:`transfercmd` method.
 182
 183
 184 .. method:: FTP.retrlines(command[, callback])
 185
 186    Retrieve a file or directory listing in ASCII transfer mode.  *command*
 187    should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
 188    command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
 189    ``'LIST'``).  The *callback* function is called for each line, with the
 190    trailing CRLF stripped.  The default *callback* prints the line to
 191    ``sys.stdout``.
 192
 193
 194 .. method:: FTP.set_pasv(boolean)
 195
 196    Enable "passive" mode if *boolean* is true, other disable passive mode.  (In
 197    Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
 198    it is on by default.)
 199
 200
 201 .. method:: FTP.storbinary(command, file[, blocksize, callback])
 202
 203    Store a file in binary transfer mode.  *command* should be an appropriate
 204    ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
 205    read until EOF using its :meth:`read` method in blocks of size *blocksize* to
 206    provide the data to be stored.  The *blocksize* argument defaults to 8192.
 207    *callback* is an optional single parameter callable that is called
 208    on each block of data after it is sent.
 209
 210    .. versionchanged:: 2.1
 211       default for *blocksize* added.
 212
 213    .. versionchanged:: 2.6
 214       *callback* parameter added.
 215
 216
 217 .. method:: FTP.storlines(command, file[, callback])
 218
 219    Store a file in ASCII transfer mode.  *command* should be an appropriate
 220    ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
 221    open file object *file* using its :meth:`readline` method to provide the data to
 222    be stored.  *callback* is an optional single parameter callable
 223    that is called on each line after it is sent.
 224
 225    .. versionchanged:: 2.6
 226       *callback* parameter added.
 227
 228
 229 .. method:: FTP.transfercmd(cmd[, rest])
 230
 231    Initiate a transfer over the data connection.  If the transfer is active, send a
 232    ``EPRT`` or  ``PORT`` command and the transfer command specified by *cmd*, and
 233    accept the connection.  If the server is passive, send a ``EPSV`` or ``PASV``
 234    command, connect to it, and start the transfer command.  Either way, return the
 235    socket for the connection.
 236
 237    If optional *rest* is given, a ``REST`` command is sent to the server, passing
 238    *rest* as an argument.  *rest* is usually a byte offset into the requested file,
 239    telling the server to restart sending the file's bytes at the requested offset,
 240    skipping over the initial bytes.  Note however that RFC 959 requires only that
 241    *rest* be a string containing characters in the printable range from ASCII code
 242    33 to ASCII code 126.  The :meth:`transfercmd` method, therefore, converts
 243    *rest* to a string, but no check is performed on the string's contents.  If the
 244    server does not recognize the ``REST`` command, an :exc:`error_reply` exception
 245    will be raised.  If this happens, simply call :meth:`transfercmd` without a
 246    *rest* argument.
 247
 248
 249 .. method:: FTP.ntransfercmd(cmd[, rest])
 250
 251    Like :meth:`transfercmd`, but returns a tuple of the data connection and the
 252    expected size of the data.  If the expected size could not be computed, ``None``
 253    will be returned as the expected size.  *cmd* and *rest* means the same thing as
 254    in :meth:`transfercmd`.
 255
 256
 257 .. method:: FTP.nlst(argument[, ...])
 258
 259    Return a list of files as returned by the ``NLST`` command.  The optional
 260    *argument* is a directory to list (default is the current server directory).
 261    Multiple arguments can be used to pass non-standard options to the ``NLST``
 262    command.
 263
 264
 265 .. method:: FTP.dir(argument[, ...])
 266
 267    Produce a directory listing as returned by the ``LIST`` command, printing it to
 268    standard output.  The optional *argument* is a directory to list (default is the
 269    current server directory).  Multiple arguments can be used to pass non-standard
 270    options to the ``LIST`` command.  If the last argument is a function, it is used
 271    as a *callback* function as for :meth:`retrlines`; the default prints to
 272    ``sys.stdout``.  This method returns ``None``.
 273
 274
 275 .. method:: FTP.rename(fromname, toname)
 276
 277    Rename file *fromname* on the server to *toname*.
 278
 279
 280 .. method:: FTP.delete(filename)
 281
 282    Remove the file named *filename* from the server.  If successful, returns the
 283    text of the response, otherwise raises :exc:`error_perm` on permission errors or
 284    :exc:`error_reply` on other errors.
 285
 286
 287 .. method:: FTP.cwd(pathname)
 288
 289    Set the current directory on the server.
 290
 291
 292 .. method:: FTP.mkd(pathname)
 293
 294    Create a new directory on the server.
 295
 296
 297 .. method:: FTP.pwd()
 298
 299    Return the pathname of the current directory on the server.
 300
 301
 302 .. method:: FTP.rmd(dirname)
 303
 304    Remove the directory named *dirname* on the server.
 305
 306
 307 .. method:: FTP.size(filename)
 308
 309    Request the size of the file named *filename* on the server.  On success, the
 310    size of the file is returned as an integer, otherwise ``None`` is returned.
 311    Note that the ``SIZE`` command is not  standardized, but is supported by many
 312    common server implementations.
 313
 314
 315 .. method:: FTP.quit()
 316
 317    Send a ``QUIT`` command to the server and close the connection. This is the
 318    "polite" way to close a connection, but it may raise an exception if the server
 319    responds with an error to the ``QUIT`` command.  This implies a call to the
 320    :meth:`close` method which renders the :class:`FTP` instance useless for
 321    subsequent calls (see below).
 322
 323
 324 .. method:: FTP.close()
 325
 326    Close the connection unilaterally.  This should not be applied to an already
 327    closed connection such as after a successful call to :meth:`quit`.  After this
 328    call the :class:`FTP` instance should not be used any more (after a call to
 329    :meth:`close` or :meth:`quit` you cannot reopen the connection by issuing
 330    another :meth:`login` method).
 331