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, the global default timeout setting

    48    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 no *timeout* is passed, the global default timeout

   130    setting will be used.

   131 

   132    .. versionchanged:: 2.6

   133       *timeout* was added.

   134 

   135 

   136 .. method:: FTP.getwelcome()

   137 

   138    Return the welcome message sent by the server in reply to the initial

   139    connection.  (This message sometimes contains disclaimers or help information

   140    that may be relevant to the user.)

   141 

   142 

   143 .. method:: FTP.login([user[, passwd[, acct]]])

   144 

   145    Log in as the given *user*.  The *passwd* and *acct* parameters are optional and

   146    default to the empty string.  If no *user* is specified, it defaults to

   147    ``'anonymous'``.  If *user* is ``'anonymous'``, the default *passwd* is

   148    ``'anonymous@'``.  This function should be called only once for each instance,

   149    after a connection has been established; it should not be called at all if a

   150    host and user were given when the instance was created.  Most FTP commands are

   151    only allowed after the client has logged in.

   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