completed nntp docs
This commit is contained in:
Guido van Rossum
parent
e375b3f1e5
commit
1b91cdae97
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
Loading…
Reference in New Issue