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