| \section{Standard Module \sectcode{ftplib}} |
| \label{module-ftplib} |
| \stmodindex{ftplib} |
| \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 |
| automated FTP jobs, such as mirroring other ftp servers. It is also |
| used by the module \module{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.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 \code{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} |
| |
| \subsection{FTP Objects} |
| |
| \class{FTP} instances have the following methods: |
| |
| \setindexsubitem{(FTP method)} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{abort}{} |
| Abort a file transfer that is in progress. Using this does not always |
| work, but it's worth a try. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{sendcmd}{command} |
| Send a simple command string to the server and return the response |
| string. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{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{funcdesc} |
| |
| \begin{funcdesc}{dir}{argument\optional{, \ldots}} |
| 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 |
| (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()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rename}{fromname, toname} |
| Rename file \var{fromname} on the server to \var{toname}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{cwd}{pathname} |
| Set the current directory on the server. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{mkd}{pathname} |
| Create a new directory on the server. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pwd}{} |
| Return the pathname of the current directory on the server. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{close}{} |
| Close the connection unilaterally. This should not be applied to an |
| already closed connection (e.g.\ after a successful call to |
| \method{quit()}. |
| \end{funcdesc} |