diff options
Diffstat (limited to 'Doc/lib/libftplib.tex')
| -rw-r--r-- | Doc/lib/libftplib.tex | 61 |
1 files changed, 35 insertions, 26 deletions
diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex index 58d16cb..98d7e80 100644 --- a/Doc/lib/libftplib.tex +++ b/Doc/lib/libftplib.tex @@ -37,12 +37,15 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. The module defines the following items: \begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, - passwd\optional{, acct}}}}} + passwd\optional{, acct\optional{, timeout}}}}}} 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). +The optional \var{timeout} parameter specifies a timeout in seconds for the +connection attempt (if is not specified, or passed as None, the global +default timeout setting will be used). \end{classdesc} \begin{datadesc}{all_errors} @@ -92,7 +95,7 @@ which is used followed by \samp{lines} for the text version or \class{FTP} instances have the following methods: -\begin{methoddesc}{set_debuglevel}{level} +\begin{methoddesc}[FTP]{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 @@ -101,22 +104,28 @@ debugging output, generally a single line per request. A value of logging each line sent and received on the control connection. \end{methoddesc} -\begin{methoddesc}{connect}{host\optional{, port}} +\begin{methoddesc}[FTP]{connect}{host\optional{, port\optional{, timeout}}} 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. + +The optional \var{timeout} parameter specifies a timeout in seconds for +the connection attempt. If is not specified, or passed as None, the +object timeout is used (the timeout that you passed when instantiating the +class); if the object timeout is also None, the global default timeout +setting will be used. \end{methoddesc} -\begin{methoddesc}{getwelcome}{} +\begin{methoddesc}[FTP]{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}}}} +\begin{methoddesc}[FTP]{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 @@ -128,23 +137,23 @@ instance was created. Most FTP commands are only allowed after the client has logged in. \end{methoddesc} -\begin{methoddesc}{abort}{} +\begin{methoddesc}[FTP]{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} +\begin{methoddesc}[FTP]{sendcmd}{command} Send a simple command string to the server and return the response string. \end{methoddesc} -\begin{methoddesc}{voidcmd}{command} +\begin{methoddesc}[FTP]{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, +\begin{methoddesc}[FTP]{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}'}. @@ -157,7 +166,7 @@ read on the low-level socket object created to do the actual transfer same thing as in the \method{transfercmd()} method. \end{methoddesc} -\begin{methoddesc}{retrlines}{command\optional{, callback}} +\begin{methoddesc}[FTP]{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 @@ -166,13 +175,13 @@ with the trailing CRLF stripped. The default \var{callback} prints the line to \code{sys.stdout}. \end{methoddesc} -\begin{methoddesc}{set_pasv}{boolean} +\begin{methoddesc}[FTP]{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}} +\begin{methoddesc}[FTP]{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 @@ -181,14 +190,14 @@ 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} +\begin{methoddesc}[FTP]{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}} +\begin{methoddesc}[FTP]{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, @@ -210,7 +219,7 @@ not recognize the \samp{REST} command, an simply call \method{transfercmd()} without a \var{rest} argument. \end{methoddesc} -\begin{methoddesc}{ntransfercmd}{cmd\optional{, rest}} +\begin{methoddesc}[FTP]{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 @@ -218,14 +227,14 @@ size. \var{cmd} and \var{rest} means the same thing as in \method{transfercmd()}. \end{methoddesc} -\begin{methoddesc}{nlst}{argument\optional{, \ldots}} +\begin{methoddesc}[FTP]{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}} +\begin{methoddesc}[FTP]{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 @@ -235,41 +244,41 @@ command. If the last argument is a function, it is used as a prints to \code{sys.stdout}. This method returns \code{None}. \end{methoddesc} -\begin{methoddesc}{rename}{fromname, toname} +\begin{methoddesc}[FTP]{rename}{fromname, toname} Rename file \var{fromname} on the server to \var{toname}. \end{methoddesc} -\begin{methoddesc}{delete}{filename} +\begin{methoddesc}[FTP]{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} +\begin{methoddesc}[FTP]{cwd}{pathname} Set the current directory on the server. \end{methoddesc} -\begin{methoddesc}{mkd}{pathname} +\begin{methoddesc}[FTP]{mkd}{pathname} Create a new directory on the server. \end{methoddesc} -\begin{methoddesc}{pwd}{} +\begin{methoddesc}[FTP]{pwd}{} Return the pathname of the current directory on the server. \end{methoddesc} -\begin{methoddesc}{rmd}{dirname} +\begin{methoddesc}[FTP]{rmd}{dirname} Remove the directory named \var{dirname} on the server. \end{methoddesc} -\begin{methoddesc}{size}{filename} +\begin{methoddesc}[FTP]{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}{} +\begin{methoddesc}[FTP]{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 @@ -278,7 +287,7 @@ method which renders the \class{FTP} instance useless for subsequent calls (see below). \end{methoddesc} -\begin{methoddesc}{close}{} +\begin{methoddesc}[FTP]{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 |