Doc/lib/libnntplib.tex

   1 \section{Standard Module \module{nntplib}}
   2 \label{module-nntplib}
   3 \stmodindex{nntplib}
   4 \indexii{NNTP}{protocol}
   5
   6
   7 This module defines the class \class{NNTP} which implements the client
   8 side of the NNTP protocol.  It can be used to implement a news reader
   9 or poster, or automated news processors.  For more information on NNTP
  10 (Network News Transfer Protocol), see Internet \rfc{977}.
  11
  12 Here are two small examples of how it can be used.  To list some
  13 statistics about a newsgroup and print the subjects of the last 10
  14 articles:
  15
  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 \end{verbatim}
  37
  38 To post an article from a file (this assumes that the article has
  39 valid headers):
  40
  41 \begin{verbatim}
  42 >>> s = NNTP('news.cwi.nl')
  43 >>> f = open('/tmp/article')
  44 >>> s.post(f)
  45 '240 Article posted successfully.'
  46 >>> s.quit()
  47 '205 news.cwi.nl closing connection.  Goodbye.'
  48 \end{verbatim}
  49 %
  50 The module itself defines the following items:
  51
  52 \begin{classdesc}{NNTP}{host\optional{, port}}
  53 Return a new instance of the \class{NNTP} class, representing a
  54 connection to the NNTP server running on host \var{host}, listening at
  55 port \var{port}.  The default \var{port} is 119.
  56 \end{classdesc}
  57
  58 \begin{excdesc}{error_reply}
  59 Exception raised when an unexpected reply is received from the server.
  60 \end{excdesc}
  61
  62 \begin{excdesc}{error_temp}
  63 Exception raised when an error code in the range 400--499 is received.
  64 \end{excdesc}
  65
  66 \begin{excdesc}{error_perm}
  67 Exception raised when an error code in the range 500--599 is received.
  68 \end{excdesc}
  69
  70 \begin{excdesc}{error_proto}
  71 Exception raised when a reply is received from the server that does
  72 not begin with a digit in the range 1--5.
  73 \end{excdesc}
  74
  75
  76 \subsection{NNTP Objects}
  77 \label{nntp-objects}
  78
  79 NNTP instances have the following methods.  The \var{response} that is
  80 returned as the first item in the return tuple of almost all methods
  81 is the server's response: a string beginning with a three-digit code.
  82 If the server's response indicates an error, the method raises one of
  83 the above exceptions.
  84
  85
  86 \begin{methoddesc}{getwelcome}{}
  87 Return the welcome message sent by the server in reply to the initial
  88 connection.  (This message sometimes contains disclaimers or help
  89 information that may be relevant to the user.)
  90 \end{methoddesc}
  91
  92 \begin{methoddesc}{set_debuglevel}{level}
  93 Set the instance's debugging level.  This controls the amount of
  94 debugging output printed.  The default, \code{0}, produces no debugging
  95 output.  A value of \code{1} produces a moderate amount of debugging
  96 output, generally a single line per request or response.  A value of
  97 \code{2} or higher produces the maximum amount of debugging output,
  98 logging each line sent and received on the connection (including
  99 message text).
 100 \end{methoddesc}
 101
 102 \begin{methoddesc}{newgroups}{date, time}
 103 Send a \samp{NEWGROUPS} command.  The \var{date} argument should be a
 104 string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
 105 date, and \var{time} should be a string of the form
 106 \code{"\var{hh}\var{mm}\var{ss}"} indicating the time.  Return a pair
 107 \code{(\var{response}, \var{groups})} where \var{groups} is a list of
 108 group names that are new since the given date and time.
 109 \end{methoddesc}
 110
 111 \begin{methoddesc}{newnews}{group, date, time}
 112 Send a \samp{NEWNEWS} command.  Here, \var{group} is a group name or
 113 \code{'*'}, and \var{date} and \var{time} have the same meaning as for
 114 \method{newgroups()}.  Return a pair \code{(\var{response},
 115 \var{articles})} where \var{articles} is a list of article ids.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}{list}{}
 119 Send a \samp{LIST} command.  Return a pair \code{(\var{response},
 120 \var{list})} where \var{list} is a list of tuples.  Each tuple has the
 121 form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
 122 \var{group} is a group name, \var{last} and \var{first} are the last
 123 and first article numbers (as strings), and \var{flag} is \code{'y'}
 124 if posting is allowed, \code{'n'} if not, and \code{'m'} if the
 125 newsgroup is moderated.  (Note the ordering: \var{last}, \var{first}.)
 126 \end{methoddesc}
 127
 128 \begin{methoddesc}{group}{name}
 129 Send a \samp{GROUP} command, where \var{name} is the group name.
 130 Return a tuple \code{(}\var{response}\code{,} \var{count}\code{,}
 131 \var{first}\code{,} \var{last}\code{,} \var{name}\code{)} where
 132 \var{count} is the (estimated) number of articles in the group,
 133 \var{first} is the first article number in the group, \var{last} is
 134 the last article number in the group, and \var{name} is the group
 135 name.  The numbers are returned as strings.
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}{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{methoddesc}
 142
 143 \begin{methoddesc}{stat}{id}
 144 Send a \samp{STAT} command, where \var{id} is the message id (enclosed
 145 in \character{<} and \character{>}) 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 \character{<} and \character{>}).
 149 \end{methoddesc}
 150
 151 \begin{methoddesc}{next}{}
 152 Send a \samp{NEXT} command.  Return as for \method{stat()}.
 153 \end{methoddesc}
 154
 155 \begin{methoddesc}{last}{}
 156 Send a \samp{LAST} command.  Return as for \method{stat()}.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}{head}{id}
 160 Send a \samp{HEAD} command, where \var{id} has the same meaning as for
 161 \method{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{methoddesc}
 165
 166 \begin{methoddesc}{body}{id}
 167 Send a \samp{BODY} command, where \var{id} has the same meaning as for
 168 \method{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{methoddesc}
 172
 173 \begin{methoddesc}{article}{id}
 174 Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
 175 for \method{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{methoddesc}
 179
 180 \begin{methoddesc}{slave}{}
 181 Send a \samp{SLAVE} command.  Return the server's \var{response}.
 182 \end{methoddesc}
 183
 184 \begin{methoddesc}{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{methoddesc}
 195
 196 \begin{methoddesc}{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 \method{readline()} method.  It should be a well-formed news article,
 200 including the required headers.  The \method{post()} method
 201 automatically escapes lines beginning with \samp{.}.
 202 \end{methoddesc}
 203
 204 \begin{methoddesc}{ihave}{id, file}
 205 Send an \samp{IHAVE} command.  If the response is not an error, treat
 206 \var{file} exactly as for the \method{post()} method.
 207 \end{methoddesc}
 208
 209 \begin{methoddesc}{date}{}
 210 Return a triple \code{(\var{response}, \var{date}, \var{time})},
 211 containing the current date and time in a form suitable for the
 212 \method{newnews()} and \method{newgroups()} methods.
 213 This is an optional NNTP extension, and may not be supported by all
 214 servers.
 215 \end{methoddesc}
 216
 217 \begin{methoddesc}{xgtitle}{name}
 218 Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
 219 \var{list})}, where \var{list} is a list of tuples containing
 220 \code{(\var{name}, \var{title})}.
 221 % XXX huh?  Should that be name, description?
 222 This is an optional NNTP extension, and may not be supported by all
 223 servers.
 224 \end{methoddesc}
 225
 226 \begin{methoddesc}{xover}{start, end}
 227 Return a pair \code{(\var{resp}, \var{list})}.  \var{list} is a list
 228 of tuples, one for each article in the range delimited by the \var{start}
 229 and \var{end} article numbers.  Each tuple is of the form
 230 \code{(}\var{article number}\code{,} \var{subject}\code{,}
 231 \var{poster}\code{,} \var{date}\code{,} \var{id}\code{,}
 232 \var{references}\code{,} \var{size}\code{,} \var{lines}\code{)}.
 233 This is an optional NNTP extension, and may not be supported by all
 234 servers.
 235 \end{methoddesc}
 236
 237 \begin{methoddesc}{xpath}{id}
 238 Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
 239 directory path to the article with message ID \var{id}.  This is an
 240 optional NNTP extension, and may not be supported by all servers.
 241 \end{methoddesc}
 242
 243 \begin{methoddesc}{quit}{}
 244 Send a \samp{QUIT} command and close the connection.  Once this method
 245 has been called, no other methods of the NNTP object should be called.
 246 \end{methoddesc}