rest25/library/nntplib.rst => rest262/library/nntplib.rst
19about a newsgroup and print the subjects of the last 10 articles::
20
21   >>> s = NNTP('news.cwi.nl')
22   >>> resp, count, first, last, name = s.group('comp.lang.python')
23   >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
24   Group comp.lang.python has 59 articles, range 3742 to 3803
25   >>> resp, subs = s.xhdr('subject', first + '-' + last)
26   >>> for id, sub in subs[-10:]: print id, sub
n27-   ... 
n27+   ...
28   3792 Re: Removing elements from a list while iterating...
29   3793 Re: Who likes Info files?
30   3794 Emacs and doc strings
31   3795 a few questions about the Mac implementation
32   3796 Re: executable python scripts
33   3797 Re: executable python scripts
n34-   3798 Re: a few questions about the Mac implementation 
n34+   3798 Re: a few questions about the Mac implementation
35   3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
n36-   3802 Re: executable python scripts 
n36+   3802 Re: executable python scripts
37   3803 Re: \POSIX{} wait and SIGCHLD
38   >>> s.quit()
39   '205 news.cwi.nl closing connection.  Goodbye.'
40
41To post an article from a file (this assumes that the article has valid
42headers)::
43
44   >>> s = NNTP('news.cwi.nl')
48   >>> s.quit()
49   '205 news.cwi.nl closing connection.  Goodbye.'
50
51The module itself defines the following items:
52
53
54.. class:: NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]])
55
n56-   Return a new instance of the :class:`NNTP` class, representing a connection to
n56+   Return a new instance of the :class:`NNTP` class, representing a connection
57-   the NNTP server running on host *host*, listening at port *port*.  The default
57+   to the NNTP server running on host *host*, listening at port *port*.  The
58-   *port* is 119.  If the optional *user* and *password* are provided,  or if
58+   default *port* is 119.  If the optional *user* and *password* are provided,
59-   suitable credentials are present in :file:`/.netrc` and the optional flag
59+   or if suitable credentials are present in :file:`/.netrc` and the optional
60-   *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO PASS``
60+   flag *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO
61-   commands are used to identify and authenticate the user to the server.  If the
61+   PASS`` commands are used to identify and authenticate the user to the server.
62-   optional flag *readermode* is true, then a ``mode reader`` command is sent
62+   If the optional flag *readermode* is true, then a ``mode reader`` command is
63-   before authentication is performed.  Reader mode is sometimes necessary if you
63+   sent before authentication is performed.  Reader mode is sometimes necessary
64-   are connecting to an NNTP server on the local machine and intend to call reader-
64+   if you are connecting to an NNTP server on the local machine and intend to
65-   specific commands, such as ``group``.  If you get unexpected
65+   call reader-specific commands, such as ``group``.  If you get unexpected
66-   :exc:`NNTPPermanentError`\ s, you might need to set *readermode*.  *readermode*
66+   :exc:`NNTPPermanentError`\ s, you might need to set *readermode*.
67-   defaults to ``None``. *usenetrc* defaults to ``True``.
67+   *readermode* defaults to ``None``. *usenetrc* defaults to ``True``.
68
69   .. versionchanged:: 2.4
70      *usenetrc* argument added.
71
72
73.. exception:: NNTPError
74
75   Derived from the standard exception :exc:`Exception`, this is the base class for
116------------
117
118NNTP instances have the following methods.  The *response* that is returned as
119the first item in the return tuple of almost all methods is the server's
120response: a string beginning with a three-digit code. If the server's response
121indicates an error, the method raises one of the above exceptions.
122
123
n124-.. method:: XXX Class.getwelcome()
n124+.. method:: NNTP.getwelcome()
125
126   Return the welcome message sent by the server in reply to the initial
127   connection.  (This message sometimes contains disclaimers or help information
128   that may be relevant to the user.)
129
130
n131-.. method:: XXX Class.set_debuglevel(level)
n131+.. method:: NNTP.set_debuglevel(level)
132
133   Set the instance's debugging level.  This controls the amount of debugging
134   output printed.  The default, ``0``, produces no debugging output.  A value of
135   ``1`` produces a moderate amount of debugging output, generally a single line
136   per request or response.  A value of ``2`` or higher produces the maximum amount
137   of debugging output, logging each line sent and received on the connection
138   (including message text).
139
140
n141-.. method:: XXX Class.newgroups(date, time, [file])
n141+.. method:: NNTP.newgroups(date, time, [file])
142
143   Send a ``NEWGROUPS`` command.  The *date* argument should be a string of the
144   form ``'yymmdd'`` indicating the date, and *time* should be a string of the form
145   ``'hhmmss'`` indicating the time.  Return a pair ``(response, groups)`` where
146   *groups* is a list of group names that are new since the given date and time. If
147   the *file* parameter is supplied, then the output of the  ``NEWGROUPS`` command
148   is stored in a file.  If *file* is a string,  then the method will open a file
149   object with that name, write to it  then close it.  If *file* is a file object,
150   then it will start calling :meth:`write` on it to store the lines of the command
151   output. If *file* is supplied, then the returned *list* is an empty list.
152
153
n154-.. method:: XXX Class.newnews(group, date, time, [file])
n154+.. method:: NNTP.newnews(group, date, time, [file])
155
156   Send a ``NEWNEWS`` command.  Here, *group* is a group name or ``'*'``, and
157   *date* and *time* have the same meaning as for :meth:`newgroups`.  Return a pair
158   ``(response, articles)`` where *articles* is a list of message ids. If the
159   *file* parameter is supplied, then the output of the  ``NEWNEWS`` command is
160   stored in a file.  If *file* is a string,  then the method will open a file
161   object with that name, write to it  then close it.  If *file* is a file object,
162   then it will start calling :meth:`write` on it to store the lines of the command
163   output. If *file* is supplied, then the returned *list* is an empty list.
164
165
n166-.. method:: XXX Class.list([file])
n166+.. method:: NNTP.list([file])
167
168   Send a ``LIST`` command.  Return a pair ``(response, list)`` where *list* is a
169   list of tuples.  Each tuple has the form ``(group, last, first, flag)``, where
170   *group* is a group name, *last* and *first* are the last and first article
171   numbers (as strings), and *flag* is ``'y'`` if posting is allowed, ``'n'`` if
172   not, and ``'m'`` if the newsgroup is moderated.  (Note the ordering: *last*,
173   *first*.) If the *file* parameter is supplied, then the output of the  ``LIST``
174   command is stored in a file.  If *file* is a string,  then the method will open
175   a file object with that name, write to it  then close it.  If *file* is a file
176   object, then it will start calling :meth:`write` on it to store the lines of the
177   command output. If *file* is supplied, then the returned *list* is an empty
178   list.
179
180
n181-.. method:: XXX Class.descriptions(grouppattern)
n181+.. method:: NNTP.descriptions(grouppattern)
182
183   Send a ``LIST NEWSGROUPS`` command, where *grouppattern* is a wildmat string as
184   specified in RFC2980 (it's essentially the same as DOS or UNIX shell wildcard
185   strings).  Return a pair ``(response, list)``, where *list* is a list of tuples
186   containing ``(name, title)``.
187
188   .. versionadded:: 2.4
189
190
n191-.. method:: XXX Class.description(group)
n191+.. method:: NNTP.description(group)
192
193   Get a description for a single group *group*.  If more than one group matches
194   (if 'group' is a real wildmat string), return the first match.   If no group
195   matches, return an empty string.
196
197   This elides the response code from the server.  If the response code is needed,
198   use :meth:`descriptions`.
199
200   .. versionadded:: 2.4
201
202
n203-.. method:: XXX Class.group(name)
n203+.. method:: NNTP.group(name)
204
205   Send a ``GROUP`` command, where *name* is the group name. Return a tuple
206   ``(response, count, first, last, name)`` where *count* is the (estimated) number
207   of articles in the group, *first* is the first article number in the group,
208   *last* is the last article number in the group, and *name* is the group name.
209   The numbers are returned as strings.
210
211
n212-.. method:: XXX Class.help([file])
n212+.. method:: NNTP.help([file])
213
214   Send a ``HELP`` command.  Return a pair ``(response, list)`` where *list* is a
215   list of help strings. If the *file* parameter is supplied, then the output of
216   the  ``HELP`` command is stored in a file.  If *file* is a string,  then the
217   method will open a file object with that name, write to it  then close it.  If
218   *file* is a file object, then it will start calling :meth:`write` on it to store
219   the lines of the command output. If *file* is supplied, then the returned *list*
220   is an empty list.
221
222
n223-.. method:: XXX Class.stat(id)
n223+.. method:: NNTP.stat(id)
224
225   Send a ``STAT`` command, where *id* is the message id (enclosed in ``'<'`` and
226   ``'>'``) or an article number (as a string). Return a triple ``(response,
227   number, id)`` where *number* is the article number (as a string) and *id* is the
228   message id  (enclosed in ``'<'`` and ``'>'``).
229
230
n231-.. method:: XXX Class.next()
n231+.. method:: NNTP.next()
232
233   Send a ``NEXT`` command.  Return as for :meth:`stat`.
234
235
n236-.. method:: XXX Class.last()
n236+.. method:: NNTP.last()
237
238   Send a ``LAST`` command.  Return as for :meth:`stat`.
239
240
n241-.. method:: XXX Class.head(id)
n241+.. method:: NNTP.head(id)
242
243   Send a ``HEAD`` command, where *id* has the same meaning as for :meth:`stat`.
244   Return a tuple ``(response, number, id, list)`` where the first three are the
245   same as for :meth:`stat`, and *list* is a list of the article's headers (an
246   uninterpreted list of lines, without trailing newlines).
247
248
n249-.. method:: XXX Class.body(id,[file])
n249+.. method:: NNTP.body(id,[file])
250
251   Send a ``BODY`` command, where *id* has the same meaning as for :meth:`stat`.
252   If the *file* parameter is supplied, then the body is stored in a file.  If
253   *file* is a string, then the method will open a file object with that name,
254   write to it then close it. If *file* is a file object, then it will start
255   calling :meth:`write` on it to store the lines of the body. Return as for
256   :meth:`head`.  If *file* is supplied, then the returned *list* is an empty list.
257
258
n259-.. method:: XXX Class.article(id)
n259+.. method:: NNTP.article(id)
260
261   Send an ``ARTICLE`` command, where *id* has the same meaning as for
262   :meth:`stat`.  Return as for :meth:`head`.
263
264
n265-.. method:: XXX Class.slave()
n265+.. method:: NNTP.slave()
266
267   Send a ``SLAVE`` command.  Return the server's *response*.
268
269
n270-.. method:: XXX Class.xhdr(header, string, [file])
n270+.. method:: NNTP.xhdr(header, string, [file])
271
272   Send an ``XHDR`` command.  This command is not defined in the RFC but is a
273   common extension.  The *header* argument is a header keyword, e.g.
274   ``'subject'``.  The *string* argument should have the form ``'first-last'``
275   where *first* and *last* are the first and last article numbers to search.
276   Return a pair ``(response, list)``, where *list* is a list of pairs ``(id,
277   text)``, where *id* is an article number (as a string) and *text* is the text of
278   the requested header for that article. If the *file* parameter is supplied, then
279   the output of the  ``XHDR`` command is stored in a file.  If *file* is a string,
280   then the method will open a file object with that name, write to it  then close
281   it.  If *file* is a file object, then it will start calling :meth:`write` on it
282   to store the lines of the command output. If *file* is supplied, then the
283   returned *list* is an empty list.
284
285
n286-.. method:: XXX Class.post(file)
n286+.. method:: NNTP.post(file)
287
288   Post an article using the ``POST`` command.  The *file* argument is an open file
289   object which is read until EOF using its :meth:`readline` method.  It should be
290   a well-formed news article, including the required headers.  The :meth:`post`
291   method automatically escapes lines beginning with ``.``.
292
293
n294-.. method:: XXX Class.ihave(id, file)
n294+.. method:: NNTP.ihave(id, file)
295
296   Send an ``IHAVE`` command. *id* is a message id (enclosed in  ``'<'`` and
297   ``'>'``). If the response is not an error, treat *file* exactly as for the
298   :meth:`post` method.
299
300
n301-.. method:: XXX Class.date()
n301+.. method:: NNTP.date()
302
303   Return a triple ``(response, date, time)``, containing the current date and time
304   in a form suitable for the :meth:`newnews` and :meth:`newgroups` methods. This
305   is an optional NNTP extension, and may not be supported by all servers.
306
307
n308-.. method:: XXX Class.xgtitle(name, [file])
n308+.. method:: NNTP.xgtitle(name, [file])
309
310   Process an ``XGTITLE`` command, returning a pair ``(response, list)``, where
311   *list* is a list of tuples containing ``(name, title)``. If the *file* parameter
312   is supplied, then the output of the  ``XGTITLE`` command is stored in a file.
313   If *file* is a string,  then the method will open a file object with that name,
314   write to it  then close it.  If *file* is a file object, then it will start
315   calling :meth:`write` on it to store the lines of the command output. If *file*
316   is supplied, then the returned *list* is an empty list. This is an optional NNTP
317   extension, and may not be supported by all servers.
318
n319-   .. % XXX huh?  Should that be name, description?
320- 
321   RFC2980 says "It is suggested that this extension be deprecated".  Use
322   :meth:`descriptions` or :meth:`description` instead.
323
324
n325-.. method:: XXX Class.xover(start, end, [file])
n323+.. method:: NNTP.xover(start, end, [file])
326
327   Return a pair ``(resp, list)``.  *list* is a list of tuples, one for each
328   article in the range delimited by the *start* and *end* article numbers.  Each
329   tuple is of the form ``(article number, subject, poster, date, id, references,
330   size, lines)``. If the *file* parameter is supplied, then the output of the
331   ``XOVER`` command is stored in a file.  If *file* is a string,  then the method
332   will open a file object with that name, write to it  then close it.  If *file*
333   is a file object, then it will start calling :meth:`write` on it to store the
334   lines of the command output. If *file* is supplied, then the returned *list* is
335   an empty list. This is an optional NNTP extension, and may not be supported by
336   all servers.
337
338
n339-.. method:: XXX Class.xpath(id)
n337+.. method:: NNTP.xpath(id)
340
341   Return a pair ``(resp, path)``, where *path* is the directory path to the
342   article with message ID *id*.  This is an optional NNTP extension, and may not
343   be supported by all servers.
344
345
t346-.. method:: XXX Class.quit()
t344+.. method:: NNTP.quit()
347
348   Send a ``QUIT`` command and close the connection.  Once this method has been
349   called, no other methods of the NNTP object should be called.
350
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op