Doc/libnntplib.tex

   1 \section{Standard Module \sectcode{nntplib}}
   2 \stmodindex{nntplib}
   3
   4 \renewcommand{\indexsubitem}{(in module nntplib)}
   5
   6 This module defines the class \code{NNTP} which implements the client
   7 side of the NNTP protocol.  It can be used to implement a news reader
   8 or poster, or automated news processors.  For more information on NNTP
   9 (Network News Transfer Protocol), see Internet RFC 977.
  10
  11 Here are two small examples of how it can be used.  To list some
  12 statistics about a newsgroup and print the subjects of the last 10
  13 articles:
  14
  15 \small{
  16 \begin{verbatim}
  17 >>> s = NNTP('news.cwi.nl')
  18 >>> resp, count, first, last, name = s.group('comp.lang.python')
  19 >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
  20 Group comp.lang.python has 59 articles, range 3742 to 3803
  21 >>> resp, subs = s.xhdr('subject', first + '-' + last)
  22 >>> for id, sub in subs[-10:]: print id, sub
  23 ...
  24 3792 Re: Removing elements from a list while iterating...
  25 3793 Re: Who likes Info files?
  26 3794 Emacs and doc strings
  27 3795 a few questions about the Mac implementation
  28 3796 Re: executable python scripts
  29 3797 Re: executable python scripts
  30 3798 Re: a few questions about the Mac implementation
  31 3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
  32 3802 Re: executable python scripts
  33 3803 Re: POSIX wait and SIGCHLD
  34 >>> s.quit()
  35 '205 news.cwi.nl closing connection.  Goodbye.'
  36 >>>
  37 \end{verbatim}
  38 }
  39
  40 To post an article from a file (this assumes that the article has
  41 valid headers):
  42
  43 \begin{verbatim}
  44 >>> s = NNTP('news.cwi.nl')
  45 >>> f = open('/tmp/article')
  46 >>> s.post(f)
  47 '240 Article posted successfully.'
  48 >>> s.quit()
  49 '205 news.cwi.nl closing connection.  Goodbye.'
  50 >>>
  51 \end{verbatim}
  52
  53 The module itself defines the following items:
  54
  55 \begin{funcdesc}{NNTP}{host\optional{\, port}}
  56 Return a new instance of the \code{NNTP} class, representing a
  57 connection to the NNTP server running on host \var{host}, listening at
  58 port \var{port}.  The default \var{port} is 119.
  59 \end{funcdesc}
  60
  61 \begin{excdesc}{error_reply}
  62 Exception raised when an unexpected reply is received from the server.
  63 \end{excdesc}
  64
  65 \begin{excdesc}{error_temp}
  66 Exception raised when an error code in the range 400--499 is received.
  67 \end{excdesc}
  68
  69 \begin{excdesc}{error_perm}
  70 Exception raised when an error code in the range 500--599 is received.
  71 \end{excdesc}
  72
  73 \begin{excdesc}{error_proto}
  74 Exception raised when a reply is received from the server that does
  75 not begin with a digit in the range 1--5.
  76 \end{excdesc}
  77
  78 \subsection{NNTP Objects}
  79
  80 NNTP instances have the following methods.  The \var{response} that is
  81 returned as the first item in the return tuple of almost all methods
  82 is the server's response: a string beginning with a three-digit code.
  83 If the server's response indicates an error, the method raises one of
  84 the above exceptions.
  85
  86 \renewcommand{\indexsubitem}{(NNTP object method)}
  87
  88 \begin{funcdesc}{getwelcome}{}
  89 Return the welcome message sent by the server in reply to the initial
  90 connection.  (This message sometimes contains disclaimers or help
  91 information that may be relevant to the user.)
  92 \end{funcdesc}
  93
  94 \begin{funcdesc}{set_debuglevel}{level}
  95 Set the instance's debugging level.  This controls the amount of
  96 debugging output printed.  The default, 0, produces no debugging
  97 output.  A value of 1 produces a moderate amount of debugging output,
  98 generally a single line per request or response.  A value of 2 or
  99 higher produces the maximum amount of debugging output, logging each
 100 line sent and received on the connection (including message text).
 101 \end{funcdesc}
 102
 103 \begin{funcdesc}{newgroups}{date\, time}
 104 Send a \samp{NEWGROUPS} command.  The \var{date} argument should be a
 105 string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
 106 date, and \var{time} should be a string of the form
 107 \code{"\var{hh}\var{mm}\var{ss}"} indicating the time.  Return a pair
 108 \code{(\var{response}, \var{groups})} where \var{groups} is a list of
 109 group names that are new since the given date and time.
 110 \end{funcdesc}
 111
 112 \begin{funcdesc}{newnews}{group\, date\, time}
 113 Send a \samp{NEWNEWS} command.  Here, \var{group} is a group name or
 114 \code{"*"}, and \var{date} and \var{time} have the same meaning as for
 115 \code{newgroups()}.  Return a pair \code{(\var{response},
 116 \var{articles})} where \var{articles} is a list of article ids.
 117 \end{funcdesc}
 118
 119 \begin{funcdesc}{list}{}
 120 Send a \samp{LIST} command.  Return a pair \code{(\var{response},
 121 \var{list})} where \var{list} is a list of tuples.  Each tuple has the
 122 form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
 123 \var{group} is a group name, \var{last} and \var{first} are the last
 124 and first article numbers (as strings), and \var{flag} is \code{'y'}
 125 if posting is allowed, \code{'n'} if not, and \code{'m'} if the
 126 newsgroup is moderated.  (Note the ordering: \var{last}, \var{first}.)
 127 \end{funcdesc}
 128
 129 \begin{funcdesc}{group}{name}
 130 Send a \samp{GROUP} command, where \var{name} is the group name.
 131 Return a tuple \code{(\var{response}, \var{count}, \var{first},
 132 \var{last}, \var{name})} where \var{count} is the (estimated) number
 133 of articles in the group, \var{first} is the first article number in
 134 the group, \var{last} is the last article number in the group, and
 135 \var{name} is the group name.  The numbers are returned as strings.
 136 \end{funcdesc}
 137
 138 \begin{funcdesc}{help}{}
 139 Send a \samp{HELP} command.  Return a pair \code{(\var{response},
 140 \var{list})} where \var{list} is a list of help strings.
 141 \end{funcdesc}
 142
 143 \begin{funcdesc}{stat}{id}
 144 Send a \samp{STAT} command, where \var{id} is the message id (enclosed
 145 in \samp{<} and \samp{>}) or an article number (as a string).
 146 Return a triple \code{(var{response}, \var{number}, \var{id})} where
 147 \var{number} is the article number (as a string) and \var{id} is the
 148 article id  (enclosed in \samp{<} and \samp{>}).
 149 \end{funcdesc}
 150
 151 \begin{funcdesc}{next}{}
 152 Send a \samp{NEXT} command.  Return as for \code{stat()}.
 153 \end{funcdesc}
 154
 155 \begin{funcdesc}{last}{}
 156 Send a \samp{LAST} command.  Return as for \code{stat()}.
 157 \end{funcdesc}
 158
 159 \begin{funcdesc}{head}{id}
 160 Send a \samp{HEAD} command, where \var{id} has the same meaning as for
 161 \code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
 162 where \var{list} is a list of the article's headers (an uninterpreted
 163 list of lines, without trailing newlines).
 164 \end{funcdesc}
 165
 166 \begin{funcdesc}{body}{id}
 167 Send a \samp{BODY} command, where \var{id} has the same meaning as for
 168 \code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
 169 where \var{list} is a list of the article's body text (an
 170 uninterpreted list of lines, without trailing newlines).
 171 \end{funcdesc}
 172
 173 \begin{funcdesc}{article}{id}
 174 Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
 175 for \code{stat()}.  Return a pair \code{(\var{response}, \var{list})}
 176 where \var{list} is a list of the article's header and body text (an
 177 uninterpreted list of lines, without trailing newlines).
 178 \end{funcdesc}
 179
 180 \begin{funcdesc}{slave}{}
 181 Send a \samp{SLAVE} command.  Return the server's \var{response}.
 182 \end{funcdesc}
 183
 184 \begin{funcdesc}{xhdr}{header\, string}
 185 Send an \samp{XHDR} command.  This command is not defined in the RFC
 186 but is a common extension.  The \var{header} argument is a header
 187 keyword, e.g. \code{"subject"}.  The \var{string} argument should have
 188 the form \code{"\var{first}-\var{last}"} where \var{first} and
 189 \var{last} are the first and last article numbers to search.  Return a
 190 pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
 191 pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
 192 (as a string) and \var{text} is the text of the requested header for
 193 that article.
 194 \end{funcdesc}
 195
 196 \begin{funcdesc}{post}{file}
 197 Post an article using the \samp{POST} command.  The \var{file}
 198 argument is an open file object which is read until EOF using its
 199 \code{readline()} method.  It should be a well-formed news article,
 200 including the required headers.  The \code{post()} method
 201 automatically escapes lines beginning with \samp{.}.
 202 \end{funcdesc}
 203
 204 \begin{funcdesc}{ihave}{id\, file}
 205 Send an \samp{IHAVE} command.  If the response is not an error, treat
 206 \var{file} exactly as for the \code{post()} method.
 207 \end{funcdesc}
 208
 209 \begin{funcdesc}{quit}{}
 210 Send a \samp{QUIT} command and close the connection.  Once this method
 211 has been called, no other methods of the NNTP object should be called.
 212 \end{funcdesc}