cpython/Doc/lib/libftplib.tex

251 lines
10 KiB
TeX
Raw Normal View History

\section{\module{ftplib} ---
FTP protocol client.}
\declaremodule{standard}{ftplib}
\modulesynopsis{FTP protocol client (requires sockets).}
\indexii{FTP}{protocol}
This module defines the class \class{FTP} and a few related items.
The \class{FTP} class implements the client side of the FTP protocol.
You can use this to write Python programs that perform a variety of
1995-03-22 11:48:46 -04:00
automated FTP jobs, such as mirroring other ftp servers. It is also
1998-03-12 02:04:53 -04:00
used by the module \module{urllib} to handle URLs that use FTP. For
more information on FTP (File Transfer Protocol), see Internet
\rfc{959}.
1995-03-22 11:48:46 -04:00
1998-03-12 02:04:53 -04:00
Here's a sample session using the \module{ftplib} module:
1995-03-22 11:48:46 -04:00
\begin{verbatim}
1995-03-22 11:48:46 -04:00
>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
1995-04-10 08:34:00 -03:00
>>> ftp.login() # user anonymous, passwd user@hostname
1995-03-22 11:48:46 -04:00
>>> ftp.retrlines('LIST') # list directory contents
total 24418
drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
-rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX
.
.
.
1998-08-07 14:30:49 -03:00
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
1995-03-22 11:48:46 -04:00
>>> ftp.quit()
\end{verbatim}
1998-03-12 02:04:53 -04:00
1995-03-22 11:48:46 -04:00
The module defines the following items:
\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{,
passwd\optional{, acct}}}}}
Return a new instance of the \class{FTP} class. When
1995-03-22 11:48:46 -04:00
\var{host} is given, the method call \code{connect(\var{host})} is
made. When \var{user} is given, additionally the method call
\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where
\var{passwd} and \var{acct} default to the empty string when not given).
1998-03-12 02:04:53 -04:00
\end{classdesc}
1995-03-22 11:48:46 -04:00
\begin{datadesc}{all_errors}
1998-03-12 02:04:53 -04:00
The set of all exceptions (as a tuple) that methods of \class{FTP}
1995-03-22 11:48:46 -04:00
instances may raise as a result of problems with the FTP connection
(as opposed to programming errors made by the caller). This set
includes the four exceptions listed below as well as
1998-03-12 02:04:53 -04:00
\exception{socket.error} and \exception{IOError}.
1995-03-22 11:48:46 -04:00
\end{datadesc}
\begin{excdesc}{error_reply}
Exception raised when an unexpected reply is received from the server.
\end{excdesc}
\begin{excdesc}{error_temp}
Exception raised when an error code in the range 400--499 is received.
\end{excdesc}
\begin{excdesc}{error_perm}
Exception raised when an error code in the range 500--599 is received.
\end{excdesc}
\begin{excdesc}{error_proto}
Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5.
\end{excdesc}
1995-03-22 11:48:46 -04:00
\subsection{FTP Objects}
\label{ftp-objects}
1995-03-22 11:48:46 -04:00
1998-03-12 02:04:53 -04:00
\class{FTP} instances have the following methods:
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{set_debuglevel}{level}
1995-03-22 11:48:46 -04:00
Set the instance's debugging level. This controls the amount of
1998-03-12 02:04:53 -04:00
debugging output printed. The default, \code{0}, produces no
debugging output. A value of \code{1} produces a moderate amount of
debugging output, generally a single line per request. A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the control connection.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{connect}{host\optional{, port}}
1998-03-12 02:04:53 -04:00
Connect to the given host and port. The default port number is \code{21}, as
1995-03-22 11:48:46 -04:00
specified by the FTP protocol specification. It is rarely needed to
specify a different port number. This function should be called only
once for each instance; it should not be called at all if a host was
given when the instance was created. All other methods can only be
used after a connection has been made.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{getwelcome}{}
1995-03-22 11:48:46 -04:00
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
1995-03-22 11:48:46 -04:00
Log in as the given \var{user}. The \var{passwd} and \var{acct}
parameters are optional and default to the empty string. If no
1998-03-12 02:04:53 -04:00
\var{user} is specified, it defaults to \code{'anonymous'}. If
1995-03-22 11:48:46 -04:00
\var{user} is \code{anonymous}, the default \var{passwd} is
\samp{\var{realuser}@\var{host}} where \var{realuser} is the real user
1998-03-12 02:04:53 -04:00
name (glanced from the \envvar{LOGNAME} or \envvar{USER} environment
1995-03-22 11:48:46 -04:00
variable) and \var{host} is the hostname as returned by
1998-03-12 02:04:53 -04:00
\function{socket.gethostname()}. This function should be called only
1995-03-22 11:48:46 -04:00
once for each instance, after a connection has been established; it
should not be called at all if a host and user were given when the
instance was created. Most FTP commands are only allowed after the
client has logged in.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{abort}{}
1995-03-22 11:48:46 -04:00
Abort a file transfer that is in progress. Using this does not always
work, but it's worth a try.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{sendcmd}{command}
1995-03-22 11:48:46 -04:00
Send a simple command string to the server and return the response
string.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{voidcmd}{command}
1995-03-22 11:48:46 -04:00
Send a simple command string to the server and handle the response.
Return nothing if a response code in the range 200--299 is received.
Raise an exception otherwise.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{retrbinary}{command, callback\optional{, maxblocksize}}
1995-03-22 11:48:46 -04:00
Retrieve a file in binary transfer mode. \var{command} should be an
1998-03-12 02:04:53 -04:00
appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}.
1995-03-22 11:48:46 -04:00
The \var{callback} function is called for each block of data received,
with a single string argument giving the data block.
The optional \var{maxblocksize} argument specifies the maximum chunk size to
read on the low-level socket object created to do the actual transfer
(which will also be the largest size of the data blocks passed to
\var{callback}). A reasonable default is chosen.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{retrlines}{command\optional{, callback}}
1995-03-22 11:48:46 -04:00
Retrieve a file or directory listing in \ASCII{} transfer mode.
\var{command} should be an appropriate \samp{RETR} command (see
1998-03-12 02:04:53 -04:00
\method{retrbinary()} or a \samp{LIST} command (usually just the string
\code{'LIST'}). The \var{callback} function is called for each line,
1995-03-22 11:48:46 -04:00
with the trailing CRLF stripped. The default \var{callback} prints
the line to \code{sys.stdout}.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{storbinary}{command, file, blocksize}
1995-03-22 11:48:46 -04:00
Store a file in binary transfer mode. \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
1998-03-12 02:04:53 -04:00
\var{file} is an open file object which is read until \EOF{} using its
\method{read()} method in blocks of size \var{blocksize} to provide the
1995-03-22 11:48:46 -04:00
data to be stored.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{storlines}{command, file}
1995-03-22 11:48:46 -04:00
Store a file in \ASCII{} transfer mode. \var{command} should be an
1998-03-12 02:04:53 -04:00
appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
read until \EOF{} from the open file object \var{file} using its
\method{readline()} method to privide the data to be stored.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{transfercmd}{cmd}
Initiate a transfer over the data connection. If the transfer is
active, send a \samp{PORT} command and the transfer command specified
by \var{cmd}, and accept the connection. If the server is passive,
send a \samp{PASV} command, connect to it, and start the transfer
command. Either way, return the socket for the connection.
\end{methoddesc}
\begin{methoddesc}{ntransfercmd}{cmd}
Like \method{transfercmd()}, but returns a tuple of the data
connection and the expected size of the data. If the expected size
could not be computed, \code{None} will be returned as the expected
size.
\end{methoddesc}
\begin{methoddesc}{nlst}{argument\optional{, \ldots}}
1995-03-22 11:48:46 -04:00
Return a list of files as returned by the \samp{NLST} command. The
optional \var{argument} is a directory to list (default is the current
1995-03-22 11:48:46 -04:00
server directory). Multiple arguments can be used to pass
non-standard options to the \samp{NLST} command.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{dir}{argument\optional{, \ldots}}
1995-03-22 11:48:46 -04:00
Return a directory listing as returned by the \samp{LIST} command, as
a list of lines. The optional \var{argument} is a directory to list
1995-03-22 11:48:46 -04:00
(default is the current server directory). Multiple arguments can be
used to pass non-standard options to the \samp{LIST} command. If the
last argument is a function, it is used as a \var{callback} function
1998-03-12 02:04:53 -04:00
as for \method{retrlines()}.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{rename}{fromname, toname}
1995-03-22 11:48:46 -04:00
Rename file \var{fromname} on the server to \var{toname}.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{delete}{filename}
Remove the file named \var{filename} from the server. If successful,
returns the text of the response, otherwise raises
\exception{error_perm} on permission errors or \exception{error_reply}
on other errors.
\end{methoddesc}
\begin{methoddesc}{cwd}{pathname}
1995-03-22 11:48:46 -04:00
Set the current directory on the server.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{mkd}{pathname}
1995-03-22 11:48:46 -04:00
Create a new directory on the server.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{pwd}{}
1995-03-22 11:48:46 -04:00
Return the pathname of the current directory on the server.
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{rmd}{dirname}
Remove the directory named \var{dirname} on the server.
\end{methoddesc}
\begin{methoddesc}{size}{filename}
Request the size of the file named \var{filename} on the server. On
success, the size of the file is returned as an integer, otherwise
\code{None} is returned. Note that the \samp{SIZE} command is not
standardized, but is supported by many common server implementations.
\end{methoddesc}
\begin{methoddesc}{quit}{}
1995-03-22 11:48:46 -04:00
Send a \samp{QUIT} command to the server and close the connection.
This is the ``polite'' way to close a connection, but it may raise an
1998-03-12 02:04:53 -04:00
exception of the server reponds with an error to the \samp{QUIT}
command. This implies a call to the \method{close()} method which
renders the \class{FTP} instance useless for subsequent calls (see
below).
\end{methoddesc}
1995-03-22 11:48:46 -04:00
\begin{methoddesc}{close}{}
1995-03-22 11:48:46 -04:00
Close the connection unilaterally. This should not be applied to an
already closed connection (e.g.\ after a successful call to
\method{quit()}. After this call the \class{FTP} instance should not
be used any more (i.e., after a call to \method{close()} or
\method{quit()} you cannot reopen the connection by issueing another
\method{login()} method).
\end{methoddesc}