Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{ftplib}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-ftplib} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 3 | \stmodindex{ftplib} |
Fred Drake | 15bac5d | 1998-01-07 13:13:42 +0000 | [diff] [blame] | 4 | \indexii{FTP}{protocol} |
| 5 | \index{RFC!959} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 6 | |
| 7 | \renewcommand{\indexsubitem}{(in module ftplib)} |
| 8 | |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 9 | This module defines the class \code{FTP} and a few related items. The |
| 10 | \code{FTP} class implements the client side of the FTP protocol. You |
| 11 | can use this to write Python programs that perform a variety of |
| 12 | automated FTP jobs, such as mirroring other ftp servers. It is also |
Guido van Rossum | 0bbbea1 | 1995-08-10 14:21:11 +0000 | [diff] [blame] | 13 | used by the module \code{urllib} to handle URLs that use FTP. For |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 14 | more information on FTP (File Transfer Protocol), see Internet RFC |
| 15 | 959. |
| 16 | |
| 17 | Here's a sample session using the \code{ftplib} module: |
| 18 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 19 | \bcode\begin{verbatim} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 20 | >>> from ftplib import FTP |
| 21 | >>> ftp = FTP('ftp.cwi.nl') # connect to host, default port |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 22 | >>> ftp.login() # user anonymous, passwd user@hostname |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 23 | >>> ftp.retrlines('LIST') # list directory contents |
| 24 | total 24418 |
| 25 | drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 . |
| 26 | dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. |
| 27 | -rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX |
| 28 | . |
| 29 | . |
| 30 | . |
| 31 | >>> ftp.quit() |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 32 | \end{verbatim}\ecode |
| 33 | % |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 34 | The module defines the following items: |
| 35 | |
| 36 | \begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}} |
| 37 | Return a new instance of the \code{FTP} class. When |
| 38 | \var{host} is given, the method call \code{connect(\var{host})} is |
| 39 | made. When \var{user} is given, additionally the method call |
| 40 | \code{login(\var{user}, \var{passwd}, \var{acct})} is made (where |
| 41 | \var{passwd} and \var{acct} default to the empty string when not given). |
| 42 | \end{funcdesc} |
| 43 | |
| 44 | \begin{datadesc}{all_errors} |
| 45 | The set of all exceptions (as a tuple) that methods of \code{FTP} |
| 46 | instances may raise as a result of problems with the FTP connection |
| 47 | (as opposed to programming errors made by the caller). This set |
| 48 | includes the four exceptions listed below as well as |
| 49 | \code{socket.error} and \code{IOError}. |
| 50 | \end{datadesc} |
| 51 | |
| 52 | \begin{excdesc}{error_reply} |
| 53 | Exception raised when an unexpected reply is received from the server. |
| 54 | \end{excdesc} |
| 55 | |
| 56 | \begin{excdesc}{error_temp} |
| 57 | Exception raised when an error code in the range 400--499 is received. |
| 58 | \end{excdesc} |
| 59 | |
| 60 | \begin{excdesc}{error_perm} |
| 61 | Exception raised when an error code in the range 500--599 is received. |
| 62 | \end{excdesc} |
| 63 | |
| 64 | \begin{excdesc}{error_proto} |
| 65 | Exception raised when a reply is received from the server that does |
| 66 | not begin with a digit in the range 1--5. |
| 67 | \end{excdesc} |
| 68 | |
| 69 | \subsection{FTP Objects} |
| 70 | |
| 71 | FTP instances have the following methods: |
| 72 | |
| 73 | \renewcommand{\indexsubitem}{(FTP object method)} |
| 74 | |
| 75 | \begin{funcdesc}{set_debuglevel}{level} |
| 76 | Set the instance's debugging level. This controls the amount of |
| 77 | debugging output printed. The default, 0, produces no debugging |
| 78 | output. A value of 1 produces a moderate amount of debugging output, |
| 79 | generally a single line per request. A value of 2 or higher produces |
| 80 | the maximum amount of debugging output, logging each line sent and |
| 81 | received on the control connection. |
| 82 | \end{funcdesc} |
| 83 | |
| 84 | \begin{funcdesc}{connect}{host\optional{\, port}} |
| 85 | Connect to the given host and port. The default port number is 21, as |
| 86 | specified by the FTP protocol specification. It is rarely needed to |
| 87 | specify a different port number. This function should be called only |
| 88 | once for each instance; it should not be called at all if a host was |
| 89 | given when the instance was created. All other methods can only be |
| 90 | used after a connection has been made. |
| 91 | \end{funcdesc} |
| 92 | |
| 93 | \begin{funcdesc}{getwelcome}{} |
| 94 | Return the welcome message sent by the server in reply to the initial |
| 95 | connection. (This message sometimes contains disclaimers or help |
| 96 | information that may be relevant to the user.) |
| 97 | \end{funcdesc} |
| 98 | |
| 99 | \begin{funcdesc}{login}{\optional{user\optional{\, passwd\optional{\, acct}}}} |
| 100 | Log in as the given \var{user}. The \var{passwd} and \var{acct} |
| 101 | parameters are optional and default to the empty string. If no |
| 102 | \var{user} is specified, it defaults to \samp{anonymous}. If |
| 103 | \var{user} is \code{anonymous}, the default \var{passwd} is |
| 104 | \samp{\var{realuser}@\var{host}} where \var{realuser} is the real user |
| 105 | name (glanced from the \samp{LOGNAME} or \samp{USER} environment |
| 106 | variable) and \var{host} is the hostname as returned by |
| 107 | \code{socket.gethostname()}. This function should be called only |
| 108 | once for each instance, after a connection has been established; it |
| 109 | should not be called at all if a host and user were given when the |
| 110 | instance was created. Most FTP commands are only allowed after the |
| 111 | client has logged in. |
| 112 | \end{funcdesc} |
| 113 | |
| 114 | \begin{funcdesc}{abort}{} |
| 115 | Abort a file transfer that is in progress. Using this does not always |
| 116 | work, but it's worth a try. |
| 117 | \end{funcdesc} |
| 118 | |
| 119 | \begin{funcdesc}{sendcmd}{command} |
| 120 | Send a simple command string to the server and return the response |
| 121 | string. |
| 122 | \end{funcdesc} |
| 123 | |
| 124 | \begin{funcdesc}{voidcmd}{command} |
| 125 | Send a simple command string to the server and handle the response. |
| 126 | Return nothing if a response code in the range 200--299 is received. |
| 127 | Raise an exception otherwise. |
| 128 | \end{funcdesc} |
| 129 | |
Guido van Rossum | ab76af3 | 1997-12-03 19:34:14 +0000 | [diff] [blame] | 130 | \begin{funcdesc}{retrbinary}{command\, callback\optional{\, maxblocksize}} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 131 | Retrieve a file in binary transfer mode. \var{command} should be an |
| 132 | appropriate \samp{RETR} command, i.e.\ \code{"RETR \var{filename}"}. |
| 133 | The \var{callback} function is called for each block of data received, |
| 134 | with a single string argument giving the data block. |
Guido van Rossum | ab76af3 | 1997-12-03 19:34:14 +0000 | [diff] [blame] | 135 | The optional \var{maxblocksize} argument specifies the maximum chunk size to |
| 136 | read on the low-level socket object created to do the actual transfer |
| 137 | (which will also be the largest size of the data blocks passed to |
| 138 | \var{callback}). A reasonable default is chosen. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 139 | \end{funcdesc} |
| 140 | |
| 141 | \begin{funcdesc}{retrlines}{command\optional{\, callback}} |
| 142 | Retrieve a file or directory listing in \ASCII{} transfer mode. |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 143 | \var{command} should be an appropriate \samp{RETR} command (see |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 144 | \code{retrbinary()} or a \samp{LIST} command (usually just the string |
| 145 | \code{"LIST"}). The \var{callback} function is called for each line, |
| 146 | with the trailing CRLF stripped. The default \var{callback} prints |
| 147 | the line to \code{sys.stdout}. |
| 148 | \end{funcdesc} |
| 149 | |
| 150 | \begin{funcdesc}{storbinary}{command\, file\, blocksize} |
| 151 | Store a file in binary transfer mode. \var{command} should be an |
| 152 | appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. |
| 153 | \var{file} is an open file object which is read until EOF using its |
| 154 | \code{read()} method in blocks of size \var{blocksize} to provide the |
| 155 | data to be stored. |
| 156 | \end{funcdesc} |
| 157 | |
| 158 | \begin{funcdesc}{storlines}{command\, file} |
| 159 | Store a file in \ASCII{} transfer mode. \var{command} should be an |
| 160 | appropriate \samp{STOR} command (see \code{storbinary()}). Lines are |
| 161 | read until EOF from the open file object \var{file} using its |
| 162 | \code{readline()} method to privide the data to be stored. |
| 163 | \end{funcdesc} |
| 164 | |
| 165 | \begin{funcdesc}{nlst}{argument\optional{\, \ldots}} |
| 166 | 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] | 167 | 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] | 168 | server directory). Multiple arguments can be used to pass |
| 169 | non-standard options to the \samp{NLST} command. |
| 170 | \end{funcdesc} |
| 171 | |
| 172 | \begin{funcdesc}{dir}{argument\optional{\, \ldots}} |
| 173 | Return a directory listing as returned by the \samp{LIST} command, as |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 174 | a list of lines. The optional \var{argument} is a directory to list |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 175 | (default is the current server directory). Multiple arguments can be |
| 176 | used to pass non-standard options to the \samp{LIST} command. If the |
| 177 | last argument is a function, it is used as a \var{callback} function |
| 178 | as for \code{retrlines()}. |
| 179 | \end{funcdesc} |
| 180 | |
| 181 | \begin{funcdesc}{rename}{fromname\, toname} |
| 182 | Rename file \var{fromname} on the server to \var{toname}. |
| 183 | \end{funcdesc} |
| 184 | |
| 185 | \begin{funcdesc}{cwd}{pathname} |
| 186 | Set the current directory on the server. |
| 187 | \end{funcdesc} |
| 188 | |
| 189 | \begin{funcdesc}{mkd}{pathname} |
| 190 | Create a new directory on the server. |
| 191 | \end{funcdesc} |
| 192 | |
| 193 | \begin{funcdesc}{pwd}{} |
| 194 | Return the pathname of the current directory on the server. |
| 195 | \end{funcdesc} |
| 196 | |
| 197 | \begin{funcdesc}{quit}{} |
| 198 | Send a \samp{QUIT} command to the server and close the connection. |
| 199 | This is the ``polite'' way to close a connection, but it may raise an |
| 200 | exception of the server reponds with an error to the \code{QUIT} |
| 201 | command. |
| 202 | \end{funcdesc} |
| 203 | |
| 204 | \begin{funcdesc}{close}{} |
| 205 | Close the connection unilaterally. This should not be applied to an |
| 206 | already closed connection (e.g.\ after a successful call to |
| 207 | \code{quit()}. |
| 208 | \end{funcdesc} |