1
:mod:`ftplib` --- FTP protocol client
2
=====================================
5
:synopsis: FTP protocol client (requires sockets).
10
single: FTP; ftplib (standard module)
12
**Source code:** :source:`Lib/ftplib.py`
16
This module defines the class :class:`FTP` and a few related items. The
17
:class:`FTP` class implements the client side of the FTP protocol. You can use
18
this to write Python programs that perform a variety of automated FTP jobs, such
19
as mirroring other FTP servers. It is also used by the module :mod:`urllib` to
20
handle URLs that use FTP. For more information on FTP (File Transfer Protocol),
21
see Internet :rfc:`959`.
23
Here's a sample session using the :mod:`ftplib` module::
25
>>> from ftplib import FTP
26
>>> ftp = FTP('ftp.debian.org') # connect to host, default port
27
>>> ftp.login() # user anonymous, passwd anonymous@
28
'230 Login successful.'
29
>>> ftp.cwd('debian') # change into "debian" directory
30
>>> ftp.retrlines('LIST') # list directory contents
31
-rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README
33
drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool
34
drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project
35
drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools
36
'226 Directory send OK.'
37
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
38
'226 Transfer complete.'
42
The module defines the following items:
44
.. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
46
Return a new instance of the :class:`FTP` class. When *host* is given, the
47
method call ``connect(host)`` is made. When *user* is given, additionally
48
the method call ``login(user, passwd, acct)`` is made (where *passwd* and
49
*acct* default to the empty string when not given). The optional *timeout*
50
parameter specifies a timeout in seconds for blocking operations like the
51
connection attempt (if is not specified, the global default timeout setting
54
.. versionchanged:: 2.6
58
.. class:: FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])
60
A :class:`FTP` subclass which adds TLS support to FTP as described in
62
Connect as usual to port 21 implicitly securing the FTP control connection
63
before authenticating. Securing the data connection requires the user to
64
explicitly ask for it by calling the :meth:`prot_p` method. *context*
65
is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
66
options, certificates and private keys into a single (potentially
67
long-lived) structure. Please read :ref:`ssl-security` for best practices.
69
*keyfile* and *certfile* are a legacy alternative to *context* -- they
70
can point to PEM-formatted private key and certificate chain files
71
(respectively) for the SSL connection.
75
.. versionchanged:: 2.7.10
76
The *context* parameter was added.
78
Here's a sample session using the :class:`FTP_TLS` class:
80
>>> from ftplib import FTP_TLS
81
>>> ftps = FTP_TLS('ftp.python.org')
82
>>> ftps.login() # login anonymously before securing control channel
83
>>> ftps.prot_p() # switch to secure data connection
84
>>> ftps.retrlines('LIST') # list directory content securely
86
drwxr-xr-x 8 root wheel 1024 Jan 3 1994 .
87
drwxr-xr-x 8 root wheel 1024 Jan 3 1994 ..
88
drwxr-xr-x 2 root wheel 1024 Jan 3 1994 bin
89
drwxr-xr-x 2 root wheel 1024 Jan 3 1994 etc
90
d-wxrwxr-x 2 ftp wheel 1024 Sep 5 13:43 incoming
91
drwxr-xr-x 2 root wheel 1024 Nov 17 1993 lib
92
drwxr-xr-x 6 1094 wheel 1024 Sep 13 19:07 pub
93
drwxr-xr-x 3 root wheel 1024 Jan 3 1994 usr
94
-rw-r--r-- 1 root root 312 Aug 1 1994 welcome.msg
95
'226 Transfer complete.'
100
.. exception:: error_reply
102
Exception raised when an unexpected reply is received from the server.
105
.. exception:: error_temp
107
Exception raised when an error code signifying a temporary error (response
108
codes in the range 400--499) is received.
111
.. exception:: error_perm
113
Exception raised when an error code signifying a permanent error (response
114
codes in the range 500--599) is received.
117
.. exception:: error_proto
119
Exception raised when a reply is received from the server that does not fit
120
the response specifications of the File Transfer Protocol, i.e. begin with a
121
digit in the range 1--5.
126
The set of all exceptions (as a tuple) that methods of :class:`FTP`
127
instances may raise as a result of problems with the FTP connection (as
128
opposed to programming errors made by the caller). This set includes the
129
four exceptions listed above as well as :exc:`socket.error` and
136
Parser for the :file:`.netrc` file format. The file :file:`.netrc` is
137
typically used by FTP clients to load user authentication information
138
before prompting the user.
140
.. index:: single: ftpmirror.py
142
The file :file:`Tools/scripts/ftpmirror.py` in the Python source distribution is
143
a script that can mirror FTP sites, or portions thereof, using the :mod:`ftplib`
144
module. It can be used as an extended example that applies this module.
152
Several methods are available in two flavors: one for handling text files and
153
another for binary files. These are named for the command which is used
154
followed by ``lines`` for the text version or ``binary`` for the binary version.
156
:class:`FTP` instances have the following methods:
159
.. method:: FTP.set_debuglevel(level)
161
Set the instance's debugging level. This controls the amount of debugging
162
output printed. The default, ``0``, produces no debugging output. A value of
163
``1`` produces a moderate amount of debugging output, generally a single line
164
per request. A value of ``2`` or higher produces the maximum amount of
165
debugging output, logging each line sent and received on the control connection.
168
.. method:: FTP.connect(host[, port[, timeout]])
170
Connect to the given host and port. The default port number is ``21``, as
171
specified by the FTP protocol specification. It is rarely needed to specify a
172
different port number. This function should be called only once for each
173
instance; it should not be called at all if a host was given when the instance
174
was created. All other methods can only be used after a connection has been
177
The optional *timeout* parameter specifies a timeout in seconds for the
178
connection attempt. If no *timeout* is passed, the global default timeout
179
setting will be used.
181
.. versionchanged:: 2.6
185
.. method:: FTP.getwelcome()
187
Return the welcome message sent by the server in reply to the initial
188
connection. (This message sometimes contains disclaimers or help information
189
that may be relevant to the user.)
192
.. method:: FTP.login([user[, passwd[, acct]]])
194
Log in as the given *user*. The *passwd* and *acct* parameters are optional and
195
default to the empty string. If no *user* is specified, it defaults to
196
``'anonymous'``. If *user* is ``'anonymous'``, the default *passwd* is
197
``'anonymous@'``. This function should be called only once for each instance,
198
after a connection has been established; it should not be called at all if a
199
host and user were given when the instance was created. Most FTP commands are
200
only allowed after the client has logged in. The *acct* parameter supplies
201
"accounting information"; few systems implement this.
204
.. method:: FTP.abort()
206
Abort a file transfer that is in progress. Using this does not always work, but
210
.. method:: FTP.sendcmd(command)
212
Send a simple command string to the server and return the response string.
215
.. method:: FTP.voidcmd(command)
217
Send a simple command string to the server and handle the response. Return
218
nothing if a response code corresponding to success (codes in the range
219
200--299) is received. Raise :exc:`error_reply` otherwise.
222
.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
224
Retrieve a file in binary transfer mode. *command* should be an appropriate
225
``RETR`` command: ``'RETR filename'``. The *callback* function is called for
226
each block of data received, with a single string argument giving the data
227
block. The optional *maxblocksize* argument specifies the maximum chunk size to
228
read on the low-level socket object created to do the actual transfer (which
229
will also be the largest size of the data blocks passed to *callback*). A
230
reasonable default is chosen. *rest* means the same thing as in the
231
:meth:`transfercmd` method.
234
.. method:: FTP.retrlines(command[, callback])
236
Retrieve a file or directory listing in ASCII transfer mode. *command*
237
should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
238
command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
239
``'LIST'``). ``LIST`` retrieves a list of files and information about those files.
240
``NLST`` retrieves a list of file names. On some servers, ``MLSD`` retrieves
241
a machine readable list of files and information about those files. The *callback*
242
function is called for each line with a string argument containing the line with
243
the trailing CRLF stripped. The default *callback* prints the line to ``sys.stdout``.
246
.. method:: FTP.set_pasv(boolean)
248
Enable "passive" mode if *boolean* is true, other disable passive mode. (In
249
Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
250
it is on by default.)
253
.. method:: FTP.storbinary(command, file[, blocksize, callback, rest])
255
Store a file in binary transfer mode. *command* should be an appropriate
256
``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
257
read until EOF using its :meth:`read` method in blocks of size *blocksize* to
258
provide the data to be stored. The *blocksize* argument defaults to 8192.
259
*callback* is an optional single parameter callable that is called
260
on each block of data after it is sent. *rest* means the same thing as in
261
the :meth:`transfercmd` method.
263
.. versionchanged:: 2.1
264
default for *blocksize* added.
266
.. versionchanged:: 2.6
267
*callback* parameter added.
269
.. versionchanged:: 2.7
270
*rest* parameter added.
272
.. method:: FTP.storlines(command, file[, callback])
274
Store a file in ASCII transfer mode. *command* should be an appropriate
275
``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
276
open file object *file* using its :meth:`~file.readline` method to provide
277
the data to be stored. *callback* is an optional single parameter callable
278
that is called on each line after it is sent.
280
.. versionchanged:: 2.6
281
*callback* parameter added.
284
.. method:: FTP.transfercmd(cmd[, rest])
286
Initiate a transfer over the data connection. If the transfer is active, send an
287
``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*, and
288
accept the connection. If the server is passive, send an ``EPSV`` or ``PASV``
289
command, connect to it, and start the transfer command. Either way, return the
290
socket for the connection.
292
If optional *rest* is given, a ``REST`` command is sent to the server, passing
293
*rest* as an argument. *rest* is usually a byte offset into the requested file,
294
telling the server to restart sending the file's bytes at the requested offset,
295
skipping over the initial bytes. Note however that RFC 959 requires only that
296
*rest* be a string containing characters in the printable range from ASCII code
297
33 to ASCII code 126. The :meth:`transfercmd` method, therefore, converts
298
*rest* to a string, but no check is performed on the string's contents. If the
299
server does not recognize the ``REST`` command, an :exc:`error_reply` exception
300
will be raised. If this happens, simply call :meth:`transfercmd` without a
304
.. method:: FTP.ntransfercmd(cmd[, rest])
306
Like :meth:`transfercmd`, but returns a tuple of the data connection and the
307
expected size of the data. If the expected size could not be computed, ``None``
308
will be returned as the expected size. *cmd* and *rest* means the same thing as
309
in :meth:`transfercmd`.
312
.. method:: FTP.nlst(argument[, ...])
314
Return a list of file names as returned by the ``NLST`` command. The
315
optional *argument* is a directory to list (default is the current server
316
directory). Multiple arguments can be used to pass non-standard options to
317
the ``NLST`` command.
320
.. method:: FTP.dir(argument[, ...])
322
Produce a directory listing as returned by the ``LIST`` command, printing it to
323
standard output. The optional *argument* is a directory to list (default is the
324
current server directory). Multiple arguments can be used to pass non-standard
325
options to the ``LIST`` command. If the last argument is a function, it is used
326
as a *callback* function as for :meth:`retrlines`; the default prints to
327
``sys.stdout``. This method returns ``None``.
330
.. method:: FTP.rename(fromname, toname)
332
Rename file *fromname* on the server to *toname*.
335
.. method:: FTP.delete(filename)
337
Remove the file named *filename* from the server. If successful, returns the
338
text of the response, otherwise raises :exc:`error_perm` on permission errors or
339
:exc:`error_reply` on other errors.
342
.. method:: FTP.cwd(pathname)
344
Set the current directory on the server.
347
.. method:: FTP.mkd(pathname)
349
Create a new directory on the server.
352
.. method:: FTP.pwd()
354
Return the pathname of the current directory on the server.
357
.. method:: FTP.rmd(dirname)
359
Remove the directory named *dirname* on the server.
362
.. method:: FTP.size(filename)
364
Request the size of the file named *filename* on the server. On success, the
365
size of the file is returned as an integer, otherwise ``None`` is returned.
366
Note that the ``SIZE`` command is not standardized, but is supported by many
367
common server implementations.
370
.. method:: FTP.quit()
372
Send a ``QUIT`` command to the server and close the connection. This is the
373
"polite" way to close a connection, but it may raise an exception if the server
374
responds with an error to the ``QUIT`` command. This implies a call to the
375
:meth:`close` method which renders the :class:`FTP` instance useless for
376
subsequent calls (see below).
379
.. method:: FTP.close()
381
Close the connection unilaterally. This should not be applied to an already
382
closed connection such as after a successful call to :meth:`~FTP.quit`.
383
After this call the :class:`FTP` instance should not be used any more (after
384
a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the
385
connection by issuing another :meth:`login` method).
391
:class:`FTP_TLS` class inherits from :class:`FTP`, defining these additional objects:
393
.. attribute:: FTP_TLS.ssl_version
395
The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`).
397
.. method:: FTP_TLS.auth()
399
Set up secure control connection by using TLS or SSL, depending on what
400
specified in :meth:`ssl_version` attribute.
402
.. method:: FTP_TLS.prot_p()
404
Set up secure data connection.
406
.. method:: FTP_TLS.prot_c()
408
Set up clear text data connection.
added
removed
python-2.7.12-docs-html/_sources/library/ftplib.txt
