|
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 |
|
13 This module defines the class :class:`NNTP` which implements the client side of |
|
14 the NNTP protocol. It can be used to implement a news reader or poster, or |
|
15 automated news processors. For more information on NNTP (Network News Transfer |
|
16 Protocol), see Internet :rfc:`977`. |
|
17 |
|
18 Here are two small examples of how it can be used. To list some statistics |
|
19 about 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 |
|
41 To post an article from a file (this assumes that the article has valid |
|
42 headers):: |
|
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 |
|
51 The 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 |
|
115 NNTP Objects |
|
116 ------------ |
|
117 |
|
118 NNTP instances have the following methods. The *response* that is returned as |
|
119 the first item in the return tuple of almost all methods is the server's |
|
120 response: a string beginning with a three-digit code. If the server's response |
|
121 indicates 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 |