rest25/library/ftplib.rst => rest262/library/ftplib.rst
n1- 
2:mod:`ftplib` --- FTP protocol client
3=====================================
4
5.. module:: ftplib
6   :synopsis: FTP protocol client (requires sockets).
7
8
9.. index::
32    .
33   >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
34   '226 Transfer complete.'
35   >>> ftp.quit()
36
37The module defines the following items:
38
39
n40-.. class:: FTP([host[, user[, passwd[, acct]]]])
n39+.. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
41
42   Return a new instance of the :class:`FTP` class.  When *host* is given, the
n43-   method call ``connect(host)`` is made.  When *user* is given, additionally the
n42+   method call ``connect(host)`` is made.  When *user* is given, additionally
44-   method call ``login(user, passwd, acct)`` is made (where *passwd* and *acct*
43+   the method call ``login(user, passwd, acct)`` is made (where *passwd* and
45-   default to the empty string when not given).
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).
46
n49+   .. versionchanged:: 2.6
50+      *timeout* was added.
47
n52+ 
48-.. data:: all_errors
53+   .. attribute:: all_errors
49
n50-   The set of all exceptions (as a tuple) that methods of :class:`FTP` instances
n55+      The set of all exceptions (as a tuple) that methods of :class:`FTP`
51-   may raise as a result of problems with the FTP connection (as opposed to
56+      instances may raise as a result of problems with the FTP connection (as
52-   programming errors made by the caller).  This set includes the four exceptions
57+      opposed to programming errors made by the caller).  This set includes the
53-   listed below as well as :exc:`socket.error` and :exc:`IOError`.
58+      four exceptions listed below as well as :exc:`socket.error` and
59+      :exc:`IOError`.
54
55
n56-.. exception:: error_reply
n62+   .. exception:: error_reply
57
n58-   Exception raised when an unexpected reply is received from the server.
n64+      Exception raised when an unexpected reply is received from the server.
59
60
n61-.. exception:: error_temp
n67+   .. exception:: error_temp
62
n63-   Exception raised when an error code in the range 400--499 is received.
n69+      Exception raised when an error code in the range 400--499 is received.
64
65
n66-.. exception:: error_perm
n72+   .. exception:: error_perm
67
n68-   Exception raised when an error code in the range 500--599 is received.
n74+      Exception raised when an error code in the range 500--599 is received.
69
70
n71-.. exception:: error_proto
n77+   .. exception:: error_proto
72
n73-   Exception raised when a reply is received from the server that does not begin
n79+      Exception raised when a reply is received from the server that does not
74-   with a digit in the range 1--5.
80+      begin with a digit in the range 1--5.
75
76
77.. seealso::
78
79   Module :mod:`netrc`
80      Parser for the :file:`.netrc` file format.  The file :file:`.netrc` is typically
81      used by FTP clients to load user authentication information before prompting the
82      user.
95
96Several methods are available in two flavors: one for handling text files and
97another for binary files.  These are named for the command which is used
98followed by ``lines`` for the text version or ``binary`` for the binary version.
99
100:class:`FTP` instances have the following methods:
101
102
n103-.. method:: XXX Class.set_debuglevel(level)
n109+.. method:: FTP.set_debuglevel(level)
104
105   Set the instance's debugging level.  This controls the amount of debugging
106   output printed.  The default, ``0``, produces no debugging output.  A value of
107   ``1`` produces a moderate amount of debugging output, generally a single line
108   per request.  A value of ``2`` or higher produces the maximum amount of
109   debugging output, logging each line sent and received on the control connection.
110
111
n112-.. method:: XXX Class.connect(host[, port])
n118+.. method:: FTP.connect(host[, port[, timeout]])
113
114   Connect to the given host and port.  The default port number is ``21``, as
115   specified by the FTP protocol specification.  It is rarely needed to specify a
116   different port number.  This function should be called only once for each
117   instance; it should not be called at all if a host was given when the instance
118   was created.  All other methods can only be used after a connection has been
119   made.
120
n127+   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.
121
n131+   .. versionchanged:: 2.6
132+      *timeout* was added.
133+ 
134+ 
122-.. method:: XXX Class.getwelcome()
135+.. method:: FTP.getwelcome()
123
124   Return the welcome message sent by the server in reply to the initial
125   connection.  (This message sometimes contains disclaimers or help information
126   that may be relevant to the user.)
127
128
n129-.. method:: XXX Class.login([user[, passwd[, acct]]])
n142+.. method:: FTP.login([user[, passwd[, acct]]])
130
131   Log in as the given *user*.  The *passwd* and *acct* parameters are optional and
132   default to the empty string.  If no *user* is specified, it defaults to
133   ``'anonymous'``.  If *user* is ``'anonymous'``, the default *passwd* is
134   ``'anonymous@'``.  This function should be called only once for each instance,
135   after a connection has been established; it should not be called at all if a
136   host and user were given when the instance was created.  Most FTP commands are
137   only allowed after the client has logged in.
138
139
n140-.. method:: XXX Class.abort()
n153+.. method:: FTP.abort()
141
142   Abort a file transfer that is in progress.  Using this does not always work, but
143   it's worth a try.
144
145
n146-.. method:: XXX Class.sendcmd(command)
n159+.. method:: FTP.sendcmd(command)
147
148   Send a simple command string to the server and return the response string.
149
150
n151-.. method:: XXX Class.voidcmd(command)
n164+.. method:: FTP.voidcmd(command)
152
153   Send a simple command string to the server and handle the response. Return
154   nothing if a response code in the range 200--299 is received. Raise an exception
155   otherwise.
156
157
n158-.. method:: XXX Class.retrbinary(command, callback[, maxblocksize[, rest]])
n171+.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
159
160   Retrieve a file in binary transfer mode.  *command* should be an appropriate
161   ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
162   each block of data received, with a single string argument giving the data
163   block. The optional *maxblocksize* argument specifies the maximum chunk size to
164   read on the low-level socket object created to do the actual transfer (which
165   will also be the largest size of the data blocks passed to *callback*).  A
166   reasonable default is chosen. *rest* means the same thing as in the
167   :meth:`transfercmd` method.
168
169
n170-.. method:: XXX Class.retrlines(command[, callback])
n183+.. method:: FTP.retrlines(command[, callback])
171
n172-   Retrieve a file or directory listing in ASCII transfer mode. *command* should be
n185+   Retrieve a file or directory listing in ASCII transfer mode.  *command*
173-   an appropriate ``RETR`` command (see :meth:`retrbinary`) or a ``LIST`` command
186+   should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
174-   (usually just the string ``'LIST'``).  The *callback* function is called for
187+   command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
188+   ``'LIST'``).  The *callback* function is called for each line, with the
175-   each line, with the trailing CRLF stripped.  The default *callback* prints the
189+   trailing CRLF stripped.  The default *callback* prints the line to
176-   line to ``sys.stdout``.
190+   ``sys.stdout``.
177
178
n179-.. method:: XXX Class.set_pasv(boolean)
n193+.. method:: FTP.set_pasv(boolean)
180
181   Enable "passive" mode if *boolean* is true, other disable passive mode.  (In
182   Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
183   it is on by default.)
184
185
n186-.. method:: XXX Class.storbinary(command, file[, blocksize])
n200+.. method:: FTP.storbinary(command, file[, blocksize, callback])
187
188   Store a file in binary transfer mode.  *command* should be an appropriate
189   ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
190   read until EOF using its :meth:`read` method in blocks of size *blocksize* to
191   provide the data to be stored.  The *blocksize* argument defaults to 8192.
n206+   *callback* is an optional single parameter callable that is called
207+   on each block of data after it is sent.
192
193   .. versionchanged:: 2.1
194      default for *blocksize* added.
195
n212+   .. versionchanged:: 2.6
213+      *callback* parameter added.
196
n215+ 
197-.. method:: XXX Class.storlines(command, file)
216+.. method:: FTP.storlines(command, file[, callback])
198
199   Store a file in ASCII transfer mode.  *command* should be an appropriate
200   ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
201   open file object *file* using its :meth:`readline` method to provide the data to
n202-   be stored.
n221+   be stored.  *callback* is an optional single parameter callable
222+   that is called on each line after it is sent.
203
n224+   .. versionchanged:: 2.6
225+      *callback* parameter added.
204
n227+ 
205-.. method:: XXX Class.transfercmd(cmd[, rest])
228+.. method:: FTP.transfercmd(cmd[, rest])
206
207   Initiate a transfer over the data connection.  If the transfer is active, send a
208   ``EPRT`` or  ``PORT`` command and the transfer command specified by *cmd*, and
209   accept the connection.  If the server is passive, send a ``EPSV`` or ``PASV``
210   command, connect to it, and start the transfer command.  Either way, return the
211   socket for the connection.
212
213   If optional *rest* is given, a ``REST`` command is sent to the server, passing
217   *rest* be a string containing characters in the printable range from ASCII code
218   33 to ASCII code 126.  The :meth:`transfercmd` method, therefore, converts
219   *rest* to a string, but no check is performed on the string's contents.  If the
220   server does not recognize the ``REST`` command, an :exc:`error_reply` exception
221   will be raised.  If this happens, simply call :meth:`transfercmd` without a
222   *rest* argument.
223
224
n225-.. method:: XXX Class.ntransfercmd(cmd[, rest])
n248+.. method:: FTP.ntransfercmd(cmd[, rest])
226
227   Like :meth:`transfercmd`, but returns a tuple of the data connection and the
228   expected size of the data.  If the expected size could not be computed, ``None``
229   will be returned as the expected size.  *cmd* and *rest* means the same thing as
230   in :meth:`transfercmd`.
231
232
n233-.. method:: XXX Class.nlst(argument[, ...])
n256+.. method:: FTP.nlst(argument[, ...])
234
235   Return a list of files as returned by the ``NLST`` command.  The optional
236   *argument* is a directory to list (default is the current server directory).
237   Multiple arguments can be used to pass non-standard options to the ``NLST``
238   command.
239
240
n241-.. method:: XXX Class.dir(argument[, ...])
n264+.. method:: FTP.dir(argument[, ...])
242
243   Produce a directory listing as returned by the ``LIST`` command, printing it to
244   standard output.  The optional *argument* is a directory to list (default is the
245   current server directory).  Multiple arguments can be used to pass non-standard
246   options to the ``LIST`` command.  If the last argument is a function, it is used
247   as a *callback* function as for :meth:`retrlines`; the default prints to
248   ``sys.stdout``.  This method returns ``None``.
249
250
n251-.. method:: XXX Class.rename(fromname, toname)
n274+.. method:: FTP.rename(fromname, toname)
252
253   Rename file *fromname* on the server to *toname*.
254
255
n256-.. method:: XXX Class.delete(filename)
n279+.. method:: FTP.delete(filename)
257
258   Remove the file named *filename* from the server.  If successful, returns the
259   text of the response, otherwise raises :exc:`error_perm` on permission errors or
260   :exc:`error_reply` on other errors.
261
262
n263-.. method:: XXX Class.cwd(pathname)
n286+.. method:: FTP.cwd(pathname)
264
265   Set the current directory on the server.
266
267
n268-.. method:: XXX Class.mkd(pathname)
n291+.. method:: FTP.mkd(pathname)
269
270   Create a new directory on the server.
271
272
n273-.. method:: XXX Class.pwd()
n296+.. method:: FTP.pwd()
274
275   Return the pathname of the current directory on the server.
276
277
n278-.. method:: XXX Class.rmd(dirname)
n301+.. method:: FTP.rmd(dirname)
279
280   Remove the directory named *dirname* on the server.
281
282
n283-.. method:: XXX Class.size(filename)
n306+.. method:: FTP.size(filename)
284
285   Request the size of the file named *filename* on the server.  On success, the
286   size of the file is returned as an integer, otherwise ``None`` is returned.
287   Note that the ``SIZE`` command is not  standardized, but is supported by many
288   common server implementations.
289
290
n291-.. method:: XXX Class.quit()
n314+.. method:: FTP.quit()
292
293   Send a ``QUIT`` command to the server and close the connection. This is the
n294-   "polite" way to close a connection, but it may raise an exception of the server
n317+   "polite" way to close a connection, but it may raise an exception if the server
295-   reponds with an error to the ``QUIT`` command.  This implies a call to the
318+   responds with an error to the ``QUIT`` command.  This implies a call to the
296   :meth:`close` method which renders the :class:`FTP` instance useless for
297   subsequent calls (see below).
298
299
t300-.. method:: XXX Class.close()
t323+.. method:: FTP.close()
301
302   Close the connection unilaterally.  This should not be applied to an already
303   closed connection such as after a successful call to :meth:`quit`.  After this
304   call the :class:`FTP` instance should not be used any more (after a call to
305   :meth:`close` or :meth:`quit` you cannot reopen the connection by issuing
306   another :meth:`login` method).
307
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op