Doc/libftplib.tex

   1 \section{Standard Module \sectcode{ftplib}}
   2 \stmodindex{ftplib}
   3
   4 \renewcommand{\indexsubitem}{(in module ftplib)}
   5
   6 This module defines the class \code{FTP} and a few related items.  The
   7 \code{FTP} class implements the client side of the FTP protocol.  You
   8 can use this to write Python programs that perform a variety of
   9 automated FTP jobs, such as mirroring other ftp servers.  It is also
  10 used by the module \code{urllib} to handle URLs that use FTP.  For
  11 more information on FTP (File Transfer Protocol), see Internet RFC
  12 959.
  13
  14 Here's a sample session using the \code{ftplib} module:
  15
  16 \begin{verbatim}
  17 >>> from ftplib import FTP
  18 >>> ftp = FTP('ftp.cwi.nl')   # connect to host, default port
  19 >>> ftp.login()               # user anonymous, passwd user@hostname
  20 >>> ftp.retrlines('LIST')     # list directory contents
  21 total 24418
  22 drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
  23 dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
  24 -rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
  25  .
  26  .
  27  .
  28 >>> ftp.quit()
  29 \end{verbatim}
  30
  31 The module defines the following items:
  32
  33 \begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}}
  34 Return a new instance of the \code{FTP} class.  When
  35 \var{host} is given, the method call \code{connect(\var{host})} is
  36 made.  When \var{user} is given, additionally the method call
  37 \code{login(\var{user}, \var{passwd}, \var{acct})} is made (where
  38 \var{passwd} and \var{acct} default to the empty string when not given).
  39 \end{funcdesc}
  40
  41 \begin{datadesc}{all_errors}
  42 The set of all exceptions (as a tuple) that methods of \code{FTP}
  43 instances may raise as a result of problems with the FTP connection
  44 (as opposed to programming errors made by the caller).  This set
  45 includes the four exceptions listed below as well as
  46 \code{socket.error} and \code{IOError}.
  47 \end{datadesc}
  48
  49 \begin{excdesc}{error_reply}
  50 Exception raised when an unexpected reply is received from the server.
  51 \end{excdesc}
  52
  53 \begin{excdesc}{error_temp}
  54 Exception raised when an error code in the range 400--499 is received.
  55 \end{excdesc}
  56
  57 \begin{excdesc}{error_perm}
  58 Exception raised when an error code in the range 500--599 is received.
  59 \end{excdesc}
  60
  61 \begin{excdesc}{error_proto}
  62 Exception raised when a reply is received from the server that does
  63 not begin with a digit in the range 1--5.
  64 \end{excdesc}
  65
  66 \subsection{FTP Objects}
  67
  68 FTP instances have the following methods:
  69
  70 \renewcommand{\indexsubitem}{(FTP object method)}
  71
  72 \begin{funcdesc}{set_debuglevel}{level}
  73 Set the instance's debugging level.  This controls the amount of
  74 debugging output printed.  The default, 0, produces no debugging
  75 output.  A value of 1 produces a moderate amount of debugging output,
  76 generally a single line per request.  A value of 2 or higher produces
  77 the maximum amount of debugging output, logging each line sent and
  78 received on the control connection.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{connect}{host\optional{\, port}}
  82 Connect to the given host and port.  The default port number is 21, as
  83 specified by the FTP protocol specification.  It is rarely needed to
  84 specify a different port number.  This function should be called only
  85 once for each instance; it should not be called at all if a host was
  86 given when the instance was created.  All other methods can only be
  87 used after a connection has been made.
  88 \end{funcdesc}
  89
  90 \begin{funcdesc}{getwelcome}{}
  91 Return the welcome message sent by the server in reply to the initial
  92 connection.  (This message sometimes contains disclaimers or help
  93 information that may be relevant to the user.)
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{login}{\optional{user\optional{\, passwd\optional{\, acct}}}}
  97 Log in as the given \var{user}.  The \var{passwd} and \var{acct}
  98 parameters are optional and default to the empty string.  If no
  99 \var{user} is specified, it defaults to \samp{anonymous}.  If
 100 \var{user} is \code{anonymous}, the default \var{passwd} is
 101 \samp{\var{realuser}@\var{host}} where \var{realuser} is the real user
 102 name (glanced from the \samp{LOGNAME} or \samp{USER} environment
 103 variable) and \var{host} is the hostname as returned by
 104 \code{socket.gethostname()}.  This function should be called only
 105 once for each instance, after a connection has been established; it
 106 should not be called at all if a host and user were given when the
 107 instance was created.  Most FTP commands are only allowed after the
 108 client has logged in.
 109 \end{funcdesc}
 110
 111 \begin{funcdesc}{abort}{}
 112 Abort a file transfer that is in progress.  Using this does not always
 113 work, but it's worth a try.
 114 \end{funcdesc}
 115
 116 \begin{funcdesc}{sendcmd}{command}
 117 Send a simple command string to the server and return the response
 118 string.
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{voidcmd}{command}
 122 Send a simple command string to the server and handle the response.
 123 Return nothing if a response code in the range 200--299 is received.
 124 Raise an exception otherwise.
 125 \end{funcdesc}
 126
 127 \begin{funcdesc}{retrbinary}{command\, callback\, maxblocksize}
 128 Retrieve a file in binary transfer mode.  \var{command} should be an
 129 appropriate \samp{RETR} command, i.e.\ \code{"RETR \var{filename}"}.
 130 The \var{callback} function is called for each block of data received,
 131 with a single string argument giving the data block.
 132 The \var{maxblocksize} argument specifies the maximum block size
 133 (which may not be the actual size of the data blocks passed to
 134 \var{callback}).
 135 \end{funcdesc}
 136
 137 \begin{funcdesc}{retrlines}{command\optional{\, callback}}
 138 Retrieve a file or directory listing in \ASCII{} transfer mode.
 139 var{command} should be an appropriate \samp{RETR} command (see
 140 \code{retrbinary()} or a \samp{LIST} command (usually just the string
 141 \code{"LIST"}).  The \var{callback} function is called for each line,
 142 with the trailing CRLF stripped.  The default \var{callback} prints
 143 the line to \code{sys.stdout}.
 144 \end{funcdesc}
 145
 146 \begin{funcdesc}{storbinary}{command\, file\, blocksize}
 147 Store a file in binary transfer mode.  \var{command} should be an
 148 appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
 149 \var{file} is an open file object which is read until EOF using its
 150 \code{read()} method in blocks of size \var{blocksize} to provide the
 151 data to be stored.
 152 \end{funcdesc}
 153
 154 \begin{funcdesc}{storlines}{command\, file}
 155 Store a file in \ASCII{} transfer mode.  \var{command} should be an
 156 appropriate \samp{STOR} command (see \code{storbinary()}).  Lines are
 157 read until EOF from the open file object \var{file} using its
 158 \code{readline()} method to privide the data to be stored.
 159 \end{funcdesc}
 160
 161 \begin{funcdesc}{nlst}{argument\optional{\, \ldots}}
 162 Return a list of files as returned by the \samp{NLST} command.  The
 163 optional var{argument} is a directory to list (default is the current
 164 server directory).  Multiple arguments can be used to pass
 165 non-standard options to the \samp{NLST} command.
 166 \end{funcdesc}
 167
 168 \begin{funcdesc}{dir}{argument\optional{\, \ldots}}
 169 Return a directory listing as returned by the \samp{LIST} command, as
 170 a list of lines.  The optional var{argument} is a directory to list
 171 (default is the current server directory).  Multiple arguments can be
 172 used to pass non-standard options to the \samp{LIST} command.  If the
 173 last argument is a function, it is used as a \var{callback} function
 174 as for \code{retrlines()}.
 175 \end{funcdesc}
 176
 177 \begin{funcdesc}{rename}{fromname\, toname}
 178 Rename file \var{fromname} on the server to \var{toname}.
 179 \end{funcdesc}
 180
 181 \begin{funcdesc}{cwd}{pathname}
 182 Set the current directory on the server.
 183 \end{funcdesc}
 184
 185 \begin{funcdesc}{mkd}{pathname}
 186 Create a new directory on the server.
 187 \end{funcdesc}
 188
 189 \begin{funcdesc}{pwd}{}
 190 Return the pathname of the current directory on the server.
 191 \end{funcdesc}
 192
 193 \begin{funcdesc}{quit}{}
 194 Send a \samp{QUIT} command to the server and close the connection.
 195 This is the ``polite'' way to close a connection, but it may raise an
 196 exception of the server reponds with an error to the \code{QUIT}
 197 command.
 198 \end{funcdesc}
 199
 200 \begin{funcdesc}{close}{}
 201 Close the connection unilaterally.  This should not be applied to an
 202 already closed connection (e.g.\ after a successful call to
 203 \code{quit()}.
 204 \end{funcdesc}