source: trunk/essentials/dev-lang/python/Doc/lib/libftplib.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}{}