\section{\module{nntplib} ---
         NNTP protocol client.}
\declaremodule{standard}{nntplib}

\modulesynopsis{NNTP protocol client (requires sockets).}

\indexii{NNTP}{protocol}
\index{Network News Transfer Protocol}


This module defines the class \class{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}.

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}
%
The module itself defines the following items:

\begin{classdesc}{NNTP}{host\optional{, port}}
Return a new instance of the \class{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{classdesc}

\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}
\label{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.


\begin{methoddesc}{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{methoddesc}

\begin{methoddesc}{set_debuglevel}{level}
Set the instance's debugging level.  This controls the amount of
debugging output printed.  The default, \code{0}, produces no debugging
output.  A value of \code{1} produces a moderate amount of debugging
output, generally a single line per request or response.  A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the connection (including
message text).
\end{methoddesc}

\begin{methoddesc}{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{methoddesc}

\begin{methoddesc}{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
\method{newgroups()}.  Return a pair \code{(\var{response},
\var{articles})} where \var{articles} is a list of article ids.
\end{methoddesc}

\begin{methoddesc}{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{methoddesc}

\begin{methoddesc}{group}{name}
Send a \samp{GROUP} command, where \var{name} is the group name.
Return a tuple \code{(}\var{response}\code{,} \var{count}\code{,}
\var{first}\code{,} \var{last}\code{,} \var{name}\code{)} 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{methoddesc}

\begin{methoddesc}{help}{}
Send a \samp{HELP} command.  Return a pair \code{(\var{response},
\var{list})} where \var{list} is a list of help strings.
\end{methoddesc}

\begin{methoddesc}{stat}{id}
Send a \samp{STAT} command, where \var{id} is the message id (enclosed
in \character{<} and \character{>}) 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 \character{<} and \character{>}).
\end{methoddesc}

\begin{methoddesc}{next}{}
Send a \samp{NEXT} command.  Return as for \method{stat()}.
\end{methoddesc}

\begin{methoddesc}{last}{}
Send a \samp{LAST} command.  Return as for \method{stat()}.
\end{methoddesc}

\begin{methoddesc}{head}{id}
Send a \samp{HEAD} command, where \var{id} has the same meaning as for
\method{stat()}.  Return a tuple
\code{(\var{response}, \var{number}, \var{id}, \var{list})}
where the first three are the same as for \method{stat()},
and \var{list} is a list of the article's headers (an uninterpreted
list of lines, without trailing newlines).
\end{methoddesc}

\begin{methoddesc}{body}{id}
Send a \samp{BODY} command, where \var{id} has the same meaning as for
\method{stat()}.  Return as for \method{head()}.
\end{methoddesc}

\begin{methoddesc}{article}{id}
Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
for \method{stat()}.  Return as for \method{head()}.
\end{methoddesc}

\begin{methoddesc}{slave}{}
Send a \samp{SLAVE} command.  Return the server's \var{response}.
\end{methoddesc}

\begin{methoddesc}{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{methoddesc}

\begin{methoddesc}{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
\method{readline()} method.  It should be a well-formed news article,
including the required headers.  The \method{post()} method
automatically escapes lines beginning with \samp{.}.
\end{methoddesc}

\begin{methoddesc}{ihave}{id, file}
Send an \samp{IHAVE} command.  If the response is not an error, treat
\var{file} exactly as for the \method{post()} method.
\end{methoddesc}

\begin{methoddesc}{date}{}
Return a triple \code{(\var{response}, \var{date}, \var{time})},
containing the current date and time in a form suitable for the
\method{newnews()} and \method{newgroups()} methods.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{methoddesc}

\begin{methoddesc}{xgtitle}{name}
Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
\var{list})}, where \var{list} is a list of tuples containing
\code{(\var{name}, \var{title})}.
% XXX huh?  Should that be name, description?
This is an optional NNTP extension, and may not be supported by all
servers.
\end{methoddesc}

\begin{methoddesc}{xover}{start, end}
Return a pair \code{(\var{resp}, \var{list})}.  \var{list} is a list
of tuples, one for each article in the range delimited by the \var{start}
and \var{end} article numbers.  Each tuple is of the form
\code{(}\var{article number}\code{,} \var{subject}\code{,}
\var{poster}\code{,} \var{date}\code{,} \var{id}\code{,}
\var{references}\code{,} \var{size}\code{,} \var{lines}\code{)}.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{methoddesc}

\begin{methoddesc}{xpath}{id}
Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
directory path to the article with message ID \var{id}.  This is an
optional NNTP extension, and may not be supported by all servers.
\end{methoddesc}

\begin{methoddesc}{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{methoddesc}