\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 clientside of the NNTP protocol.  It can be used to implement a news readeror 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 somestatistics about a newsgroup and print the subjects of the last 10articles: \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', lastGroup 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 strings3795 a few questions about the Mac implementation3796 Re: executable python scripts3797 Re: executable python scripts3798 Re: a few questions about the Mac implementation 3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules3802 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 hasvalid 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                        \optional{, user\optional{, password			\optional{, readermode}			\optional{, usenetrc}}}}}Return a new instance of the \class{NNTP} class, representing aconnection to the NNTP server running on host \var{host}, listening atport \var{port}.  The default \var{port} is 119.  If the optional\var{user} and \var{password} are provided, or if suitable credentials are present in \file{~/.netrc} and theoptional flag \var{usenetrc} is true (the default),the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used toidentify and authenticate the user to the server.  If the optionalflag \var{readermode} is true, then a \samp{mode reader} command issent before authentication is performed.  Reader mode is sometimesnecessary if you are connecting to an NNTP server on the local machineand intend to call reader-specific commands, such as \samp{group}.  Ifyou get unexpected \exception{NNTPPermanentError}s, you might need to set\var{readermode}.  \var{readermode} defaults to \code{None}.\var{usenetrc} defaults to \code{True}. \versionchanged[\var{usenetrc} argument added]{2.4}\end{classdesc} \begin{excdesc}{NNTPError}Derived from the standard exception \exception{Exception}, this is thebase class for all exceptions raised by the \module{nntplib} module.\end{excdesc} \begin{excdesc}{NNTPReplyError}Exception raised when an unexpected reply is received from theserver.  For backwards compatibility, the exception \code{error_reply}is equivalent to this class.\end{excdesc} \begin{excdesc}{NNTPTemporaryError}Exception raised when an error code in the range 400--499 isreceived.  For backwards compatibility, the exception\code{error_temp} is equivalent to this class.\end{excdesc} \begin{excdesc}{NNTPPermanentError}Exception raised when an error code in the range 500--599 isreceived.  For backwards compatibility, the exception\code{error_perm} is equivalent to this class.\end{excdesc} \begin{excdesc}{NNTPProtocolError}Exception raised when a reply is received from the server that doesnot begin with a digit in the range 1--5.  For backwardscompatibility, the exception \code{error_proto} is equivalent to thisclass.\end{excdesc} \begin{excdesc}{NNTPDataError}Exception raised when there is some error in the response data.  Forbackwards compatibility, the exception \code{error_data} isequivalent to this class.\end{excdesc}  \subsection{NNTP Objects \label{nntp-objects}} NNTP instances have the following methods.  The \var{response} that isreturned as the first item in the return tuple of almost all methodsis the server's response: a string beginning with a three-digit code.If the server's response indicates an error, the method raises one ofthe above exceptions.  \begin{methoddesc}{getwelcome}{}Return the welcome message sent by the server in reply to the initialconnection.  (This message sometimes contains disclaimers or helpinformation that may be relevant to the user.)\end{methoddesc} \begin{methoddesc}{set_debuglevel}{level}Set the instance's debugging level.  This controls the amount ofdebugging output printed.  The default, \code{0}, produces no debuggingoutput.  A value of \code{1} produces a moderate amount of debuggingoutput, 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 (includingmessage text).\end{methoddesc} \begin{methoddesc}{newgroups}{date, time, \optional{file}}Send a \samp{NEWGROUPS} command.  The \var{date} argument should be astring of the form \code{'\var{yy}\var{mm}\var{dd}'} indicating thedate, 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 ofgroup names that are new since the given date and time.If the \var{file} parameter is supplied, then the output of the \samp{NEWGROUPS} command is stored in a file.  If \var{file} is a string, then the method will open a file object with that name, write to it then close it.  If \var{file} is a file object, then it will startcalling \method{write()} on it to store the lines of the command output.If \var{file} is supplied, then the returned \var{list} is an empty list.\end{methoddesc} \begin{methoddesc}{newnews}{group, date, time, \optional{file}}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 message ids.If the \var{file} parameter is supplied, then the output of the \samp{NEWNEWS} command is stored in a file.  If \var{file} is a string, then the method will open a file object with that name, write to it then close it.  If \var{file} is a file object, then it will startcalling \method{write()} on it to store the lines of the command output.If \var{file} is supplied, then the returned \var{list} is an empty list.\end{methoddesc} \begin{methoddesc}{list}{\optional{file}}Send a \samp{LIST} command.  Return a pair \code{(\var{response},\var{list})} where \var{list} is a list of tuples.  Each tuple has theform \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where\var{group} is a group name, \var{last} and \var{first} are the lastand first article numbers (as strings), and \var{flag} is\code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} ifthe newsgroup is moderated.  (Note the ordering: \var{last},\var{first}.)If the \var{file} parameter is supplied, then the output of the \samp{LIST} command is stored in a file.  If \var{file} is a string, then the method will open a file object with that name, write to it then close it.  If \var{file} is a file object, then it will startcalling \method{write()} on it to store the lines of the command output.If \var{file} is supplied, then the returned \var{list} is an empty list.\end{methoddesc} \begin{methoddesc}{descriptions}{grouppattern}Send a \samp{LIST NEWSGROUPS} command, where \var{grouppattern} is a wildmatstring as specified in RFC2980 (it's essentially the same as DOS or UNIXshell wildcard strings).  Return a pair \code{(\var{response},\var{list})}, where \var{list} is a list of tuples containing\code{(\var{name}, \var{title})}. \versionadded{2.4}\end{methoddesc} \begin{methoddesc}{description}{group}Get a description for a single group \var{group}.  If more than one groupmatches (if 'group' is a real wildmat string), return the first match.  If no group matches, return an empty string. This elides the response code from the server.  If the response code isneeded, use \method{descriptions()}. \versionadded{2.4}\end{methoddesc} \begin{methoddesc}{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) numberof articles in the group, \var{first} is the first article number inthe 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}{\optional{file}}Send a \samp{HELP} command.  Return a pair \code{(\var{response},\var{list})} where \var{list} is a list of help strings.If the \var{file} parameter is supplied, then the output of the \samp{HELP} command is stored in a file.  If \var{file} is a string, then the method will open a file object with that name, write to it then close it.  If \var{file} is a file object, then it will startcalling \method{write()} on it to store the lines of the command output.If \var{file} is supplied, then the returned \var{list} is an empty list.\end{methoddesc} \begin{methoddesc}{stat}{id}Send a \samp{STAT} command, where \var{id} is the message id (enclosedin \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 themessage 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 uninterpretedlist of lines, without trailing newlines).\end{methoddesc} \begin{methoddesc}{body}{id,\optional{file}}Send a \samp{BODY} command, where \var{id} has the same meaning as for\method{stat()}.  If the \var{file} parameter is supplied, thenthe body is stored in a file.  If \var{file} is a string, thenthe method will open a file object with that name, write to it then close it.If \var{file} is a file object, then it will start calling\method{write()} on it to store the lines of the body.Return as for \method{head()}.  If \var{file} is supplied, thenthe returned \var{list} is an empty list.\end{methoddesc} \begin{methoddesc}{article}{id}Send an \samp{ARTICLE} command, where \var{id} has the same meaning asfor \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, \optional{file}}Send an \samp{XHDR} command.  This command is not defined in the RFCbut is a common extension.  The \var{header} argument is a headerkeyword, e.g. \code{'subject'}.  The \var{string} argument should havethe form \code{'\var{first}-\var{last}'} where \var{first} and\var{last} are the first and last article numbers to search.  Return apair \code{(\var{response}, \var{list})}, where \var{list} is a list ofpairs \code{(\var{id}, \var{text})}, where \var{id} is an article number(as a string) and \var{text} is the text of the requested header forthat article.If the \var{file} parameter is supplied, then the output of the \samp{XHDR} command is stored in a file.  If \var{file} is a string, then the method will open a file object with that name, write to it then close it.  If \var{file} is a file object, then it will startcalling \method{write()} on it to store the lines of the command output.If \var{file} is supplied, then the returned \var{list} is an empty list.\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()} methodautomatically escapes lines beginning with \samp{.}.\end{methoddesc} \begin{methoddesc}{ihave}{id, file}Send an \samp{IHAVE} command. \var{id} is a message id (enclosed in \character{<} and \character{>}).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 allservers.\end{methoddesc} \begin{methoddesc}{xgtitle}{name, \optional{file}}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?If the \var{file} parameter is supplied, then the output of the \samp{XGTITLE} command is stored in a file.  If \var{file} is a string, then the method will open a file object with that name, write to it then close it.  If \var{file} is a file object, then it will startcalling \method{write()} on it to store the lines of the command output.If \var{file} is supplied, then the returned \var{list} is an empty list.This is an optional NNTP extension, and may not be supported by allservers. RFC2980 says ``It is suggested that this extension be deprecated''.  Use\method{descriptions()} or \method{description()} instead.\end{methoddesc} \begin{methoddesc}{xover}{start, end, \optional{file}}Return a pair \code{(\var{resp}, \var{list})}.  \var{list} is a listof 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}, \var{subject}, \var{poster}, \var{date},\var{id}, \var{references}, \var{size}, \var{lines})}.If the \var{file} parameter is supplied, then the output of the \samp{XOVER} command is stored in a file.  If \var{file} is a string, then the method will open a file object with that name, write to it then close it.  If \var{file} is a file object, then it will startcalling \method{write()} on it to store the lines of the command output.If \var{file} is supplied, then the returned \var{list} is an empty list.This is an optional NNTP extension, and may not be supported by allservers.\end{methoddesc} \begin{methoddesc}{xpath}{id}Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is thedirectory path to the article with message ID \var{id}.  This is anoptional 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 methodhas been called, no other methods of the NNTP object should be called.\end{methoddesc}