\section{\module{ftplib} ---
         FTP protocol client}

\declaremodule{standard}{ftplib}
\modulesynopsis{FTP protocol client (requires sockets).}


This module defines the class \class{FTP} and a few related items.
The \class{FTP} class implements the client side of the FTP
protocol.\indexii{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 user@hostname
>>> 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
\samp{\var{realuser}@\var{host}} where \var{realuser} is the real user
name (glanced from the \envvar{LOGNAME} or \envvar{USER} environment
variable) and \var{host} is the hostname as returned by
\function{socket.gethostname()}.  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}}
Retrieve a file in binary transfer mode.  \var{command} should be an
appropriate \samp{RETR} command, i.e.\ \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.
\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.
\end{methoddesc}

\begin{methoddesc}{storbinary}{command, file, blocksize}
Store a file in binary transfer mode.  \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \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.
\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 privide the data to be stored.
\end{methoddesc}

\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}}
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 (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}