blob: 7f14deeac77eeee34cb2830cebb43f72643246b7 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{nntplib} ---
Fred Drakedd6c6d91999-04-22 16:45:26 +00002 NNTP protocol client}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drakedd6c6d91999-04-22 16:45:26 +00004\declaremodule{standard}{nntplib}
Fred Drakeb91e9341998-07-23 17:59:49 +00005\modulesynopsis{NNTP protocol client (requires sockets).}
6
Fred Drake6279fcc1998-01-07 13:23:32 +00007\indexii{NNTP}{protocol}
Fred Drake3f6034d1998-07-02 19:33:43 +00008\index{Network News Transfer Protocol}
Guido van Rossum86751151995-02-28 17:14:32 +00009
Fred Drakefc576191998-04-04 07:15:02 +000010This module defines the class \class{NNTP} which implements the client
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000011side of the NNTP protocol. It can be used to implement a news reader
12or poster, or automated news processors. For more information on NNTP
Fred Drakec5891241998-02-09 19:16:20 +000013(Network News Transfer Protocol), see Internet \rfc{977}.
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000014
Guido van Rossum1b91cda1995-03-24 15:56:02 +000015Here are two small examples of how it can be used. To list some
16statistics about a newsgroup and print the subjects of the last 10
17articles:
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000018
Fred Drake19479911998-02-13 06:58:54 +000019\begin{verbatim}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000020>>> s = NNTP('news.cwi.nl')
21>>> resp, count, first, last, name = s.group('comp.lang.python')
22>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
23Group comp.lang.python has 59 articles, range 3742 to 3803
24>>> resp, subs = s.xhdr('subject', first + '-' + last)
25>>> for id, sub in subs[-10:]: print id, sub
26...
273792 Re: Removing elements from a list while iterating...
283793 Re: Who likes Info files?
293794 Emacs and doc strings
303795 a few questions about the Mac implementation
313796 Re: executable python scripts
323797 Re: executable python scripts
333798 Re: a few questions about the Mac implementation
343799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
353802 Re: executable python scripts
Fred Drake65b32f71998-02-09 20:27:12 +0000363803 Re: \POSIX{} wait and SIGCHLD
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000037>>> s.quit()
38'205 news.cwi.nl closing connection. Goodbye.'
Fred Drake19479911998-02-13 06:58:54 +000039\end{verbatim}
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
Fred Drake19479911998-02-13 06:58:54 +000044\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.'
Fred Drake19479911998-02-13 06:58:54 +000051\end{verbatim}
Fred Drakedd6c6d91999-04-22 16:45:26 +000052
Guido van Rossum1b91cda1995-03-24 15:56:02 +000053The module itself defines the following items:
54
Fred Drakec46973c1998-11-16 17:11:30 +000055\begin{classdesc}{NNTP}{host\optional{, port
Barry Warsaw41d84632000-02-10 20:26:45 +000056 \optional{, user\optional{, password
Martin v. Löwis9513e342004-08-03 14:36:32 +000057 \optional{, readermode}
58 \optional{, usenetrc}}}}}
Fred Drakefc576191998-04-04 07:15:02 +000059Return a new instance of the \class{NNTP} class, representing a
Guido van Rossum1b91cda1995-03-24 15:56:02 +000060connection to the NNTP server running on host \var{host}, listening at
Fred Drakec46973c1998-11-16 17:11:30 +000061port \var{port}. The default \var{port} is 119. If the optional
Eric S. Raymond2852cba2002-12-31 15:28:44 +000062\var{user} and \var{password} are provided,
Martin v. Löwis9513e342004-08-03 14:36:32 +000063or if suitable credentials are present in \file{~/.netrc} and the
64optional flag \var{usenetrc} is true (the default),
Eric S. Raymond2852cba2002-12-31 15:28:44 +000065the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used to
Barry Warsaw41d84632000-02-10 20:26:45 +000066identify and authenticate the user to the server. If the optional
67flag \var{readermode} is true, then a \samp{mode reader} command is
68sent before authentication is performed. Reader mode is sometimes
69necessary if you are connecting to an NNTP server on the local machine
70and intend to call reader-specific commands, such as \samp{group}. If
71you get unexpected \code{NNTPPermanentError}s, you might need to set
72\var{readermode}. \var{readermode} defaults to \code{None}.
Martin v. Löwis9513e342004-08-03 14:36:32 +000073\var{usenetrc} defaults to \code{True}.
74
75\versionchanged[\var{usenetrc} argument added]{2.4}
Fred Drakefc576191998-04-04 07:15:02 +000076\end{classdesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +000077
Barry Warsaw41d84632000-02-10 20:26:45 +000078\begin{classdesc}{NNTPError}{}
79Derived from the standard exception \code{Exception}, this is the base
80class for all exceptions raised by the \code{nntplib} module.
81\end{classdesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +000082
Barry Warsaw41d84632000-02-10 20:26:45 +000083\begin{classdesc}{NNTPReplyError}{}
84Exception raised when an unexpected reply is received from the
85server. For backwards compatibility, the exception \code{error_reply}
86is equivalent to this class.
87\end{classdesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +000088
Barry Warsaw41d84632000-02-10 20:26:45 +000089\begin{classdesc}{NNTPTemporaryError}{}
90Exception raised when an error code in the range 400--499 is
91received. For backwards compatibility, the exception
92\code{error_temp} is equivalent to this class.
93\end{classdesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +000094
Barry Warsaw41d84632000-02-10 20:26:45 +000095\begin{classdesc}{NNTPPermanentError}{}
96Exception raised when an error code in the range 500--599 is
97received. For backwards compatibility, the exception
98\code{error_perm} is equivalent to this class.
99\end{classdesc}
100
101\begin{classdesc}{NNTPProtocolError}{}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000102Exception raised when a reply is received from the server that does
Barry Warsaw41d84632000-02-10 20:26:45 +0000103not begin with a digit in the range 1--5. For backwards
104compatibility, the exception \code{error_proto} is equivalent to this
105class.
106\end{classdesc}
107
108\begin{classdesc}{NNTPDataError}{}
109Exception raised when there is some error in the response data. For
110backwards compatibility, the exception \code{error_data} is
111equivalent to this class.
112\end{classdesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000113
Fred Drakefc576191998-04-04 07:15:02 +0000114
Fred Drakedd6c6d91999-04-22 16:45:26 +0000115\subsection{NNTP Objects \label{nntp-objects}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000116
117NNTP instances have the following methods. The \var{response} that is
118returned as the first item in the return tuple of almost all methods
119is the server's response: a string beginning with a three-digit code.
120If the server's response indicates an error, the method raises one of
121the above exceptions.
122
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000123
Fred Drakefc576191998-04-04 07:15:02 +0000124\begin{methoddesc}{getwelcome}{}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000125Return the welcome message sent by the server in reply to the initial
126connection. (This message sometimes contains disclaimers or help
127information that may be relevant to the user.)
Fred Drakefc576191998-04-04 07:15:02 +0000128\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000129
Fred Drakefc576191998-04-04 07:15:02 +0000130\begin{methoddesc}{set_debuglevel}{level}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000131Set the instance's debugging level. This controls the amount of
Fred Drakefc576191998-04-04 07:15:02 +0000132debugging output printed. The default, \code{0}, produces no debugging
133output. A value of \code{1} produces a moderate amount of debugging
134output, generally a single line per request or response. A value of
135\code{2} or higher produces the maximum amount of debugging output,
136logging each line sent and received on the connection (including
137message text).
138\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000139
Guido van Rossuma2685402003-04-19 18:04:57 +0000140\begin{methoddesc}{newgroups}{date, time, \optional{file}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000141Send a \samp{NEWGROUPS} command. The \var{date} argument should be a
Fred Drakedd6c6d91999-04-22 16:45:26 +0000142string of the form \code{'\var{yy}\var{mm}\var{dd}'} indicating the
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000143date, and \var{time} should be a string of the form
Fred Drakedd6c6d91999-04-22 16:45:26 +0000144\code{'\var{hh}\var{mm}\var{ss}'} indicating the time. Return a pair
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000145\code{(\var{response}, \var{groups})} where \var{groups} is a list of
146group names that are new since the given date and time.
Guido van Rossuma2685402003-04-19 18:04:57 +0000147If the \var{file} parameter is supplied, then the output of the
148\samp{NEWGROUPS} command is stored in a file. If \var{file} is a string,
149then the method will open a file object with that name, write to it
150then close it. If \var{file} is a file object, then it will start
151calling \method{write()} on it to store the lines of the command output.
152If \var{file} is supplied, then the returned \var{list} is an empty list.
Fred Drakefc576191998-04-04 07:15:02 +0000153\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000154
Guido van Rossuma2685402003-04-19 18:04:57 +0000155\begin{methoddesc}{newnews}{group, date, time, \optional{file}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000156Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
Fred Drakefc576191998-04-04 07:15:02 +0000157\code{'*'}, and \var{date} and \var{time} have the same meaning as for
158\method{newgroups()}. Return a pair \code{(\var{response},
Georg Brandl5dbda752005-07-17 20:27:41 +0000159\var{articles})} where \var{articles} is a list of message ids.
Guido van Rossuma2685402003-04-19 18:04:57 +0000160If the \var{file} parameter is supplied, then the output of the
161\samp{NEWNEWS} command is stored in a file. If \var{file} is a string,
162then the method will open a file object with that name, write to it
163then close it. If \var{file} is a file object, then it will start
164calling \method{write()} on it to store the lines of the command output.
165If \var{file} is supplied, then the returned \var{list} is an empty list.
Fred Drakefc576191998-04-04 07:15:02 +0000166\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000167
Guido van Rossuma2685402003-04-19 18:04:57 +0000168\begin{methoddesc}{list}{\optional{file}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000169Send a \samp{LIST} command. Return a pair \code{(\var{response},
170\var{list})} where \var{list} is a list of tuples. Each tuple has the
171form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
172\var{group} is a group name, \var{last} and \var{first} are the last
Fred Drakedd6c6d91999-04-22 16:45:26 +0000173and first article numbers (as strings), and \var{flag} is
174\code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if
175the newsgroup is moderated. (Note the ordering: \var{last},
176\var{first}.)
Guido van Rossuma2685402003-04-19 18:04:57 +0000177If the \var{file} parameter is supplied, then the output of the
178\samp{LIST} command is stored in a file. If \var{file} is a string,
179then the method will open a file object with that name, write to it
180then close it. If \var{file} is a file object, then it will start
181calling \method{write()} on it to store the lines of the command output.
182If \var{file} is supplied, then the returned \var{list} is an empty list.
Martin v. Löwis8ddb6382004-07-30 16:08:49 +0000183\end{methoddesc}
Martin v. Löwiscc0f9322004-07-26 12:40:50 +0000184
185\begin{methoddesc}{descriptions}{grouppattern}
186Send a \samp{LIST NEWSGROUPS} command, where \var{grouppattern} is a wildmat
187string as specified in RFC2980 (it's essentially the same as DOS or UNIX
188shell wildcard strings). Return a pair \code{(\var{response},
189\var{list})}, where \var{list} is a list of tuples containing
190\code{(\var{name}, \var{title})}.
Martin v. Löwis8ddb6382004-07-30 16:08:49 +0000191
192\versionadded{2.4}
Martin v. Löwiscc0f9322004-07-26 12:40:50 +0000193\end{methoddesc}
194
195\begin{methoddesc}{description}{group}
196Get a description for a single group \var{group}. If more than one group
Martin v. Löwis8ddb6382004-07-30 16:08:49 +0000197matches (if 'group' is a real wildmat string), return the first match.
198If no group matches, return an empty string.
Martin v. Löwiscc0f9322004-07-26 12:40:50 +0000199
200This elides the response code from the server. If the response code is
201needed, use \method{descriptions()}.
202
Martin v. Löwis8ddb6382004-07-30 16:08:49 +0000203\versionadded{2.4}
Fred Drakefc576191998-04-04 07:15:02 +0000204\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000205
Fred Drakefc576191998-04-04 07:15:02 +0000206\begin{methoddesc}{group}{name}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000207Send a \samp{GROUP} command, where \var{name} is the group name.
Fred Drakedd6c6d91999-04-22 16:45:26 +0000208Return a tuple \code{(\var{response}, \var{count}, \var{first},
209\var{last}, \var{name})} where \var{count} is the (estimated) number
210of articles in the group, \var{first} is the first article number in
211the group, \var{last} is the last article number in the group, and
212\var{name} is the group name. The numbers are returned as strings.
Fred Drakefc576191998-04-04 07:15:02 +0000213\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000214
Guido van Rossuma2685402003-04-19 18:04:57 +0000215\begin{methoddesc}{help}{\optional{file}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000216Send a \samp{HELP} command. Return a pair \code{(\var{response},
217\var{list})} where \var{list} is a list of help strings.
Guido van Rossuma2685402003-04-19 18:04:57 +0000218If the \var{file} parameter is supplied, then the output of the
219\samp{HELP} command is stored in a file. If \var{file} is a string,
220then the method will open a file object with that name, write to it
221then close it. If \var{file} is a file object, then it will start
222calling \method{write()} on it to store the lines of the command output.
223If \var{file} is supplied, then the returned \var{list} is an empty list.
Fred Drakefc576191998-04-04 07:15:02 +0000224\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000225
Fred Drakefc576191998-04-04 07:15:02 +0000226\begin{methoddesc}{stat}{id}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000227Send a \samp{STAT} command, where \var{id} is the message id (enclosed
Fred Drakefc576191998-04-04 07:15:02 +0000228in \character{<} and \character{>}) or an article number (as a string).
Fred Drake4b3f0311996-12-13 22:04:31 +0000229Return a triple \code{(\var{response}, \var{number}, \var{id})} where
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000230\var{number} is the article number (as a string) and \var{id} is the
Georg Brandl5dbda752005-07-17 20:27:41 +0000231message id (enclosed in \character{<} and \character{>}).
Fred Drakefc576191998-04-04 07:15:02 +0000232\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000233
Fred Drakefc576191998-04-04 07:15:02 +0000234\begin{methoddesc}{next}{}
235Send a \samp{NEXT} command. Return as for \method{stat()}.
236\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000237
Fred Drakefc576191998-04-04 07:15:02 +0000238\begin{methoddesc}{last}{}
239Send a \samp{LAST} command. Return as for \method{stat()}.
240\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000241
Fred Drakefc576191998-04-04 07:15:02 +0000242\begin{methoddesc}{head}{id}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000243Send a \samp{HEAD} command, where \var{id} has the same meaning as for
Guido van Rossumcd905091998-06-30 14:53:41 +0000244\method{stat()}. Return a tuple
245\code{(\var{response}, \var{number}, \var{id}, \var{list})}
246where the first three are the same as for \method{stat()},
247and \var{list} is a list of the article's headers (an uninterpreted
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000248list of lines, without trailing newlines).
Fred Drakefc576191998-04-04 07:15:02 +0000249\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000250
Fredrik Lundha5e61652001-10-18 20:58:25 +0000251\begin{methoddesc}{body}{id,\optional{file}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000252Send a \samp{BODY} command, where \var{id} has the same meaning as for
Fredrik Lundha5e61652001-10-18 20:58:25 +0000253\method{stat()}. If the \var{file} parameter is supplied, then
254the body is stored in a file. If \var{file} is a string, then
Guido van Rossume7877df2001-10-01 13:50:15 +0000255the method will open a file object with that name, write to it then close it.
Fredrik Lundha5e61652001-10-18 20:58:25 +0000256If \var{file} is a file object, then it will start calling
Guido van Rossume7877df2001-10-01 13:50:15 +0000257\method{write()} on it to store the lines of the body.
Guido van Rossuma2685402003-04-19 18:04:57 +0000258Return as for \method{head()}. If \var{file} is supplied, then
Guido van Rossume7877df2001-10-01 13:50:15 +0000259the returned \var{list} is an empty list.
Fred Drakefc576191998-04-04 07:15:02 +0000260\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000261
Fred Drakefc576191998-04-04 07:15:02 +0000262\begin{methoddesc}{article}{id}
Fred Drake506a7a82000-07-01 17:43:19 +0000263Send an \samp{ARTICLE} command, where \var{id} has the same meaning as
Guido van Rossumcd905091998-06-30 14:53:41 +0000264for \method{stat()}. Return as for \method{head()}.
Fred Drakefc576191998-04-04 07:15:02 +0000265\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000266
Fred Drakefc576191998-04-04 07:15:02 +0000267\begin{methoddesc}{slave}{}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000268Send a \samp{SLAVE} command. Return the server's \var{response}.
Fred Drakefc576191998-04-04 07:15:02 +0000269\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000270
Guido van Rossuma2685402003-04-19 18:04:57 +0000271\begin{methoddesc}{xhdr}{header, string, \optional{file}}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000272Send an \samp{XHDR} command. This command is not defined in the RFC
273but is a common extension. The \var{header} argument is a header
Fred Drakefc576191998-04-04 07:15:02 +0000274keyword, e.g. \code{'subject'}. The \var{string} argument should have
Fred Drakedd6c6d91999-04-22 16:45:26 +0000275the form \code{'\var{first}-\var{last}'} where \var{first} and
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000276\var{last} are the first and last article numbers to search. Return a
277pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
Georg Brandl5dbda752005-07-17 20:27:41 +0000278pairs \code{(\var{id}, \var{text})}, where \var{id} is an article number
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000279(as a string) and \var{text} is the text of the requested header for
280that article.
Guido van Rossuma2685402003-04-19 18:04:57 +0000281If the \var{file} parameter is supplied, then the output of the
282\samp{XHDR} command is stored in a file. If \var{file} is a string,
283then the method will open a file object with that name, write to it
284then close it. If \var{file} is a file object, then it will start
285calling \method{write()} on it to store the lines of the command output.
286If \var{file} is supplied, then the returned \var{list} is an empty list.
Fred Drakefc576191998-04-04 07:15:02 +0000287\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000288
Fred Drakefc576191998-04-04 07:15:02 +0000289\begin{methoddesc}{post}{file}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000290Post an article using the \samp{POST} command. The \var{file}
291argument is an open file object which is read until EOF using its
Fred Drakefc576191998-04-04 07:15:02 +0000292\method{readline()} method. It should be a well-formed news article,
293including the required headers. The \method{post()} method
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000294automatically escapes lines beginning with \samp{.}.
Fred Drakefc576191998-04-04 07:15:02 +0000295\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000296
Fred Drakefc576191998-04-04 07:15:02 +0000297\begin{methoddesc}{ihave}{id, file}
Georg Brandl5dbda752005-07-17 20:27:41 +0000298Send an \samp{IHAVE} command. \var{id} is a message id (enclosed in
299\character{<} and \character{>}).
300If the response is not an error, treat
Fred Drakefc576191998-04-04 07:15:02 +0000301\var{file} exactly as for the \method{post()} method.
302\end{methoddesc}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000303
Fred Drakefc576191998-04-04 07:15:02 +0000304\begin{methoddesc}{date}{}
Guido van Rossum94adab51997-06-02 17:27:50 +0000305Return a triple \code{(\var{response}, \var{date}, \var{time})},
306containing the current date and time in a form suitable for the
Fred Drakefc576191998-04-04 07:15:02 +0000307\method{newnews()} and \method{newgroups()} methods.
Guido van Rossum94adab51997-06-02 17:27:50 +0000308This is an optional NNTP extension, and may not be supported by all
309servers.
Fred Drakefc576191998-04-04 07:15:02 +0000310\end{methoddesc}
Guido van Rossum94adab51997-06-02 17:27:50 +0000311
Guido van Rossuma2685402003-04-19 18:04:57 +0000312\begin{methoddesc}{xgtitle}{name, \optional{file}}
Fred Drakefc576191998-04-04 07:15:02 +0000313Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
Fred Drakefac431e1998-02-16 21:57:37 +0000314\var{list})}, where \var{list} is a list of tuples containing
Guido van Rossum94adab51997-06-02 17:27:50 +0000315\code{(\var{name}, \var{title})}.
316% XXX huh? Should that be name, description?
Guido van Rossuma2685402003-04-19 18:04:57 +0000317If the \var{file} parameter is supplied, then the output of the
318\samp{XGTITLE} command is stored in a file. If \var{file} is a string,
319then the method will open a file object with that name, write to it
320then close it. If \var{file} is a file object, then it will start
321calling \method{write()} on it to store the lines of the command output.
322If \var{file} is supplied, then the returned \var{list} is an empty list.
Guido van Rossum94adab51997-06-02 17:27:50 +0000323This is an optional NNTP extension, and may not be supported by all
324servers.
Martin v. Löwiscc0f9322004-07-26 12:40:50 +0000325
326RFC2980 says ``It is suggested that this extension be deprecated''. Use
327\method{descriptions()} or \method{description()} instead.
Fred Drakefc576191998-04-04 07:15:02 +0000328\end{methoddesc}
Guido van Rossum94adab51997-06-02 17:27:50 +0000329
Guido van Rossuma2685402003-04-19 18:04:57 +0000330\begin{methoddesc}{xover}{start, end, \optional{file}}
Guido van Rossum94adab51997-06-02 17:27:50 +0000331Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
332of tuples, one for each article in the range delimited by the \var{start}
333and \var{end} article numbers. Each tuple is of the form
Fred Drakedd6c6d91999-04-22 16:45:26 +0000334\code{(\var{article number}, \var{subject}, \var{poster}, \var{date},
335\var{id}, \var{references}, \var{size}, \var{lines})}.
Guido van Rossuma2685402003-04-19 18:04:57 +0000336If the \var{file} parameter is supplied, then the output of the
337\samp{XOVER} command is stored in a file. If \var{file} is a string,
338then the method will open a file object with that name, write to it
339then close it. If \var{file} is a file object, then it will start
340calling \method{write()} on it to store the lines of the command output.
341If \var{file} is supplied, then the returned \var{list} is an empty list.
Guido van Rossum94adab51997-06-02 17:27:50 +0000342This is an optional NNTP extension, and may not be supported by all
343servers.
Fred Drakefc576191998-04-04 07:15:02 +0000344\end{methoddesc}
Guido van Rossum94adab51997-06-02 17:27:50 +0000345
Fred Drakefc576191998-04-04 07:15:02 +0000346\begin{methoddesc}{xpath}{id}
Guido van Rossum94adab51997-06-02 17:27:50 +0000347Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
348directory path to the article with message ID \var{id}. This is an
349optional NNTP extension, and may not be supported by all servers.
Fred Drakefc576191998-04-04 07:15:02 +0000350\end{methoddesc}
Guido van Rossum94adab51997-06-02 17:27:50 +0000351
Fred Drakefc576191998-04-04 07:15:02 +0000352\begin{methoddesc}{quit}{}
Guido van Rossum1b91cda1995-03-24 15:56:02 +0000353Send a \samp{QUIT} command and close the connection. Once this method
354has been called, no other methods of the NNTP object should be called.
Fred Drakefc576191998-04-04 07:15:02 +0000355\end{methoddesc}