1 :mod:`ftplib` --- FTP protocol client
2 =====================================
5 :synopsis: FTP protocol client (requires sockets).
10 single: FTP; ftplib (standard module)
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`.
19 Here's a sample session using the :mod:`ftplib` module::
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
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
32 >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
33 '226 Transfer complete.'
36 The module defines the following items:
39 .. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
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
49 .. versionchanged:: 2.6
53 .. attribute:: all_errors
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
62 .. exception:: error_reply
64 Exception raised when an unexpected reply is received from the server.
67 .. exception:: error_temp
69 Exception raised when an error code in the range 400--499 is received.
72 .. exception:: error_perm
74 Exception raised when an error code in the range 500--599 is received.
77 .. exception:: error_proto
79 Exception raised when a reply is received from the server that does not
80 begin with a digit in the range 1--5.
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
90 .. index:: single: ftpmirror.py
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.
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.
106 :class:`FTP` instances have the following methods:
109 .. method:: FTP.set_debuglevel(level)
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.
118 .. method:: FTP.connect(host[, port[, timeout]])
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
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.
131 .. versionchanged:: 2.6
135 .. method:: FTP.getwelcome()
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.)
142 .. method:: FTP.login([user[, passwd[, acct]]])
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.
154 .. method:: FTP.abort()
156 Abort a file transfer that is in progress. Using this does not always work, but
160 .. method:: FTP.sendcmd(command)
162 Send a simple command string to the server and return the response string.
165 .. method:: FTP.voidcmd(command)
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
172 .. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
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.
184 .. method:: FTP.retrlines(command[, callback])
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
194 .. method:: FTP.set_pasv(boolean)
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.)
201 .. method:: FTP.storbinary(command, file[, blocksize, callback])
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.
210 .. versionchanged:: 2.1
211 default for *blocksize* added.
213 .. versionchanged:: 2.6
214 *callback* parameter added.
217 .. method:: FTP.storlines(command, file[, callback])
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.
225 .. versionchanged:: 2.6
226 *callback* parameter added.
229 .. method:: FTP.transfercmd(cmd[, rest])
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.
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
249 .. method:: FTP.ntransfercmd(cmd[, rest])
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`.
257 .. method:: FTP.nlst(argument[, ...])
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``
265 .. method:: FTP.dir(argument[, ...])
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``.
275 .. method:: FTP.rename(fromname, toname)
277 Rename file *fromname* on the server to *toname*.
280 .. method:: FTP.delete(filename)
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.
287 .. method:: FTP.cwd(pathname)
289 Set the current directory on the server.
292 .. method:: FTP.mkd(pathname)
294 Create a new directory on the server.
297 .. method:: FTP.pwd()
299 Return the pathname of the current directory on the server.
302 .. method:: FTP.rmd(dirname)
304 Remove the directory named *dirname* on the server.
307 .. method:: FTP.size(filename)
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.
315 .. method:: FTP.quit()
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).
324 .. method:: FTP.close()
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).