Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{ftplib} --- |
Fred Drake | 5967667 | 1999-03-18 16:08:54 +0000 | [diff] [blame] | 2 | FTP protocol client} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{ftplib} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{FTP protocol client (requires sockets).} |
| 6 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 7 | |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 8 | This module defines the class \class{FTP} and a few related items. |
Fred Drake | 5967667 | 1999-03-18 16:08:54 +0000 | [diff] [blame] | 9 | The \class{FTP} class implements the client side of the FTP |
| 10 | protocol.\indexii{FTP}{protocol} You can use this to write Python |
| 11 | programs that perform a variety of automated FTP jobs, such as |
| 12 | mirroring other ftp servers. It is also used by the module |
| 13 | \refmodule{urllib} to handle URLs that use FTP. For more information |
| 14 | on FTP (File Transfer Protocol), see Internet \rfc{959}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 15 | |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 16 | Here's a sample session using the \module{ftplib} module: |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 17 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 18 | \begin{verbatim} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 19 | >>> from ftplib import FTP |
| 20 | >>> ftp = FTP('ftp.cwi.nl') # connect to host, default port |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 21 | >>> ftp.login() # user anonymous, passwd user@hostname |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 22 | >>> ftp.retrlines('LIST') # list directory contents |
| 23 | total 24418 |
| 24 | drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 . |
| 25 | dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. |
| 26 | -rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX |
| 27 | . |
| 28 | . |
| 29 | . |
Fred Drake | 161edc2 | 1998-08-07 17:30:49 +0000 | [diff] [blame] | 30 | >>> ftp.retrbinary('RETR README', open('README', 'wb').write) |
| 31 | '226 Transfer complete.' |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 32 | >>> ftp.quit() |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 33 | \end{verbatim} |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 34 | |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 35 | The module defines the following items: |
| 36 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 37 | \begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, |
| 38 | passwd\optional{, acct}}}}} |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 39 | Return a new instance of the \class{FTP} class. When |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 40 | \var{host} is given, the method call \code{connect(\var{host})} is |
| 41 | made. When \var{user} is given, additionally the method call |
| 42 | \code{login(\var{user}, \var{passwd}, \var{acct})} is made (where |
| 43 | \var{passwd} and \var{acct} default to the empty string when not given). |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 44 | \end{classdesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 45 | |
| 46 | \begin{datadesc}{all_errors} |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 47 | The set of all exceptions (as a tuple) that methods of \class{FTP} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 48 | instances may raise as a result of problems with the FTP connection |
| 49 | (as opposed to programming errors made by the caller). This set |
| 50 | includes the four exceptions listed below as well as |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 51 | \exception{socket.error} and \exception{IOError}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 52 | \end{datadesc} |
| 53 | |
| 54 | \begin{excdesc}{error_reply} |
| 55 | Exception raised when an unexpected reply is received from the server. |
| 56 | \end{excdesc} |
| 57 | |
| 58 | \begin{excdesc}{error_temp} |
| 59 | Exception raised when an error code in the range 400--499 is received. |
| 60 | \end{excdesc} |
| 61 | |
| 62 | \begin{excdesc}{error_perm} |
| 63 | Exception raised when an error code in the range 500--599 is received. |
| 64 | \end{excdesc} |
| 65 | |
| 66 | \begin{excdesc}{error_proto} |
| 67 | Exception raised when a reply is received from the server that does |
| 68 | not begin with a digit in the range 1--5. |
| 69 | \end{excdesc} |
| 70 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 71 | |
Fred Drake | e82f5b3 | 1999-03-25 05:04:17 +0000 | [diff] [blame] | 72 | \begin{seealso} |
Fred Drake | 184e836 | 1999-05-11 15:14:15 +0000 | [diff] [blame] | 73 | \seemodule{netrc}{Parser for the \file{.netrc} file format. The file |
| 74 | \file{.netrc} is typically used by FTP clients to |
| 75 | load user authentication information before prompting |
| 76 | the user.} |
Fred Drake | e82f5b3 | 1999-03-25 05:04:17 +0000 | [diff] [blame] | 77 | \seetext{The file \file{Tools/scripts/ftpmirror.py}\index{ftpmirror.py} |
| 78 | in the Python source distribution is a script that can mirror |
| 79 | FTP sites, or portions thereof, using the \module{ftplib} module. |
| 80 | It can be used as an extended example that applies this module.} |
| 81 | \end{seealso} |
| 82 | |
| 83 | |
Fred Drake | 5967667 | 1999-03-18 16:08:54 +0000 | [diff] [blame] | 84 | \subsection{FTP Objects \label{ftp-objects}} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 85 | |
Fred Drake | 33378da | 1999-05-17 16:35:15 +0000 | [diff] [blame] | 86 | Several methods are available in two flavors: one for handling text |
| 87 | files and another for binary files. These are named for the command |
| 88 | which is used followed by \samp{lines} for the text version or |
| 89 | \samp{binary} for the binary version. |
| 90 | |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 91 | \class{FTP} instances have the following methods: |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 92 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 93 | \begin{methoddesc}{set_debuglevel}{level} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 94 | Set the instance's debugging level. This controls the amount of |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 95 | debugging output printed. The default, \code{0}, produces no |
| 96 | debugging output. A value of \code{1} produces a moderate amount of |
| 97 | debugging output, generally a single line per request. A value of |
| 98 | \code{2} or higher produces the maximum amount of debugging output, |
| 99 | logging each line sent and received on the control connection. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 100 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 101 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 102 | \begin{methoddesc}{connect}{host\optional{, port}} |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 103 | Connect to the given host and port. The default port number is \code{21}, as |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 104 | specified by the FTP protocol specification. It is rarely needed to |
| 105 | specify a different port number. This function should be called only |
| 106 | once for each instance; it should not be called at all if a host was |
| 107 | given when the instance was created. All other methods can only be |
| 108 | used after a connection has been made. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 109 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 110 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 111 | \begin{methoddesc}{getwelcome}{} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 112 | Return the welcome message sent by the server in reply to the initial |
| 113 | connection. (This message sometimes contains disclaimers or help |
| 114 | information that may be relevant to the user.) |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 115 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 116 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 117 | \begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 118 | Log in as the given \var{user}. The \var{passwd} and \var{acct} |
| 119 | parameters are optional and default to the empty string. If no |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 120 | \var{user} is specified, it defaults to \code{'anonymous'}. If |
Fred Drake | 5967667 | 1999-03-18 16:08:54 +0000 | [diff] [blame] | 121 | \var{user} is \code{'anonymous'}, the default \var{passwd} is |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 122 | \samp{\var{realuser}@\var{host}} where \var{realuser} is the real user |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 123 | name (glanced from the \envvar{LOGNAME} or \envvar{USER} environment |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 124 | variable) and \var{host} is the hostname as returned by |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 125 | \function{socket.gethostname()}. This function should be called only |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 126 | once for each instance, after a connection has been established; it |
| 127 | should not be called at all if a host and user were given when the |
| 128 | instance was created. Most FTP commands are only allowed after the |
| 129 | client has logged in. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 130 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 131 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 132 | \begin{methoddesc}{abort}{} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 133 | Abort a file transfer that is in progress. Using this does not always |
| 134 | work, but it's worth a try. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 135 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 136 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 137 | \begin{methoddesc}{sendcmd}{command} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 138 | Send a simple command string to the server and return the response |
| 139 | string. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 140 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 141 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 142 | \begin{methoddesc}{voidcmd}{command} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 143 | Send a simple command string to the server and handle the response. |
| 144 | Return nothing if a response code in the range 200--299 is received. |
| 145 | Raise an exception otherwise. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 146 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 147 | |
Barry Warsaw | 21fbd54 | 2000-09-01 06:32:32 +0000 | [diff] [blame] | 148 | \begin{methoddesc}{retrbinary}{command, |
| 149 | callback\optional{, maxblocksize\optional{, rest}}} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 150 | Retrieve a file in binary transfer mode. \var{command} should be an |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 151 | appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 152 | The \var{callback} function is called for each block of data received, |
| 153 | with a single string argument giving the data block. |
Guido van Rossum | ab76af3 | 1997-12-03 19:34:14 +0000 | [diff] [blame] | 154 | The optional \var{maxblocksize} argument specifies the maximum chunk size to |
| 155 | read on the low-level socket object created to do the actual transfer |
| 156 | (which will also be the largest size of the data blocks passed to |
Barry Warsaw | 21fbd54 | 2000-09-01 06:32:32 +0000 | [diff] [blame] | 157 | \var{callback}). A reasonable default is chosen. \var{rest} means the |
| 158 | same thing as in the \method{transfercmd()} method. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 159 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 160 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 161 | \begin{methoddesc}{retrlines}{command\optional{, callback}} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 162 | Retrieve a file or directory listing in \ASCII{} transfer mode. |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 163 | \var{command} should be an appropriate \samp{RETR} command (see |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 164 | \method{retrbinary()} or a \samp{LIST} command (usually just the string |
| 165 | \code{'LIST'}). The \var{callback} function is called for each line, |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 166 | with the trailing CRLF stripped. The default \var{callback} prints |
| 167 | the line to \code{sys.stdout}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 168 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 169 | |
Fred Drake | 5967667 | 1999-03-18 16:08:54 +0000 | [diff] [blame] | 170 | \begin{methoddesc}{set_pasv}{boolean} |
| 171 | Enable ``passive'' mode if \var{boolean} is true, other disable |
Guido van Rossum | 97d3b93 | 2001-01-15 16:37:05 +0000 | [diff] [blame] | 172 | passive mode. (In Python 2.0 and before, passive mode was off by |
| 173 | default; in Python 2.1 and later, it is on by default.) |
Fred Drake | 5967667 | 1999-03-18 16:08:54 +0000 | [diff] [blame] | 174 | \end{methoddesc} |
| 175 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 176 | \begin{methoddesc}{storbinary}{command, file, blocksize} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 177 | Store a file in binary transfer mode. \var{command} should be an |
| 178 | appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 179 | \var{file} is an open file object which is read until \EOF{} using its |
| 180 | \method{read()} method in blocks of size \var{blocksize} to provide the |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 181 | data to be stored. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 182 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 183 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 184 | \begin{methoddesc}{storlines}{command, file} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 185 | Store a file in \ASCII{} transfer mode. \var{command} should be an |
Fred Drake | 6a1eefe | 1998-03-12 06:04:53 +0000 | [diff] [blame] | 186 | appropriate \samp{STOR} command (see \method{storbinary()}). Lines are |
| 187 | read until \EOF{} from the open file object \var{file} using its |
Fred Drake | 5d48e45 | 1999-07-20 13:21:42 +0000 | [diff] [blame] | 188 | \method{readline()} method to provide the data to be stored. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 189 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 190 | |
Barry Warsaw | 21fbd54 | 2000-09-01 06:32:32 +0000 | [diff] [blame] | 191 | \begin{methoddesc}{transfercmd}{cmd\optional{, rest}} |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 192 | Initiate a transfer over the data connection. If the transfer is |
| 193 | active, send a \samp{PORT} command and the transfer command specified |
| 194 | by \var{cmd}, and accept the connection. If the server is passive, |
| 195 | send a \samp{PASV} command, connect to it, and start the transfer |
| 196 | command. Either way, return the socket for the connection. |
Barry Warsaw | 21fbd54 | 2000-09-01 06:32:32 +0000 | [diff] [blame] | 197 | |
| 198 | If optional \var{rest} is given, a \samp{REST} command is |
| 199 | sent to the server, passing \var{rest} as an argument. \var{rest} is |
| 200 | usually a byte offset into the requested file, telling the server to |
| 201 | restart sending the file's bytes at the requested offset, skipping |
| 202 | over the initial bytes. Note however that RFC |
| 203 | 959 requires only that \var{rest} be a string containing characters |
| 204 | in the printable range from ASCII code 33 to ASCII code 126. The |
| 205 | \method{transfercmd()} method, therefore, converts |
| 206 | \var{rest} to a string, but no check is |
| 207 | performed on the string's contents. If the server does |
| 208 | not recognize the \samp{REST} command, an |
| 209 | \exception{error_reply} exception will be raised. If this happens, |
| 210 | simply call \method{transfercmd()} without a \var{rest} argument. |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 211 | \end{methoddesc} |
| 212 | |
Barry Warsaw | 21fbd54 | 2000-09-01 06:32:32 +0000 | [diff] [blame] | 213 | \begin{methoddesc}{ntransfercmd}{cmd\optional{, rest}} |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 214 | Like \method{transfercmd()}, but returns a tuple of the data |
| 215 | connection and the expected size of the data. If the expected size |
| 216 | could not be computed, \code{None} will be returned as the expected |
Barry Warsaw | 21fbd54 | 2000-09-01 06:32:32 +0000 | [diff] [blame] | 217 | size. \var{cmd} and \var{rest} means the same thing as in |
| 218 | \method{transfercmd()}. |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 219 | \end{methoddesc} |
| 220 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 221 | \begin{methoddesc}{nlst}{argument\optional{, \ldots}} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 222 | Return a list of files as returned by the \samp{NLST} command. The |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 223 | optional \var{argument} is a directory to list (default is the current |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 224 | server directory). Multiple arguments can be used to pass |
| 225 | non-standard options to the \samp{NLST} command. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 226 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 227 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 228 | \begin{methoddesc}{dir}{argument\optional{, \ldots}} |
Fred Drake | 1508970 | 1999-07-07 13:36:22 +0000 | [diff] [blame] | 229 | Produce a directory listing as returned by the \samp{LIST} command, |
| 230 | printing it to standard output. The optional \var{argument} is a |
| 231 | directory to list (default is the current server directory). Multiple |
| 232 | arguments can be used to pass non-standard options to the \samp{LIST} |
| 233 | command. If the last argument is a function, it is used as a |
| 234 | \var{callback} function as for \method{retrlines()}; the default |
| 235 | prints to \code{sys.stdout}. This method returns \code{None}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 236 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 237 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 238 | \begin{methoddesc}{rename}{fromname, toname} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 239 | Rename file \var{fromname} on the server to \var{toname}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 240 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 241 | |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 242 | \begin{methoddesc}{delete}{filename} |
| 243 | Remove the file named \var{filename} from the server. If successful, |
| 244 | returns the text of the response, otherwise raises |
Fred Drake | 4429772 | 1999-04-22 16:15:34 +0000 | [diff] [blame] | 245 | \exception{error_perm} on permission errors or |
| 246 | \exception{error_reply} on other errors. |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 247 | \end{methoddesc} |
| 248 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 249 | \begin{methoddesc}{cwd}{pathname} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 250 | Set the current directory on the server. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 251 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 252 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 253 | \begin{methoddesc}{mkd}{pathname} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 254 | Create a new directory on the server. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 255 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 256 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 257 | \begin{methoddesc}{pwd}{} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 258 | Return the pathname of the current directory on the server. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 259 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 260 | |
Fred Drake | 4f31694 | 1998-04-27 14:54:06 +0000 | [diff] [blame] | 261 | \begin{methoddesc}{rmd}{dirname} |
| 262 | Remove the directory named \var{dirname} on the server. |
| 263 | \end{methoddesc} |
| 264 | |
| 265 | \begin{methoddesc}{size}{filename} |
| 266 | Request the size of the file named \var{filename} on the server. On |
| 267 | success, the size of the file is returned as an integer, otherwise |
| 268 | \code{None} is returned. Note that the \samp{SIZE} command is not |
| 269 | standardized, but is supported by many common server implementations. |
| 270 | \end{methoddesc} |
| 271 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 272 | \begin{methoddesc}{quit}{} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 273 | Send a \samp{QUIT} command to the server and close the connection. |
| 274 | This is the ``polite'' way to close a connection, but it may raise an |
Fred Drake | 4429772 | 1999-04-22 16:15:34 +0000 | [diff] [blame] | 275 | exception of the server reponds with an error to the |
| 276 | \samp{QUIT} command. This implies a call to the \method{close()} |
| 277 | method which renders the \class{FTP} instance useless for subsequent |
| 278 | calls (see below). |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 279 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 280 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 281 | \begin{methoddesc}{close}{} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 282 | Close the connection unilaterally. This should not be applied to an |
| 283 | already closed connection (e.g.\ after a successful call to |
Guido van Rossum | 730d837 | 1998-08-07 17:36:59 +0000 | [diff] [blame] | 284 | \method{quit()}. After this call the \class{FTP} instance should not |
| 285 | be used any more (i.e., after a call to \method{close()} or |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 286 | \method{quit()} you cannot reopen the connection by issuing another |
Guido van Rossum | 730d837 | 1998-08-07 17:36:59 +0000 | [diff] [blame] | 287 | \method{login()} method). |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 288 | \end{methoddesc} |