Logical markup.

This commit is contained in:
Fred Drake 1998-03-12 06:04:53 +00:00
parent a2e9818467
commit 6a1eefe535
2 changed files with 80 additions and 82 deletions

View file

@ -3,16 +3,15 @@
\stmodindex{ftplib} \stmodindex{ftplib}
\indexii{FTP}{protocol} \indexii{FTP}{protocol}
\setindexsubitem{(in module ftplib)}
This module defines the class \code{FTP} and a few related items. The This module defines the class \class{FTP} and a few related items. The
\code{FTP} class implements the client side of the FTP protocol. You \class{FTP} class implements the client side of the FTP protocol. You
can use this to write Python programs that perform a variety of can use this to write Python programs that perform a variety of
automated FTP jobs, such as mirroring other ftp servers. It is also automated FTP jobs, such as mirroring other ftp servers. It is also
used by the module \code{urllib} to handle URLs that use FTP. For used by the module \module{urllib} to handle URLs that use FTP. For
more information on FTP (File Transfer Protocol), see Internet \rfc{959}. more information on FTP (File Transfer Protocol), see Internet \rfc{959}.
Here's a sample session using the \code{ftplib} module: Here's a sample session using the \module{ftplib} module:
\begin{verbatim} \begin{verbatim}
>>> from ftplib import FTP >>> from ftplib import FTP
@ -28,23 +27,23 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
. .
>>> ftp.quit() >>> ftp.quit()
\end{verbatim} \end{verbatim}
%
The module defines the following items: The module defines the following items:
\begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}} \begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, passwd\optional{, acct}}}}}
Return a new instance of the \code{FTP} class. When Return a new instance of the \code{FTP} class. When
\var{host} is given, the method call \code{connect(\var{host})} is \var{host} is given, the method call \code{connect(\var{host})} is
made. When \var{user} is given, additionally the method call made. When \var{user} is given, additionally the method call
\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where \code{login(\var{user}, \var{passwd}, \var{acct})} is made (where
\var{passwd} and \var{acct} default to the empty string when not given). \var{passwd} and \var{acct} default to the empty string when not given).
\end{funcdesc} \end{classdesc}
\begin{datadesc}{all_errors} \begin{datadesc}{all_errors}
The set of all exceptions (as a tuple) that methods of \code{FTP} 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 instances may raise as a result of problems with the FTP connection
(as opposed to programming errors made by the caller). This set (as opposed to programming errors made by the caller). This set
includes the four exceptions listed below as well as includes the four exceptions listed below as well as
\code{socket.error} and \code{IOError}. \exception{socket.error} and \exception{IOError}.
\end{datadesc} \end{datadesc}
\begin{excdesc}{error_reply} \begin{excdesc}{error_reply}
@ -66,21 +65,21 @@ not begin with a digit in the range 1--5.
\subsection{FTP Objects} \subsection{FTP Objects}
FTP instances have the following methods: \class{FTP} instances have the following methods:
\setindexsubitem{(FTP object method)} \setindexsubitem{(FTP method)}
\begin{funcdesc}{set_debuglevel}{level} \begin{funcdesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of Set the instance's debugging level. This controls the amount of
debugging output printed. The default, 0, produces no debugging debugging output printed. The default, \code{0}, produces no
output. A value of 1 produces a moderate amount of debugging output, debugging output. A value of \code{1} produces a moderate amount of
generally a single line per request. A value of 2 or higher produces debugging output, generally a single line per request. A value of
the maximum amount of debugging output, logging each line sent and \code{2} or higher produces the maximum amount of debugging output,
received on the control connection. logging each line sent and received on the control connection.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{connect}{host\optional{\, port}} \begin{funcdesc}{connect}{host\optional{, port}}
Connect to the given host and port. The default port number is 21, as 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 specified by the FTP protocol specification. It is rarely needed to
specify a different port number. This function should be called only 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 once for each instance; it should not be called at all if a host was
@ -94,15 +93,15 @@ connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.) information that may be relevant to the user.)
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{login}{\optional{user\optional{\, passwd\optional{\, acct}}}} \begin{funcdesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
Log in as the given \var{user}. The \var{passwd} and \var{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 parameters are optional and default to the empty string. If no
\var{user} is specified, it defaults to \samp{anonymous}. If \var{user} is specified, it defaults to \code{'anonymous'}. If
\var{user} is \code{anonymous}, the default \var{passwd} is \var{user} is \code{anonymous}, the default \var{passwd} is
\samp{\var{realuser}@\var{host}} where \var{realuser} is the real user \samp{\var{realuser}@\var{host}} where \var{realuser} is the real user
name (glanced from the \samp{LOGNAME} or \samp{USER} environment name (glanced from the \envvar{LOGNAME} or \envvar{USER} environment
variable) and \var{host} is the hostname as returned by variable) and \var{host} is the hostname as returned by
\code{socket.gethostname()}. This function should be called only \function{socket.gethostname()}. This function should be called only
once for each instance, after a connection has been established; it 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 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 instance was created. Most FTP commands are only allowed after the
@ -125,9 +124,9 @@ Return nothing if a response code in the range 200--299 is received.
Raise an exception otherwise. Raise an exception otherwise.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{retrbinary}{command\, callback\optional{\, maxblocksize}} \begin{funcdesc}{retrbinary}{command, callback\optional{, maxblocksize}}
Retrieve a file in binary transfer mode. \var{command} should be an Retrieve a file in binary transfer mode. \var{command} should be an
appropriate \samp{RETR} command, i.e.\ \code{"RETR \var{filename}"}. appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}.
The \var{callback} function is called for each block of data received, The \var{callback} function is called for each block of data received,
with a single string argument giving the data block. with a single string argument giving the data block.
The optional \var{maxblocksize} argument specifies the maximum chunk size to The optional \var{maxblocksize} argument specifies the maximum chunk size to
@ -136,47 +135,47 @@ read on the low-level socket object created to do the actual transfer
\var{callback}). A reasonable default is chosen. \var{callback}). A reasonable default is chosen.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{retrlines}{command\optional{\, callback}} \begin{funcdesc}{retrlines}{command\optional{, callback}}
Retrieve a file or directory listing in \ASCII{} transfer mode. Retrieve a file or directory listing in \ASCII{} transfer mode.
\var{command} should be an appropriate \samp{RETR} command (see \var{command} should be an appropriate \samp{RETR} command (see
\code{retrbinary()} or a \samp{LIST} command (usually just the string \method{retrbinary()} or a \samp{LIST} command (usually just the string
\code{"LIST"}). The \var{callback} function is called for each line, \code{'LIST'}). The \var{callback} function is called for each line,
with the trailing CRLF stripped. The default \var{callback} prints with the trailing CRLF stripped. The default \var{callback} prints
the line to \code{sys.stdout}. the line to \code{sys.stdout}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{storbinary}{command\, file\, blocksize} \begin{funcdesc}{storbinary}{command, file, blocksize}
Store a file in binary transfer mode. \var{command} should be an Store a file in binary transfer mode. \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
\var{file} is an open file object which is read until EOF using its \var{file} is an open file object which is read until \EOF{} using its
\code{read()} method in blocks of size \var{blocksize} to provide the \method{read()} method in blocks of size \var{blocksize} to provide the
data to be stored. data to be stored.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{storlines}{command\, file} \begin{funcdesc}{storlines}{command, file}
Store a file in \ASCII{} transfer mode. \var{command} should be an Store a file in \ASCII{} transfer mode. \var{command} should be an
appropriate \samp{STOR} command (see \code{storbinary()}). Lines are appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
read until EOF from the open file object \var{file} using its read until \EOF{} from the open file object \var{file} using its
\code{readline()} method to privide the data to be stored. \method{readline()} method to privide the data to be stored.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{nlst}{argument\optional{\, \ldots}} \begin{funcdesc}{nlst}{argument\optional{, \ldots}}
Return a list of files as returned by the \samp{NLST} command. The 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 optional \var{argument} is a directory to list (default is the current
server directory). Multiple arguments can be used to pass server directory). Multiple arguments can be used to pass
non-standard options to the \samp{NLST} command. non-standard options to the \samp{NLST} command.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{dir}{argument\optional{\, \ldots}} \begin{funcdesc}{dir}{argument\optional{, \ldots}}
Return a directory listing as returned by the \samp{LIST} command, as 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 a list of lines. The optional \var{argument} is a directory to list
(default is the current server directory). Multiple arguments can be (default is the current server directory). Multiple arguments can be
used to pass non-standard options to the \samp{LIST} command. If the 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 last argument is a function, it is used as a \var{callback} function
as for \code{retrlines()}. as for \method{retrlines()}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{rename}{fromname\, toname} \begin{funcdesc}{rename}{fromname, toname}
Rename file \var{fromname} on the server to \var{toname}. Rename file \var{fromname} on the server to \var{toname}.
\end{funcdesc} \end{funcdesc}
@ -195,12 +194,12 @@ Return the pathname of the current directory on the server.
\begin{funcdesc}{quit}{} \begin{funcdesc}{quit}{}
Send a \samp{QUIT} command to the server and close the connection. 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 This is the ``polite'' way to close a connection, but it may raise an
exception of the server reponds with an error to the \code{QUIT} exception of the server reponds with an error to the \samp{QUIT}
command. command.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{close}{} \begin{funcdesc}{close}{}
Close the connection unilaterally. This should not be applied to an Close the connection unilaterally. This should not be applied to an
already closed connection (e.g.\ after a successful call to already closed connection (e.g.\ after a successful call to
\code{quit()}. \method{quit()}.
\end{funcdesc} \end{funcdesc}

View file

@ -3,16 +3,15 @@
\stmodindex{ftplib} \stmodindex{ftplib}
\indexii{FTP}{protocol} \indexii{FTP}{protocol}
\setindexsubitem{(in module ftplib)}
This module defines the class \code{FTP} and a few related items. The This module defines the class \class{FTP} and a few related items. The
\code{FTP} class implements the client side of the FTP protocol. You \class{FTP} class implements the client side of the FTP protocol. You
can use this to write Python programs that perform a variety of can use this to write Python programs that perform a variety of
automated FTP jobs, such as mirroring other ftp servers. It is also automated FTP jobs, such as mirroring other ftp servers. It is also
used by the module \code{urllib} to handle URLs that use FTP. For used by the module \module{urllib} to handle URLs that use FTP. For
more information on FTP (File Transfer Protocol), see Internet \rfc{959}. more information on FTP (File Transfer Protocol), see Internet \rfc{959}.
Here's a sample session using the \code{ftplib} module: Here's a sample session using the \module{ftplib} module:
\begin{verbatim} \begin{verbatim}
>>> from ftplib import FTP >>> from ftplib import FTP
@ -28,23 +27,23 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
. .
>>> ftp.quit() >>> ftp.quit()
\end{verbatim} \end{verbatim}
%
The module defines the following items: The module defines the following items:
\begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}} \begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, passwd\optional{, acct}}}}}
Return a new instance of the \code{FTP} class. When Return a new instance of the \code{FTP} class. When
\var{host} is given, the method call \code{connect(\var{host})} is \var{host} is given, the method call \code{connect(\var{host})} is
made. When \var{user} is given, additionally the method call made. When \var{user} is given, additionally the method call
\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where \code{login(\var{user}, \var{passwd}, \var{acct})} is made (where
\var{passwd} and \var{acct} default to the empty string when not given). \var{passwd} and \var{acct} default to the empty string when not given).
\end{funcdesc} \end{classdesc}
\begin{datadesc}{all_errors} \begin{datadesc}{all_errors}
The set of all exceptions (as a tuple) that methods of \code{FTP} 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 instances may raise as a result of problems with the FTP connection
(as opposed to programming errors made by the caller). This set (as opposed to programming errors made by the caller). This set
includes the four exceptions listed below as well as includes the four exceptions listed below as well as
\code{socket.error} and \code{IOError}. \exception{socket.error} and \exception{IOError}.
\end{datadesc} \end{datadesc}
\begin{excdesc}{error_reply} \begin{excdesc}{error_reply}
@ -66,21 +65,21 @@ not begin with a digit in the range 1--5.
\subsection{FTP Objects} \subsection{FTP Objects}
FTP instances have the following methods: \class{FTP} instances have the following methods:
\setindexsubitem{(FTP object method)} \setindexsubitem{(FTP method)}
\begin{funcdesc}{set_debuglevel}{level} \begin{funcdesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of Set the instance's debugging level. This controls the amount of
debugging output printed. The default, 0, produces no debugging debugging output printed. The default, \code{0}, produces no
output. A value of 1 produces a moderate amount of debugging output, debugging output. A value of \code{1} produces a moderate amount of
generally a single line per request. A value of 2 or higher produces debugging output, generally a single line per request. A value of
the maximum amount of debugging output, logging each line sent and \code{2} or higher produces the maximum amount of debugging output,
received on the control connection. logging each line sent and received on the control connection.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{connect}{host\optional{\, port}} \begin{funcdesc}{connect}{host\optional{, port}}
Connect to the given host and port. The default port number is 21, as 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 specified by the FTP protocol specification. It is rarely needed to
specify a different port number. This function should be called only 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 once for each instance; it should not be called at all if a host was
@ -94,15 +93,15 @@ connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.) information that may be relevant to the user.)
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{login}{\optional{user\optional{\, passwd\optional{\, acct}}}} \begin{funcdesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
Log in as the given \var{user}. The \var{passwd} and \var{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 parameters are optional and default to the empty string. If no
\var{user} is specified, it defaults to \samp{anonymous}. If \var{user} is specified, it defaults to \code{'anonymous'}. If
\var{user} is \code{anonymous}, the default \var{passwd} is \var{user} is \code{anonymous}, the default \var{passwd} is
\samp{\var{realuser}@\var{host}} where \var{realuser} is the real user \samp{\var{realuser}@\var{host}} where \var{realuser} is the real user
name (glanced from the \samp{LOGNAME} or \samp{USER} environment name (glanced from the \envvar{LOGNAME} or \envvar{USER} environment
variable) and \var{host} is the hostname as returned by variable) and \var{host} is the hostname as returned by
\code{socket.gethostname()}. This function should be called only \function{socket.gethostname()}. This function should be called only
once for each instance, after a connection has been established; it 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 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 instance was created. Most FTP commands are only allowed after the
@ -125,9 +124,9 @@ Return nothing if a response code in the range 200--299 is received.
Raise an exception otherwise. Raise an exception otherwise.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{retrbinary}{command\, callback\optional{\, maxblocksize}} \begin{funcdesc}{retrbinary}{command, callback\optional{, maxblocksize}}
Retrieve a file in binary transfer mode. \var{command} should be an Retrieve a file in binary transfer mode. \var{command} should be an
appropriate \samp{RETR} command, i.e.\ \code{"RETR \var{filename}"}. appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}.
The \var{callback} function is called for each block of data received, The \var{callback} function is called for each block of data received,
with a single string argument giving the data block. with a single string argument giving the data block.
The optional \var{maxblocksize} argument specifies the maximum chunk size to The optional \var{maxblocksize} argument specifies the maximum chunk size to
@ -136,47 +135,47 @@ read on the low-level socket object created to do the actual transfer
\var{callback}). A reasonable default is chosen. \var{callback}). A reasonable default is chosen.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{retrlines}{command\optional{\, callback}} \begin{funcdesc}{retrlines}{command\optional{, callback}}
Retrieve a file or directory listing in \ASCII{} transfer mode. Retrieve a file or directory listing in \ASCII{} transfer mode.
\var{command} should be an appropriate \samp{RETR} command (see \var{command} should be an appropriate \samp{RETR} command (see
\code{retrbinary()} or a \samp{LIST} command (usually just the string \method{retrbinary()} or a \samp{LIST} command (usually just the string
\code{"LIST"}). The \var{callback} function is called for each line, \code{'LIST'}). The \var{callback} function is called for each line,
with the trailing CRLF stripped. The default \var{callback} prints with the trailing CRLF stripped. The default \var{callback} prints
the line to \code{sys.stdout}. the line to \code{sys.stdout}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{storbinary}{command\, file\, blocksize} \begin{funcdesc}{storbinary}{command, file, blocksize}
Store a file in binary transfer mode. \var{command} should be an Store a file in binary transfer mode. \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
\var{file} is an open file object which is read until EOF using its \var{file} is an open file object which is read until \EOF{} using its
\code{read()} method in blocks of size \var{blocksize} to provide the \method{read()} method in blocks of size \var{blocksize} to provide the
data to be stored. data to be stored.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{storlines}{command\, file} \begin{funcdesc}{storlines}{command, file}
Store a file in \ASCII{} transfer mode. \var{command} should be an Store a file in \ASCII{} transfer mode. \var{command} should be an
appropriate \samp{STOR} command (see \code{storbinary()}). Lines are appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
read until EOF from the open file object \var{file} using its read until \EOF{} from the open file object \var{file} using its
\code{readline()} method to privide the data to be stored. \method{readline()} method to privide the data to be stored.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{nlst}{argument\optional{\, \ldots}} \begin{funcdesc}{nlst}{argument\optional{, \ldots}}
Return a list of files as returned by the \samp{NLST} command. The 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 optional \var{argument} is a directory to list (default is the current
server directory). Multiple arguments can be used to pass server directory). Multiple arguments can be used to pass
non-standard options to the \samp{NLST} command. non-standard options to the \samp{NLST} command.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{dir}{argument\optional{\, \ldots}} \begin{funcdesc}{dir}{argument\optional{, \ldots}}
Return a directory listing as returned by the \samp{LIST} command, as 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 a list of lines. The optional \var{argument} is a directory to list
(default is the current server directory). Multiple arguments can be (default is the current server directory). Multiple arguments can be
used to pass non-standard options to the \samp{LIST} command. If the 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 last argument is a function, it is used as a \var{callback} function
as for \code{retrlines()}. as for \method{retrlines()}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{rename}{fromname\, toname} \begin{funcdesc}{rename}{fromname, toname}
Rename file \var{fromname} on the server to \var{toname}. Rename file \var{fromname} on the server to \var{toname}.
\end{funcdesc} \end{funcdesc}
@ -195,12 +194,12 @@ Return the pathname of the current directory on the server.
\begin{funcdesc}{quit}{} \begin{funcdesc}{quit}{}
Send a \samp{QUIT} command to the server and close the connection. 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 This is the ``polite'' way to close a connection, but it may raise an
exception of the server reponds with an error to the \code{QUIT} exception of the server reponds with an error to the \samp{QUIT}
command. command.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{close}{} \begin{funcdesc}{close}{}
Close the connection unilaterally. This should not be applied to an Close the connection unilaterally. This should not be applied to an
already closed connection (e.g.\ after a successful call to already closed connection (e.g.\ after a successful call to
\code{quit()}. \method{quit()}.
\end{funcdesc} \end{funcdesc}