some new material

6 files changed, 369 insertions, 11 deletions

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 4194dbf..3a25342 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -98,16 +98,16 @@ language.
 
 \input{libwww}			% WWW EXTENSIONS
 \input{libcgi}
+\input{liburllib}
+\input{libhttplib}
 \input{libftplib}
 \input{libgopherlib}
-\input{libhtmllib}
-\input{libhttplib}
-\input{libmimetools}
 \input{libnntplib}
-\input{librfc822}
-\input{libsgmllib}
-\input{liburllib}
 \input{liburlparse}
+\input{libhtmllib}
+\input{libsgmllib}
+\input{librfc822}
+\input{libmimetools}
 
 \input{libmm}			% MULTIMEDIA EXTENSIONS
 \input{libaudioop}
diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex
index f5f7ef3..f78805c 100644
--- a/Doc/lib/libftplib.tex
+++ b/Doc/lib/libftplib.tex
@@ -3,4 +3,202 @@
 
 \renewcommand{\indexsubitem}{(in module ftplib)}
 
-To be provided.
+This module defines the class \code{FTP} and a few related items.  The
+\code{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 bu the module \code{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 \code{ftplib} module:
+
+\begin{verbatim}
+>>> from ftplib import FTP
+>>> ftp = FTP('ftp.cwi.nl')   # connect to host, default port
+>>> ftp.login()               # default 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{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, 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{funcdesc}
+
+\begin{datadesc}{all_errors}
+The set of all exceptions (as a tuple) that methods of \code{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
+\code{socket.error} and \code{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}
+
+FTP instances have the following methods:
+
+\renewcommand{\indexsubitem}{(FTP object method)}
+
+\begin{funcdesc}{set_debuglevel}{level}
+Set the instance's debugging level.  This controls the amount of
+debugging output printed.  The default, 0, produces no debugging
+output.  A value of 1 produces a moderate amount of debugging output,
+generally a single line per request.  A value of 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 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 \samp{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 \samp{LOGNAME} or \samp{USER} environment
+variable) and \var{host} is the hostname as returned by
+\code{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\, 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 \var{maxblocksize} argument specifies the maximum block size
+(which may not be the actual size of the data blocks passed to
+\var{callback}).
+\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
+\code{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
+\code{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 \code{storbinary()}).  Lines are
+read until EOF from the open file object \var{file} using its
+\code{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 \code{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 \code{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
+\code{quit()}.
+\end{funcdesc}
diff --git a/Doc/lib/libgopherlib.tex b/Doc/lib/libgopherlib.tex
index eb50fdd..e94e1f9 100644
--- a/Doc/lib/libgopherlib.tex
+++ b/Doc/lib/libgopherlib.tex
@@ -3,4 +3,28 @@
 
 \renewcommand{\indexsubitem}{(in module gopherlib)}
 
-To be provided.
+This module provides a minimal implementation of client side of the
+the Gopher protocol.  It is used by the module \code{urllib} to handle
+URLs that use the Gopher protocol.
+
+The module defines the following functions:
+
+\begin{funcdesc}{send_selector}{selector\, host\optional{\, port}}
+Send a \var{selector} string to the gopher server at \var{host} and
+\var{port} (default 70).  Return an open file object from which the
+returned document can be read.
+\end{funcdesc}
+
+\begin{funcdesc}{send_query}{selector\, query\, host\optional{\, port}}
+Send a \var{selector} string and a \var{query} string to a gopher
+server at \var{host} and \var{port} (default 70).  Return an open file
+object from which the returned document can be read.
+\end{funcdesc}
+
+Note that the data returned by the Gopher server can be of any type,
+depending on the first character of the selector string.  If the data
+is text (first character of the selector is \samp{0}), lines are
+terminated by CRLF, and the data is terminated by a line consisting of
+a single \samp{.}, and a leading \samp{.} should be stripped from
+lines that begin with \samp{..}.  Directory listings (first charactger
+of the selector is \samp{1}) are transferred using the same protocol.
diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex
index 361e0d0..03f9247 100644
--- a/Doc/lib/libmimetools.tex
+++ b/Doc/lib/libmimetools.tex
@@ -3,4 +3,94 @@
 
 \renewcommand{\indexsubitem}{(in module mimetools)}
 
-To be provided.
+This module defines a subclass of the class \code{rfc822.Message} and
+a number of utility functions that are useful for the manipulation for
+MIME style multipart or encoded message.
+
+It defines the following items:
+
+\begin{funcdesc}{Message}{fp}
+Return a new instance of the \code{mimetools.Message} class.  This is
+a subclass of the \code{rfc822.Message} class, with some additional
+methods (see below).
+\end{funcdesc}
+
+\begin{funcdesc}{choose_boundary}{}
+Return a unique string that has a high likelihood of being usable as a
+part boundary.  The string has the form
+\code{"\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}"}.
+\end{funcdesc}
+
+\begin{funcdesc}{decode}{input\, output\, encoding}
+Read data encoded using the allowed MIME \var{encoding} from open file
+object \var{input} and write the decoded data to open file object
+\var{output}.  Valid values for \var{encoding} include
+\code{"base64"}, \code{"quoted-printable"} and \code{"uuencode"}.
+\end{funcdesc}
+
+\begin{funcdesc}{encode}{input\, output\, encoding}
+Read data from open file object \var{input} and write it encoded using
+the allowed MIME \var{encoding} to open file object \var{output}.
+Valid values for \var{encoding} are the same as for \code{decode()}.
+\end{funcdesc}
+
+\begin{funcdesc}{copyliteral}{input\, output}
+Read lines until EOF from open file \var{input} and write them to open
+file \var{output}.
+\end{funcdesc}
+
+\begin{funcdesc}{copybinary}{input\, output}
+Read blocks until EOF from open file \var{input} and write them to open
+file \var{output}.  The block size is currently fixed at 8192.
+\end{funcdesc}
+
+
+\subsection{Additional Methods of \sectcode{Message} objects}
+\nodename{mimetools.Message Methods}
+
+The \code{mimetools.Message} class defines the following methods in
+addition to the \code{rfc822.Message} class:
+
+\renewcommand{\indexsubitem}{(mimetool.Message method)}
+
+\begin{funcdesc}{getplist}{}
+Return the parameter list of the \code{Content-type} header.  This is
+a list if strings.  For parameters of the form
+\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
+\var{value} is not.  For example, if the message contains the header
+\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
+\code{getplist()} will return the Python list \code{['spam=1',
+'spam=2', 'Spam']}.
+\end{funcdesc}
+
+\begin{funcdesc}{getparam}{name}
+Return the \var{value} of the first parameter (as returned by
+\code{getplist()} of the form \samp{\var{name}=\var{value}} for the
+given \var{name}.  If \var{value} is surrounded by quotes of the form
+\var{<...>} or \var{"..."}, these are removed.
+\end{funcdesc}
+
+\begin{funcdesc}{getencoding}{}
+Return the encoding specified in the \samp{Content-transfer-encoding}
+message header.  If no such header exists, return \code{"7bit"}.  The
+encoding is converted to lower case.
+\end{funcdesc}
+
+\begin{funcdesc}{gettype}{}
+Return the message type (of the form \samp{\var{type}/var{subtype}})
+as specified in the \samp{Content-type} header.  If no such header
+exists, return \code{"text/plain"}.  The type is converted to lower
+case.
+\end{funcdesc}
+
+\begin{funcdesc}{getmaintype}{}
+Return the main type as specified in the \samp{Content-type} header.
+If no such header exists, return \code{"text"}.  The main type is
+converted to lower case.
+\end{funcdesc}
+
+\begin{funcdesc}{getsubtype}{}
+Return the subtype as specified in the \samp{Content-type} header.  If
+no such header exists, return \code{"plain"}.  The subtype is
+converted to lower case.
+\end{funcdesc}
diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
index b1a891d..e5ee97d 100644
--- a/Doc/lib/libnntplib.tex
+++ b/Doc/lib/libnntplib.tex
@@ -3,4 +3,50 @@
 
 \renewcommand{\indexsubitem}{(in module nntplib)}
 
-To be provided.
+This module defines the class \code{NNTP} which implements the client
+side of the NNTP protocol.  It can be used to implement a news reader
+or poster, or automated news processors.  For more information on NNTP
+(Network News Transfer Protocol), see Internet RFC 977.
+
+Due to time constraints, the documentation for this module could not
+be completed for this release of the Python documentation.  Here are
+two small examples of how it can be used.
+
+To list some statistics about a newsgroup and print the subjects of
+the last 10 articles:
+
+\begin{verbatim}
+>>> s = NNTP('news.cwi.nl')
+>>> resp, count, first, last, name = s.group('comp.lang.python')
+>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
+Group comp.lang.python has 59 articles, range 3742 to 3803
+>>> resp, subs = s.xhdr('subject', first + '-' + last)
+>>> for id, sub in subs[-10:]: print id, sub
+... 
+3792 Re: Removing elements from a list while iterating...
+3793 Re: Who likes Info files?
+3794 Emacs and doc strings
+3795 a few questions about the Mac implementation
+3796 Re: executable python scripts
+3797 Re: executable python scripts
+3798 Re: a few questions about the Mac implementation 
+3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
+3802 Re: executable python scripts 
+3803 Re: POSIX wait and SIGCHLD
+>>> s.quit()
+'205 news.cwi.nl closing connection.  Goodbye.'
+>>> 
+\end{verbatim}
+
+To post an article from a file (this assumes that the article has
+valid headers):
+
+\begin{verbatim}
+>>> s = NNTP('news.cwi.nl')
+>>> f = open('/tmp/article')
+>>> s.post(f)
+'240 Article posted successfully.'
+>>> s.quit()
+'205 news.cwi.nl closing connection.  Goodbye.'
+>>> 
+\end{verbatim}
diff --git a/Doc/lib/libprofile.tex b/Doc/lib/libprofile.tex
index ecf41c3..3cd4296 100644
--- a/Doc/lib/libprofile.tex
+++ b/Doc/lib/libprofile.tex
@@ -500,7 +500,7 @@ that it relies on the Python interpreter to dispatch \dfn{call},
 \dfn{return}, and \dfn{exception} events.  Compiled C code does not
 get interpreted, and hence is ``invisible'' to the profiler.  All time
 spent in C code (including builtin functions) will be charged to the
-Python function that was invoked the C code.  If the C code calls out
+Python function that invoked the C code.  If the C code calls out
 to some native Python code, then those calls will be profiled
 properly.