completed nntp docs

2 files changed, 328 insertions, 12 deletions

diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
index e5ee97d..d2db0d5 100644
--- a/Doc/lib/libnntplib.tex
+++ b/Doc/lib/libnntplib.tex
@@ -8,12 +8,9 @@ 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:
+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')
@@ -50,3 +47,164 @@ valid headers):
 '205 news.cwi.nl closing connection.  Goodbye.'
 >>> 
 \end{verbatim}
+
+The module itself defines the following items:
+
+\begin{funcdesc}{NNTP}{host\optional{\, port}}
+Return a new instance of the \code{NNTP} class, representing a
+connection to the NNTP server running on host \var{host}, listening at
+port \var{port}.  The default \var{port} is 119.
+\end{funcdesc}
+
+\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{NNTP Objects}
+
+NNTP instances have the following methods.  The \var{response} that is
+returned as the first item in the return tuple of almost all methods
+is the server's response: a string beginning with a three-digit code.
+If the server's response indicates an error, the method raises one of
+the above exceptions.
+
+\renewcommand{\indexsubitem}{(NNTP object method)}
+
+\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}{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 or response.  A value of 2 or
+higher produces the maximum amount of debugging output, logging each
+line sent and received on the connection (including message text).
+\end{funcdesc}
+
+\begin{funcdesc}{newgroups}{date\, time}
+Send a \samp{NEWGROUPS} command.  The \var{date} argument should be a
+string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
+date, and \var{time} should be a string of the form
+\code{"\var{hh}\var{mm}\var{ss}"} indicating the time.  Return a pair
+\code{(\var{response}, \var{groups})} where \var{groups} is a list of
+group names that are new since the given date and time.
+\end{funcdesc}
+
+\begin{funcdesc}{newnews}{group\, date\, time}
+Send a \samp{NEWNEWS} command.  Here, \var{group} is a group name or
+\code{"*"}, and \var{date} and \var{time} have the same meaning as for
+\code{newgroups()}.  Return a pair \code{(\var{response},
+\var{articles})} where \var{articles} is a list of article ids.
+\end{funcdesc}
+
+\begin{funcdesc}{list}{}
+Send a \samp{LIST} command.  Return a pair \code{(\var{response},
+\var{list})} where \var{list} is a list of tuples.  Each tuple has the
+form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
+\var{group} is a group name, \var{last} and \var{first} are the last
+and first article numbers (as strings), and \var{flag} is \code{'y'}
+if posting is allowed, \code{'n'} if not, and \code{'m'} if the
+newsgroup is moderated.  (Note the ordering: \var{last}, \var{first}.)
+\end{funcdesc}
+
+\begin{funcdesc}{group}{name}
+Send a \samp{GROUP} command, where \var{name} is the group name.
+Return a tuple \code{(\var{response}, \var{count}, \var{first},
+\var{last}, \var{name})} where \var{count} is the (estimated) number
+of articles in the group, \var{first} is the first article number in
+the group, \var{last} is the last article number in the group, and
+\var{name} is the group name.  The numbers are returned as strings.
+\end{funcdesc}
+
+\begin{funcdesc}{help}{}
+Send a \samp{HELP} command.  Return a pair \code{(\var{response},
+\var{list})} where \var{list} is a list of help strings.
+\end{funcdesc}
+
+\begin{funcdesc}{stat}{id}
+Send a \samp{STAT} command, where \var{id} is the message id (enclosed
+in \samp{<} and \samp{>}) or an article number (as a string).
+Return a triple \code{(var{response}, \var{number}, \var{id})} where
+\var{number} is the article number (as a string) and \var{id} is the
+article id  (enclosed in \samp{<} and \samp{>}).
+\end{funcdesc}
+
+\begin{funcdesc}{next}{}
+Send a \samp{NEXT} command.  Return as for \code{stat()}.
+\end{funcdesc}
+
+\begin{funcdesc}{last}{}
+Send a \samp{LAST} command.  Return as for \code{stat()}.
+\end{funcdesc}
+
+\begin{funcdesc}{head}{id}
+Send a \samp{HEAD} command, where \var{id} has the same meaning as for
+\code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
+where \var{list} is a list of the article's headers (an uninterpreted
+list of lines, without trailing newlines).
+\end{funcdesc}
+
+\begin{funcdesc}{body}{id}
+Send a \samp{BODY} command, where \var{id} has the same meaning as for
+\code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
+where \var{list} is a list of the article's body text (an
+uninterpreted list of lines, without trailing newlines).
+\end{funcdesc}
+
+\begin{funcdesc}{article}{id}
+Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
+for \code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
+where \var{list} is a list of the article's header and body text (an
+uninterpreted list of lines, without trailing newlines).
+\end{funcdesc}
+
+\begin{funcdesc}{slave}{}
+Send a \samp{SLAVE} command.  Return the server's \var{response}.
+\end{funcdesc}
+
+\begin{funcdesc}{xhdr}{header\, string}
+Send an \samp{XHDR} command.  This command is not defined in the RFC
+but is a common extension.  The \var{header} argument is a header
+keyword, e.g. \code{"subject"}.  The \var{string} argument should have
+the form \code{"\var{first}-\var{last}"} where \var{first} and
+\var{last} are the first and last article numbers to search.  Return a
+pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
+pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
+(as a string) and \var{text} is the text of the requested header for
+that article.
+\end{funcdesc}
+
+\begin{funcdesc}{post}{file}
+Post an article using the \samp{POST} command.  The \var{file}
+argument is an open file object which is read until EOF using its
+\code{readline()} method.  It should be a well-formed news article,
+including the required headers.  The \code{post()} method
+automatically escapes lines beginning with \samp{.}.
+\end{funcdesc}
+
+\begin{funcdesc}{ihave}{id\, file}
+Send an \samp{IHAVE} command.  If the response is not an error, treat
+\var{file} exactly as for the \code{post()} method.
+\end{funcdesc}
+
+\begin{funcdesc}{quit}{}
+Send a \samp{QUIT} command and close the connection.  Once this method
+has been called, no other methods of the NNTP object should be called.
+\end{funcdesc}
diff --git a/Doc/libnntplib.tex b/Doc/libnntplib.tex
index e5ee97d..d2db0d5 100644
--- a/Doc/libnntplib.tex
+++ b/Doc/libnntplib.tex
@@ -8,12 +8,9 @@ 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:
+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')
@@ -50,3 +47,164 @@ valid headers):
 '205 news.cwi.nl closing connection.  Goodbye.'
 >>> 
 \end{verbatim}
+
+The module itself defines the following items:
+
+\begin{funcdesc}{NNTP}{host\optional{\, port}}
+Return a new instance of the \code{NNTP} class, representing a
+connection to the NNTP server running on host \var{host}, listening at
+port \var{port}.  The default \var{port} is 119.
+\end{funcdesc}
+
+\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{NNTP Objects}
+
+NNTP instances have the following methods.  The \var{response} that is
+returned as the first item in the return tuple of almost all methods
+is the server's response: a string beginning with a three-digit code.
+If the server's response indicates an error, the method raises one of
+the above exceptions.
+
+\renewcommand{\indexsubitem}{(NNTP object method)}
+
+\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}{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 or response.  A value of 2 or
+higher produces the maximum amount of debugging output, logging each
+line sent and received on the connection (including message text).
+\end{funcdesc}
+
+\begin{funcdesc}{newgroups}{date\, time}
+Send a \samp{NEWGROUPS} command.  The \var{date} argument should be a
+string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
+date, and \var{time} should be a string of the form
+\code{"\var{hh}\var{mm}\var{ss}"} indicating the time.  Return a pair
+\code{(\var{response}, \var{groups})} where \var{groups} is a list of
+group names that are new since the given date and time.
+\end{funcdesc}
+
+\begin{funcdesc}{newnews}{group\, date\, time}
+Send a \samp{NEWNEWS} command.  Here, \var{group} is a group name or
+\code{"*"}, and \var{date} and \var{time} have the same meaning as for
+\code{newgroups()}.  Return a pair \code{(\var{response},
+\var{articles})} where \var{articles} is a list of article ids.
+\end{funcdesc}
+
+\begin{funcdesc}{list}{}
+Send a \samp{LIST} command.  Return a pair \code{(\var{response},
+\var{list})} where \var{list} is a list of tuples.  Each tuple has the
+form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
+\var{group} is a group name, \var{last} and \var{first} are the last
+and first article numbers (as strings), and \var{flag} is \code{'y'}
+if posting is allowed, \code{'n'} if not, and \code{'m'} if the
+newsgroup is moderated.  (Note the ordering: \var{last}, \var{first}.)
+\end{funcdesc}
+
+\begin{funcdesc}{group}{name}
+Send a \samp{GROUP} command, where \var{name} is the group name.
+Return a tuple \code{(\var{response}, \var{count}, \var{first},
+\var{last}, \var{name})} where \var{count} is the (estimated) number
+of articles in the group, \var{first} is the first article number in
+the group, \var{last} is the last article number in the group, and
+\var{name} is the group name.  The numbers are returned as strings.
+\end{funcdesc}
+
+\begin{funcdesc}{help}{}
+Send a \samp{HELP} command.  Return a pair \code{(\var{response},
+\var{list})} where \var{list} is a list of help strings.
+\end{funcdesc}
+
+\begin{funcdesc}{stat}{id}
+Send a \samp{STAT} command, where \var{id} is the message id (enclosed
+in \samp{<} and \samp{>}) or an article number (as a string).
+Return a triple \code{(var{response}, \var{number}, \var{id})} where
+\var{number} is the article number (as a string) and \var{id} is the
+article id  (enclosed in \samp{<} and \samp{>}).
+\end{funcdesc}
+
+\begin{funcdesc}{next}{}
+Send a \samp{NEXT} command.  Return as for \code{stat()}.
+\end{funcdesc}
+
+\begin{funcdesc}{last}{}
+Send a \samp{LAST} command.  Return as for \code{stat()}.
+\end{funcdesc}
+
+\begin{funcdesc}{head}{id}
+Send a \samp{HEAD} command, where \var{id} has the same meaning as for
+\code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
+where \var{list} is a list of the article's headers (an uninterpreted
+list of lines, without trailing newlines).
+\end{funcdesc}
+
+\begin{funcdesc}{body}{id}
+Send a \samp{BODY} command, where \var{id} has the same meaning as for
+\code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
+where \var{list} is a list of the article's body text (an
+uninterpreted list of lines, without trailing newlines).
+\end{funcdesc}
+
+\begin{funcdesc}{article}{id}
+Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
+for \code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
+where \var{list} is a list of the article's header and body text (an
+uninterpreted list of lines, without trailing newlines).
+\end{funcdesc}
+
+\begin{funcdesc}{slave}{}
+Send a \samp{SLAVE} command.  Return the server's \var{response}.
+\end{funcdesc}
+
+\begin{funcdesc}{xhdr}{header\, string}
+Send an \samp{XHDR} command.  This command is not defined in the RFC
+but is a common extension.  The \var{header} argument is a header
+keyword, e.g. \code{"subject"}.  The \var{string} argument should have
+the form \code{"\var{first}-\var{last}"} where \var{first} and
+\var{last} are the first and last article numbers to search.  Return a
+pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
+pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
+(as a string) and \var{text} is the text of the requested header for
+that article.
+\end{funcdesc}
+
+\begin{funcdesc}{post}{file}
+Post an article using the \samp{POST} command.  The \var{file}
+argument is an open file object which is read until EOF using its
+\code{readline()} method.  It should be a well-formed news article,
+including the required headers.  The \code{post()} method
+automatically escapes lines beginning with \samp{.}.
+\end{funcdesc}
+
+\begin{funcdesc}{ihave}{id\, file}
+Send an \samp{IHAVE} command.  If the response is not an error, treat
+\var{file} exactly as for the \code{post()} method.
+\end{funcdesc}
+
+\begin{funcdesc}{quit}{}
+Send a \samp{QUIT} command and close the connection.  Once this method
+has been called, no other methods of the NNTP object should be called.
+\end{funcdesc}