blob: 4f57c9b157df8c5c59f57f7f036b0a651f0424ea [file] [log] [blame]
Guido van Rossum470be141995-03-17 16:07:09 +00001\section{Standard Module \sectcode{nntplib}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00002\label{module-nntplib}
Guido van Rossuma12ef941995-02-27 17:53:25 +00003\stmodindex{nntplib}
Fred Drake6279fcc1998-01-07 13:23:32 +00004\indexii{NNTP}{protocol}
5\index{RFC!977}
Guido van Rossum86751151995-02-28 17:14:32 +00006
7\renewcommand{\indexsubitem}{(in module nntplib)}
8
Guido van Rossumcca8d2b1995-03-22 15:48:46 +00009This module defines the class \code{NNTP} which implements the client
10side of the NNTP protocol. It can be used to implement a news reader
11or poster, or automated news processors. For more information on NNTP
12(Network News Transfer Protocol), see Internet RFC 977.
13
Guido van Rossum1b91cda1995-03-24 15:56:02 +000014Here are two small examples of how it can be used. To list some
15statistics about a newsgroup and print the subjects of the last 10
16articles:
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000017
Guido van Rossume47da0a1997-07-17 16:34:52 +000018\bcode\begin{verbatim}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000019>>> s = NNTP('news.cwi.nl')
20>>> resp, count, first, last, name = s.group('comp.lang.python')
21>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
22Group comp.lang.python has 59 articles, range 3742 to 3803
23>>> resp, subs = s.xhdr('subject', first + '-' + last)
24>>> for id, sub in subs[-10:]: print id, sub
25...
263792 Re: Removing elements from a list while iterating...
273793 Re: Who likes Info files?
283794 Emacs and doc strings
293795 a few questions about the Mac implementation
303796 Re: executable python scripts
313797 Re: executable python scripts
323798 Re: a few questions about the Mac implementation
333799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
343802 Re: executable python scripts
353803 Re: POSIX wait and SIGCHLD
36>>> s.quit()
37'205 news.cwi.nl closing connection. Goodbye.'
38>>>
Guido van Rossume47da0a1997-07-17 16:34:52 +000039\end{verbatim}\ecode
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000040
41To post an article from a file (this assumes that the article has
42valid headers):
43
Guido van Rossume47da0a1997-07-17 16:34:52 +000044\bcode\begin{verbatim}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000045>>> s = NNTP('news.cwi.nl')
46>>> f = open('/tmp/article')
47>>> s.post(f)
48'240 Article posted successfully.'
49>>> s.quit()
50'205 news.cwi.nl closing connection. Goodbye.'
51>>>
Guido van Rossume47da0a1997-07-17 16:34:52 +000052\end{verbatim}\ecode
53%
Guido van Rossum1b91cda1995-03-24 15:56:02 +000054The module itself defines the following items:
55
Fred Drake6279fcc1998-01-07 13:23:32 +000056\begin{funcdesc}{NNTP}{host\optional{, port}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +000057Return a new instance of the \code{NNTP} class, representing a
58connection to the NNTP server running on host \var{host}, listening at
59port \var{port}. The default \var{port} is 119.
60\end{funcdesc}
61
62\begin{excdesc}{error_reply}
63Exception raised when an unexpected reply is received from the server.
64\end{excdesc}
65
66\begin{excdesc}{error_temp}
67Exception raised when an error code in the range 400--499 is received.
68\end{excdesc}
69
70\begin{excdesc}{error_perm}
71Exception raised when an error code in the range 500--599 is received.
72\end{excdesc}
73
74\begin{excdesc}{error_proto}
75Exception raised when a reply is received from the server that does
76not begin with a digit in the range 1--5.
77\end{excdesc}
78
79\subsection{NNTP Objects}
80
81NNTP instances have the following methods. The \var{response} that is
82returned as the first item in the return tuple of almost all methods
83is the server's response: a string beginning with a three-digit code.
84If the server's response indicates an error, the method raises one of
85the above exceptions.
86
87\renewcommand{\indexsubitem}{(NNTP object method)}
88
89\begin{funcdesc}{getwelcome}{}
90Return the welcome message sent by the server in reply to the initial
91connection. (This message sometimes contains disclaimers or help
92information that may be relevant to the user.)
93\end{funcdesc}
94
95\begin{funcdesc}{set_debuglevel}{level}
96Set the instance's debugging level. This controls the amount of
97debugging output printed. The default, 0, produces no debugging
98output. A value of 1 produces a moderate amount of debugging output,
99generally a single line per request or response. A value of 2 or
100higher produces the maximum amount of debugging output, logging each
101line sent and received on the connection (including message text).
102\end{funcdesc}
103
Fred Drake6279fcc1998-01-07 13:23:32 +0000104\begin{funcdesc}{newgroups}{date, time}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000105Send a \samp{NEWGROUPS} command. The \var{date} argument should be a
106string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
107date, and \var{time} should be a string of the form
108\code{"\var{hh}\var{mm}\var{ss}"} indicating the time. Return a pair
109\code{(\var{response}, \var{groups})} where \var{groups} is a list of
110group names that are new since the given date and time.
111\end{funcdesc}
112
Fred Drake6279fcc1998-01-07 13:23:32 +0000113\begin{funcdesc}{newnews}{group, date, time}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000114Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
115\code{"*"}, and \var{date} and \var{time} have the same meaning as for
116\code{newgroups()}. Return a pair \code{(\var{response},
117\var{articles})} where \var{articles} is a list of article ids.
118\end{funcdesc}
119
120\begin{funcdesc}{list}{}
121Send a \samp{LIST} command. Return a pair \code{(\var{response},
122\var{list})} where \var{list} is a list of tuples. Each tuple has the
123form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
124\var{group} is a group name, \var{last} and \var{first} are the last
125and first article numbers (as strings), and \var{flag} is \code{'y'}
126if posting is allowed, \code{'n'} if not, and \code{'m'} if the
127newsgroup is moderated. (Note the ordering: \var{last}, \var{first}.)
128\end{funcdesc}
129
130\begin{funcdesc}{group}{name}
131Send a \samp{GROUP} command, where \var{name} is the group name.
132Return a tuple \code{(\var{response}, \var{count}, \var{first},
133\var{last}, \var{name})} where \var{count} is the (estimated) number
134of articles in the group, \var{first} is the first article number in
135the group, \var{last} is the last article number in the group, and
136\var{name} is the group name. The numbers are returned as strings.
137\end{funcdesc}
138
139\begin{funcdesc}{help}{}
140Send a \samp{HELP} command. Return a pair \code{(\var{response},
141\var{list})} where \var{list} is a list of help strings.
142\end{funcdesc}
143
144\begin{funcdesc}{stat}{id}
145Send a \samp{STAT} command, where \var{id} is the message id (enclosed
146in \samp{<} and \samp{>}) or an article number (as a string).
Fred Drake4b3f0311996-12-13 22:04:31 +0000147Return a triple \code{(\var{response}, \var{number}, \var{id})} where
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000148\var{number} is the article number (as a string) and \var{id} is the
149article id (enclosed in \samp{<} and \samp{>}).
150\end{funcdesc}
151
152\begin{funcdesc}{next}{}
153Send a \samp{NEXT} command. Return as for \code{stat()}.
154\end{funcdesc}
155
156\begin{funcdesc}{last}{}
157Send a \samp{LAST} command. Return as for \code{stat()}.
158\end{funcdesc}
159
160\begin{funcdesc}{head}{id}
161Send a \samp{HEAD} command, where \var{id} has the same meaning as for
162\code{stat()}. Return a pair \code{(\var{response}, \var{list})}
163where \var{list} is a list of the article's headers (an uninterpreted
164list of lines, without trailing newlines).
165\end{funcdesc}
166
167\begin{funcdesc}{body}{id}
168Send a \samp{BODY} command, where \var{id} has the same meaning as for
169\code{stat()}. Return a pair \code{(\var{response}, \var{list})}
170where \var{list} is a list of the article's body text (an
171uninterpreted list of lines, without trailing newlines).
172\end{funcdesc}
173
174\begin{funcdesc}{article}{id}
175Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
176for \code{stat()}. Return a pair \code{(\var{response}, \var{list})}
177where \var{list} is a list of the article's header and body text (an
178uninterpreted list of lines, without trailing newlines).
179\end{funcdesc}
180
181\begin{funcdesc}{slave}{}
182Send a \samp{SLAVE} command. Return the server's \var{response}.
183\end{funcdesc}
184
Fred Drake6279fcc1998-01-07 13:23:32 +0000185\begin{funcdesc}{xhdr}{header, string}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000186Send an \samp{XHDR} command. This command is not defined in the RFC
187but is a common extension. The \var{header} argument is a header
188keyword, e.g. \code{"subject"}. The \var{string} argument should have
189the form \code{"\var{first}-\var{last}"} where \var{first} and
190\var{last} are the first and last article numbers to search. Return a
191pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
192pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
193(as a string) and \var{text} is the text of the requested header for
194that article.
195\end{funcdesc}
196
197\begin{funcdesc}{post}{file}
198Post an article using the \samp{POST} command. The \var{file}
199argument is an open file object which is read until EOF using its
200\code{readline()} method. It should be a well-formed news article,
201including the required headers. The \code{post()} method
202automatically escapes lines beginning with \samp{.}.
203\end{funcdesc}
204
Fred Drake6279fcc1998-01-07 13:23:32 +0000205\begin{funcdesc}{ihave}{id, file}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000206Send an \samp{IHAVE} command. If the response is not an error, treat
207\var{file} exactly as for the \code{post()} method.
208\end{funcdesc}
209
Guido van Rossum94adab51997-06-02 17:27:50 +0000210\begin{funcdesc}{date}{}
211Return a triple \code{(\var{response}, \var{date}, \var{time})},
212containing the current date and time in a form suitable for the
213\code{newnews} and \code{newgroups} methods.
214This is an optional NNTP extension, and may not be supported by all
215servers.
216\end{funcdesc}
217
218\begin{funcdesc}{xgtitle}{name}
219Process an XGTITLE command, returning a pair \code{(\var{response},
220\var{list}}, where \var{list} is a list of tuples containing
221\code{(\var{name}, \var{title})}.
222% XXX huh? Should that be name, description?
223This is an optional NNTP extension, and may not be supported by all
224servers.
225\end{funcdesc}
226
Fred Drake6279fcc1998-01-07 13:23:32 +0000227\begin{funcdesc}{xover}{start, end}
Guido van Rossum94adab51997-06-02 17:27:50 +0000228Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
229of tuples, one for each article in the range delimited by the \var{start}
230and \var{end} article numbers. Each tuple is of the form
Fred Drake6279fcc1998-01-07 13:23:32 +0000231\code{(}\var{article number}, \var{subject}, \var{poster}, \var{date}, \var{id}, \var{references}, \var{size}, \var{lines}\code{)}.
Guido van Rossum94adab51997-06-02 17:27:50 +0000232This is an optional NNTP extension, and may not be supported by all
233servers.
234\end{funcdesc}
235
236\begin{funcdesc}{xpath}{id}
237Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
238directory path to the article with message ID \var{id}. This is an
239optional NNTP extension, and may not be supported by all servers.
240\end{funcdesc}
241
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000242\begin{funcdesc}{quit}{}
243Send a \samp{QUIT} command and close the connection. Once this method
244has been called, no other methods of the NNTP object should be called.
245\end{funcdesc}