/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
 12This 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
 14this to write Python programs that perform a variety of automated FTP jobs, such
 15as mirroring other ftp servers.  It is also used by the module :mod:`urllib` to
 16handle URLs that use FTP.  For more information on FTP (File Transfer Protocol),
 17see Internet :rfc:`959`.
 18
 19Here'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
 36The 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
 99FTP Objects
100-----------
101
102Several methods are available in two flavors: one for handling text files and
103another for binary files.  These are named for the command which is used
104followed 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