PageRenderTime 36ms CodeModel.GetById 15ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 1ms

/Doc/library/nntplib.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 348 lines | 235 code | 113 blank | 0 comment | 0 complexity | f78197b9c99420974fe1bf84be05659f MD5 | raw file
  1
  2:mod:`nntplib` --- NNTP protocol client
  3=======================================
  4
  5.. module:: nntplib
  6   :synopsis: NNTP protocol client (requires sockets).
  7
  8
  9.. index::
 10   pair: NNTP; protocol
 11   single: Network News Transfer Protocol
 12
 13This module defines the class :class:`NNTP` which implements the client side of
 14the NNTP protocol.  It can be used to implement a news reader or poster, or
 15automated news processors.  For more information on NNTP (Network News Transfer
 16Protocol), see Internet :rfc:`977`.
 17
 18Here are two small examples of how it can be used.  To list some statistics
 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
 27   ...
 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
 34   3798 Re: a few questions about the Mac implementation
 35   3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
 36   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')
 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
 51The module itself defines the following items:
 52
 53
 54.. class:: NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]])
 55
 56   Return a new instance of the :class:`NNTP` class, representing a connection
 57   to the NNTP server running on host *host*, listening at port *port*.  The
 58   default *port* is 119.  If the optional *user* and *password* are provided,
 59   or if suitable credentials are present in :file:`/.netrc` and the optional
 60   flag *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO
 61   PASS`` commands are used to identify and authenticate the user to the server.
 62   If the optional flag *readermode* is true, then a ``mode reader`` command is
 63   sent before authentication is performed.  Reader mode is sometimes necessary
 64   if you are connecting to an NNTP server on the local machine and intend to
 65   call reader-specific commands, such as ``group``.  If you get unexpected
 66   :exc:`NNTPPermanentError`\ s, you might need to set *readermode*.
 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
 76   all exceptions raised by the :mod:`nntplib` module.
 77
 78
 79.. exception:: NNTPReplyError
 80
 81   Exception raised when an unexpected reply is received from the server.  For
 82   backwards compatibility, the exception ``error_reply`` is equivalent to this
 83   class.
 84
 85
 86.. exception:: NNTPTemporaryError
 87
 88   Exception raised when an error code in the range 400--499 is received.  For
 89   backwards compatibility, the exception ``error_temp`` is equivalent to this
 90   class.
 91
 92
 93.. exception:: NNTPPermanentError
 94
 95   Exception raised when an error code in the range 500--599 is received.  For
 96   backwards compatibility, the exception ``error_perm`` is equivalent to this
 97   class.
 98
 99
100.. exception:: NNTPProtocolError
101
102   Exception raised when a reply is received from the server that does not begin
103   with a digit in the range 1--5.  For backwards compatibility, the exception
104   ``error_proto`` is equivalent to this class.
105
106
107.. exception:: NNTPDataError
108
109   Exception raised when there is some error in the response data.  For backwards
110   compatibility, the exception ``error_data`` is equivalent to this class.
111
112
113.. _nntp-objects:
114
115NNTP Objects
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
124.. 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
131.. 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
141.. 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
154.. 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
166.. 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
181.. 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
191.. 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
203.. 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
212.. 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
223.. 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
231.. method:: NNTP.next()
232
233   Send a ``NEXT`` command.  Return as for :meth:`stat`.
234
235
236.. method:: NNTP.last()
237
238   Send a ``LAST`` command.  Return as for :meth:`stat`.
239
240
241.. 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
249.. 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
259.. 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
265.. method:: NNTP.slave()
266
267   Send a ``SLAVE`` command.  Return the server's *response*.
268
269
270.. 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
286.. 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
294.. 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
301.. 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
308.. 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
319   RFC2980 says "It is suggested that this extension be deprecated".  Use
320   :meth:`descriptions` or :meth:`description` instead.
321
322
323.. method:: NNTP.xover(start, end, [file])
324
325   Return a pair ``(resp, list)``.  *list* is a list of tuples, one for each
326   article in the range delimited by the *start* and *end* article numbers.  Each
327   tuple is of the form ``(article number, subject, poster, date, id, references,
328   size, lines)``. If the *file* parameter is supplied, then the output of the
329   ``XOVER`` command is stored in a file.  If *file* is a string,  then the method
330   will open a file object with that name, write to it  then close it.  If *file*
331   is a file object, then it will start calling :meth:`write` on it to store the
332   lines of the command output. If *file* is supplied, then the returned *list* is
333   an empty list. This is an optional NNTP extension, and may not be supported by
334   all servers.
335
336
337.. method:: NNTP.xpath(id)
338
339   Return a pair ``(resp, path)``, where *path* is the directory path to the
340   article with message ID *id*.  This is an optional NNTP extension, and may not
341   be supported by all servers.
342
343
344.. method:: NNTP.quit()
345
346   Send a ``QUIT`` command and close the connection.  Once this method has been
347   called, no other methods of the NNTP object should be called.
348