289 lines
12 KiB
TeX
289 lines
12 KiB
TeX
\section{\module{ftplib} ---
|
|
FTP protocol client}
|
|
|
|
\declaremodule{standard}{ftplib}
|
|
\modulesynopsis{FTP protocol client (requires sockets).}
|
|
|
|
\indexii{FTP}{protocol}
|
|
\index{FTP!\module{ftplib} (standard module)}
|
|
|
|
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 automated FTP jobs, such as
|
|
mirroring other ftp servers. It is also used by the module
|
|
\refmodule{urllib} to handle URLs that use FTP. For more information
|
|
on FTP (File Transfer Protocol), see Internet \rfc{959}.
|
|
|
|
Here's a sample session using the \module{ftplib} module:
|
|
|
|
\begin{verbatim}
|
|
>>> from ftplib import FTP
|
|
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
|
|
>>> ftp.login() # user anonymous, passwd anonymous@
|
|
>>> 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
|
|
.
|
|
.
|
|
.
|
|
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
|
|
'226 Transfer complete.'
|
|
>>> ftp.quit()
|
|
\end{verbatim}
|
|
|
|
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
|
|
\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).
|
|
\end{classdesc}
|
|
|
|
\begin{datadesc}{all_errors}
|
|
The set of all exceptions (as a tuple) that methods of \class{FTP}
|
|
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
|
|
\exception{socket.error} and \exception{IOError}.
|
|
\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}
|
|
|
|
|
|
\begin{seealso}
|
|
\seemodule{netrc}{Parser for the \file{.netrc} file format. The file
|
|
\file{.netrc} is typically used by FTP clients to
|
|
load user authentication information before prompting
|
|
the user.}
|
|
\seetext{The file \file{Tools/scripts/ftpmirror.py}\index{ftpmirror.py}
|
|
in the Python source distribution is a script that can mirror
|
|
FTP sites, or portions thereof, using the \module{ftplib} module.
|
|
It can be used as an extended example that applies this module.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{FTP Objects \label{ftp-objects}}
|
|
|
|
Several methods are available in two flavors: one for handling text
|
|
files and another for binary files. These are named for the command
|
|
which is used followed by \samp{lines} for the text version or
|
|
\samp{binary} for the binary version.
|
|
|
|
\class{FTP} instances have the following methods:
|
|
|
|
\begin{methoddesc}{set_debuglevel}{level}
|
|
Set the instance's debugging level. This controls the amount of
|
|
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}
|
|
|
|
\begin{methoddesc}{connect}{host\optional{, port}}
|
|
Connect to the given host and port. The default port number is \code{21}, as
|
|
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}
|
|
|
|
\begin{methoddesc}{getwelcome}{}
|
|
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}
|
|
|
|
\begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
|
|
Log in as the given \var{user}. The \var{passwd} and \var{acct}
|
|
parameters are optional and default to the empty string. If no
|
|
\var{user} is specified, it defaults to \code{'anonymous'}. If
|
|
\var{user} is \code{'anonymous'}, the default \var{passwd} is
|
|
\code{'anonymous@'}. This function should be called only
|
|
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}
|
|
|
|
\begin{methoddesc}{abort}{}
|
|
Abort a file transfer that is in progress. Using this does not always
|
|
work, but it's worth a try.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{sendcmd}{command}
|
|
Send a simple command string to the server and return the response
|
|
string.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{voidcmd}{command}
|
|
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}
|
|
|
|
\begin{methoddesc}{retrbinary}{command,
|
|
callback\optional{, maxblocksize\optional{, rest}}}
|
|
Retrieve a file in binary transfer mode. \var{command} should be an
|
|
appropriate \samp{RETR} command: \code{'RETR \var{filename}'}.
|
|
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. \var{rest} means the
|
|
same thing as in the \method{transfercmd()} method.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{retrlines}{command\optional{, callback}}
|
|
Retrieve a file or directory listing in \ASCII{} transfer mode.
|
|
\var{command} should be an appropriate \samp{RETR} command (see
|
|
\method{retrbinary()} or a \samp{LIST} command (usually just the string
|
|
\code{'LIST'}). The \var{callback} function is called for each line,
|
|
with the trailing CRLF stripped. The default \var{callback} prints
|
|
the line to \code{sys.stdout}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{set_pasv}{boolean}
|
|
Enable ``passive'' mode if \var{boolean} is true, other disable
|
|
passive mode. (In Python 2.0 and before, passive mode was off by
|
|
default; in Python 2.1 and later, it is on by default.)
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{storbinary}{command, file\optional{, blocksize}}
|
|
Store a file in binary transfer mode. \var{command} should be an
|
|
appropriate \samp{STOR} command: \code{"STOR \var{filename}"}.
|
|
\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
|
|
data to be stored. The \var{blocksize} argument defaults to 8192.
|
|
\versionchanged[default for \var{blocksize} added]{2.1}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{storlines}{command, file}
|
|
Store a file in \ASCII{} transfer mode. \var{command} should be an
|
|
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 provide the data to be stored.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{transfercmd}{cmd\optional{, rest}}
|
|
Initiate a transfer over the data connection. If the transfer is
|
|
active, send a \samp{EPRT} or \samp{PORT} command and the transfer command specified
|
|
by \var{cmd}, and accept the connection. If the server is passive,
|
|
send a \samp{EPSV} or \samp{PASV} command, connect to it, and start the transfer
|
|
command. Either way, return the socket for the connection.
|
|
|
|
If optional \var{rest} is given, a \samp{REST} command is
|
|
sent to the server, passing \var{rest} as an argument. \var{rest} is
|
|
usually a byte offset into the requested file, telling the server to
|
|
restart sending the file's bytes at the requested offset, skipping
|
|
over the initial bytes. Note however that RFC
|
|
959 requires only that \var{rest} be a string containing characters
|
|
in the printable range from ASCII code 33 to ASCII code 126. The
|
|
\method{transfercmd()} method, therefore, converts
|
|
\var{rest} to a string, but no check is
|
|
performed on the string's contents. If the server does
|
|
not recognize the \samp{REST} command, an
|
|
\exception{error_reply} exception will be raised. If this happens,
|
|
simply call \method{transfercmd()} without a \var{rest} argument.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{ntransfercmd}{cmd\optional{, rest}}
|
|
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. \var{cmd} and \var{rest} means the same thing as in
|
|
\method{transfercmd()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{nlst}{argument\optional{, \ldots}}
|
|
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
|
|
server directory). Multiple arguments can be used to pass
|
|
non-standard options to the \samp{NLST} command.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{dir}{argument\optional{, \ldots}}
|
|
Produce a directory listing as returned by the \samp{LIST} command,
|
|
printing it to standard output. The optional \var{argument} is a
|
|
directory to list (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 as for \method{retrlines()}; the default
|
|
prints to \code{sys.stdout}. This method returns \code{None}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{rename}{fromname, toname}
|
|
Rename file \var{fromname} on the server to \var{toname}.
|
|
\end{methoddesc}
|
|
|
|
\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}
|
|
Set the current directory on the server.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{mkd}{pathname}
|
|
Create a new directory on the server.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{pwd}{}
|
|
Return the pathname of the current directory on the server.
|
|
\end{methoddesc}
|
|
|
|
\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}{}
|
|
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
|
|
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}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Close the connection unilaterally. This should not be applied to an
|
|
already closed connection (such as after a successful call to
|
|
\method{quit()}. After this call the \class{FTP} instance should not
|
|
be used any more (after a call to \method{close()} or
|
|
\method{quit()} you cannot reopen the connection by issuing another
|
|
\method{login()} method).
|
|
\end{methoddesc}
|