From 1b91cdae97831ba1ac670bae2134ca164576ed9e Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Fri, 24 Mar 1995 15:56:02 +0000 Subject: [PATCH] completed nntp docs --- Doc/lib/libnntplib.tex | 170 +++++++++++++++++++++++++++++++++++++++-- Doc/libnntplib.tex | 170 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 328 insertions(+), 12 deletions(-) diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex index e5ee97de2ed..d2db0d54d00 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 e5ee97de2ed..d2db0d54d00 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}