Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | """An NNTP client class based on RFC 977: Network News Transfer Protocol. |
2 | ||
3 | Example: | |
4 | ||
5 | >>> from nntplib import NNTP | |
6 | >>> s = NNTP('news') | |
7 | >>> resp, count, first, last, name = s.group('comp.lang.python') | |
8 | >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last | |
9 | Group comp.lang.python has 51 articles, range 5770 to 5821 | |
10 | >>> resp, subs = s.xhdr('subject', first + '-' + last) | |
11 | >>> resp = s.quit() | |
12 | >>> | |
13 | ||
14 | Here 'resp' is the server response line. | |
15 | Error responses are turned into exceptions. | |
16 | ||
17 | To post an article from a file: | |
18 | >>> f = open(filename, 'r') # file containing article, including header | |
19 | >>> resp = s.post(f) | |
20 | >>> | |
21 | ||
22 | For descriptions of all methods, read the comments in the code below. | |
23 | Note that all arguments and return values representing article numbers | |
24 | are strings, not numbers, since they are rarely used for calculations. | |
25 | """ | |
26 | ||
27 | # RFC 977 by Brian Kantor and Phil Lapsley. | |
28 | # xover, xgtitle, xpath, date methods by Kevan Heydon | |
29 | ||
30 | ||
31 | # Imports | |
32 | import re | |
33 | import socket | |
34 | ||
35 | __all__ = ["NNTP","NNTPReplyError","NNTPTemporaryError", | |
36 | "NNTPPermanentError","NNTPProtocolError","NNTPDataError", | |
37 | "error_reply","error_temp","error_perm","error_proto", | |
38 | "error_data",] | |
39 | ||
40 | # Exceptions raised when an error or invalid response is received | |
41 | class NNTPError(Exception): | |
42 | """Base class for all nntplib exceptions""" | |
43 | def __init__(self, *args): | |
44 | Exception.__init__(self, *args) | |
45 | try: | |
46 | self.response = args[0] | |
47 | except IndexError: | |
48 | self.response = 'No response given' | |
49 | ||
50 | class NNTPReplyError(NNTPError): | |
51 | """Unexpected [123]xx reply""" | |
52 | pass | |
53 | ||
54 | class NNTPTemporaryError(NNTPError): | |
55 | """4xx errors""" | |
56 | pass | |
57 | ||
58 | class NNTPPermanentError(NNTPError): | |
59 | """5xx errors""" | |
60 | pass | |
61 | ||
62 | class NNTPProtocolError(NNTPError): | |
63 | """Response does not begin with [1-5]""" | |
64 | pass | |
65 | ||
66 | class NNTPDataError(NNTPError): | |
67 | """Error in response data""" | |
68 | pass | |
69 | ||
70 | # for backwards compatibility | |
71 | error_reply = NNTPReplyError | |
72 | error_temp = NNTPTemporaryError | |
73 | error_perm = NNTPPermanentError | |
74 | error_proto = NNTPProtocolError | |
75 | error_data = NNTPDataError | |
76 | ||
77 | ||
78 | ||
79 | # Standard port used by NNTP servers | |
80 | NNTP_PORT = 119 | |
81 | ||
82 | ||
83 | # Response numbers that are followed by additional text (e.g. article) | |
84 | LONGRESP = ['100', '215', '220', '221', '222', '224', '230', '231', '282'] | |
85 | ||
86 | ||
87 | # Line terminators (we always output CRLF, but accept any of CRLF, CR, LF) | |
88 | CRLF = '\r\n' | |
89 | ||
90 | ||
91 | ||
92 | # The class itself | |
93 | class NNTP: | |
94 | def __init__(self, host, port=NNTP_PORT, user=None, password=None, | |
95 | readermode=None, usenetrc=True): | |
96 | """Initialize an instance. Arguments: | |
97 | - host: hostname to connect to | |
98 | - port: port to connect to (default the standard NNTP port) | |
99 | - user: username to authenticate with | |
100 | - password: password to use with username | |
101 | - readermode: if true, send 'mode reader' command after | |
102 | connecting. | |
103 | ||
104 | readermode is sometimes necessary if you are connecting to an | |
105 | NNTP server on the local machine and intend to call | |
106 | reader-specific comamnds, such as `group'. If you get | |
107 | unexpected NNTPPermanentErrors, you might need to set | |
108 | readermode. | |
109 | """ | |
110 | self.host = host | |
111 | self.port = port | |
112 | self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) | |
113 | self.sock.connect((self.host, self.port)) | |
114 | self.file = self.sock.makefile('rb') | |
115 | self.debugging = 0 | |
116 | self.welcome = self.getresp() | |
117 | ||
118 | # 'mode reader' is sometimes necessary to enable 'reader' mode. | |
119 | # However, the order in which 'mode reader' and 'authinfo' need to | |
120 | # arrive differs between some NNTP servers. Try to send | |
121 | # 'mode reader', and if it fails with an authorization failed | |
122 | # error, try again after sending authinfo. | |
123 | readermode_afterauth = 0 | |
124 | if readermode: | |
125 | try: | |
126 | self.welcome = self.shortcmd('mode reader') | |
127 | except NNTPPermanentError: | |
128 | # error 500, probably 'not implemented' | |
129 | pass | |
130 | except NNTPTemporaryError, e: | |
131 | if user and e.response[:3] == '480': | |
132 | # Need authorization before 'mode reader' | |
133 | readermode_afterauth = 1 | |
134 | else: | |
135 | raise | |
136 | # If no login/password was specified, try to get them from ~/.netrc | |
137 | # Presume that if .netc has an entry, NNRP authentication is required. | |
138 | try: | |
139 | if usenetrc and not user: | |
140 | import netrc | |
141 | credentials = netrc.netrc() | |
142 | auth = credentials.authenticators(host) | |
143 | if auth: | |
144 | user = auth[0] | |
145 | password = auth[2] | |
146 | except IOError: | |
147 | pass | |
148 | # Perform NNRP authentication if needed. | |
149 | if user: | |
150 | resp = self.shortcmd('authinfo user '+user) | |
151 | if resp[:3] == '381': | |
152 | if not password: | |
153 | raise NNTPReplyError(resp) | |
154 | else: | |
155 | resp = self.shortcmd( | |
156 | 'authinfo pass '+password) | |
157 | if resp[:3] != '281': | |
158 | raise NNTPPermanentError(resp) | |
159 | if readermode_afterauth: | |
160 | try: | |
161 | self.welcome = self.shortcmd('mode reader') | |
162 | except NNTPPermanentError: | |
163 | # error 500, probably 'not implemented' | |
164 | pass | |
165 | ||
166 | ||
167 | # Get the welcome message from the server | |
168 | # (this is read and squirreled away by __init__()). | |
169 | # If the response code is 200, posting is allowed; | |
170 | # if it 201, posting is not allowed | |
171 | ||
172 | def getwelcome(self): | |
173 | """Get the welcome message from the server | |
174 | (this is read and squirreled away by __init__()). | |
175 | If the response code is 200, posting is allowed; | |
176 | if it 201, posting is not allowed.""" | |
177 | ||
178 | if self.debugging: print '*welcome*', repr(self.welcome) | |
179 | return self.welcome | |
180 | ||
181 | def set_debuglevel(self, level): | |
182 | """Set the debugging level. Argument 'level' means: | |
183 | 0: no debugging output (default) | |
184 | 1: print commands and responses but not body text etc. | |
185 | 2: also print raw lines read and sent before stripping CR/LF""" | |
186 | ||
187 | self.debugging = level | |
188 | debug = set_debuglevel | |
189 | ||
190 | def putline(self, line): | |
191 | """Internal: send one line to the server, appending CRLF.""" | |
192 | line = line + CRLF | |
193 | if self.debugging > 1: print '*put*', repr(line) | |
194 | self.sock.sendall(line) | |
195 | ||
196 | def putcmd(self, line): | |
197 | """Internal: send one command to the server (through putline()).""" | |
198 | if self.debugging: print '*cmd*', repr(line) | |
199 | self.putline(line) | |
200 | ||
201 | def getline(self): | |
202 | """Internal: return one line from the server, stripping CRLF. | |
203 | Raise EOFError if the connection is closed.""" | |
204 | line = self.file.readline() | |
205 | if self.debugging > 1: | |
206 | print '*get*', repr(line) | |
207 | if not line: raise EOFError | |
208 | if line[-2:] == CRLF: line = line[:-2] | |
209 | elif line[-1:] in CRLF: line = line[:-1] | |
210 | return line | |
211 | ||
212 | def getresp(self): | |
213 | """Internal: get a response from the server. | |
214 | Raise various errors if the response indicates an error.""" | |
215 | resp = self.getline() | |
216 | if self.debugging: print '*resp*', repr(resp) | |
217 | c = resp[:1] | |
218 | if c == '4': | |
219 | raise NNTPTemporaryError(resp) | |
220 | if c == '5': | |
221 | raise NNTPPermanentError(resp) | |
222 | if c not in '123': | |
223 | raise NNTPProtocolError(resp) | |
224 | return resp | |
225 | ||
226 | def getlongresp(self, file=None): | |
227 | """Internal: get a response plus following text from the server. | |
228 | Raise various errors if the response indicates an error.""" | |
229 | ||
230 | openedFile = None | |
231 | try: | |
232 | # If a string was passed then open a file with that name | |
233 | if isinstance(file, str): | |
234 | openedFile = file = open(file, "w") | |
235 | ||
236 | resp = self.getresp() | |
237 | if resp[:3] not in LONGRESP: | |
238 | raise NNTPReplyError(resp) | |
239 | list = [] | |
240 | while 1: | |
241 | line = self.getline() | |
242 | if line == '.': | |
243 | break | |
244 | if line[:2] == '..': | |
245 | line = line[1:] | |
246 | if file: | |
247 | file.write(line + "\n") | |
248 | else: | |
249 | list.append(line) | |
250 | finally: | |
251 | # If this method created the file, then it must close it | |
252 | if openedFile: | |
253 | openedFile.close() | |
254 | ||
255 | return resp, list | |
256 | ||
257 | def shortcmd(self, line): | |
258 | """Internal: send a command and get the response.""" | |
259 | self.putcmd(line) | |
260 | return self.getresp() | |
261 | ||
262 | def longcmd(self, line, file=None): | |
263 | """Internal: send a command and get the response plus following text.""" | |
264 | self.putcmd(line) | |
265 | return self.getlongresp(file) | |
266 | ||
267 | def newgroups(self, date, time, file=None): | |
268 | """Process a NEWGROUPS command. Arguments: | |
269 | - date: string 'yymmdd' indicating the date | |
270 | - time: string 'hhmmss' indicating the time | |
271 | Return: | |
272 | - resp: server response if successful | |
273 | - list: list of newsgroup names""" | |
274 | ||
275 | return self.longcmd('NEWGROUPS ' + date + ' ' + time, file) | |
276 | ||
277 | def newnews(self, group, date, time, file=None): | |
278 | """Process a NEWNEWS command. Arguments: | |
279 | - group: group name or '*' | |
280 | - date: string 'yymmdd' indicating the date | |
281 | - time: string 'hhmmss' indicating the time | |
282 | Return: | |
283 | - resp: server response if successful | |
284 | - list: list of message ids""" | |
285 | ||
286 | cmd = 'NEWNEWS ' + group + ' ' + date + ' ' + time | |
287 | return self.longcmd(cmd, file) | |
288 | ||
289 | def list(self, file=None): | |
290 | """Process a LIST command. Return: | |
291 | - resp: server response if successful | |
292 | - list: list of (group, last, first, flag) (strings)""" | |
293 | ||
294 | resp, list = self.longcmd('LIST', file) | |
295 | for i in range(len(list)): | |
296 | # Parse lines into "group last first flag" | |
297 | list[i] = tuple(list[i].split()) | |
298 | return resp, list | |
299 | ||
300 | def description(self, group): | |
301 | ||
302 | """Get a description for a single group. If more than one | |
303 | group matches ('group' is a pattern), return the first. If no | |
304 | group matches, return an empty string. | |
305 | ||
306 | This elides the response code from the server, since it can | |
307 | only be '215' or '285' (for xgtitle) anyway. If the response | |
308 | code is needed, use the 'descriptions' method. | |
309 | ||
310 | NOTE: This neither checks for a wildcard in 'group' nor does | |
311 | it check whether the group actually exists.""" | |
312 | ||
313 | resp, lines = self.descriptions(group) | |
314 | if len(lines) == 0: | |
315 | return "" | |
316 | else: | |
317 | return lines[0][1] | |
318 | ||
319 | def descriptions(self, group_pattern): | |
320 | """Get descriptions for a range of groups.""" | |
321 | line_pat = re.compile("^(?P<group>[^ \t]+)[ \t]+(.*)$") | |
322 | # Try the more std (acc. to RFC2980) LIST NEWSGROUPS first | |
323 | resp, raw_lines = self.longcmd('LIST NEWSGROUPS ' + group_pattern) | |
324 | if resp[:3] != "215": | |
325 | # Now the deprecated XGTITLE. This either raises an error | |
326 | # or succeeds with the same output structure as LIST | |
327 | # NEWSGROUPS. | |
328 | resp, raw_lines = self.longcmd('XGTITLE ' + group_pattern) | |
329 | lines = [] | |
330 | for raw_line in raw_lines: | |
331 | match = line_pat.search(raw_line.strip()) | |
332 | if match: | |
333 | lines.append(match.group(1, 2)) | |
334 | return resp, lines | |
335 | ||
336 | def group(self, name): | |
337 | """Process a GROUP command. Argument: | |
338 | - group: the group name | |
339 | Returns: | |
340 | - resp: server response if successful | |
341 | - count: number of articles (string) | |
342 | - first: first article number (string) | |
343 | - last: last article number (string) | |
344 | - name: the group name""" | |
345 | ||
346 | resp = self.shortcmd('GROUP ' + name) | |
347 | if resp[:3] != '211': | |
348 | raise NNTPReplyError(resp) | |
349 | words = resp.split() | |
350 | count = first = last = 0 | |
351 | n = len(words) | |
352 | if n > 1: | |
353 | count = words[1] | |
354 | if n > 2: | |
355 | first = words[2] | |
356 | if n > 3: | |
357 | last = words[3] | |
358 | if n > 4: | |
359 | name = words[4].lower() | |
360 | return resp, count, first, last, name | |
361 | ||
362 | def help(self, file=None): | |
363 | """Process a HELP command. Returns: | |
364 | - resp: server response if successful | |
365 | - list: list of strings""" | |
366 | ||
367 | return self.longcmd('HELP',file) | |
368 | ||
369 | def statparse(self, resp): | |
370 | """Internal: parse the response of a STAT, NEXT or LAST command.""" | |
371 | if resp[:2] != '22': | |
372 | raise NNTPReplyError(resp) | |
373 | words = resp.split() | |
374 | nr = 0 | |
375 | id = '' | |
376 | n = len(words) | |
377 | if n > 1: | |
378 | nr = words[1] | |
379 | if n > 2: | |
380 | id = words[2] | |
381 | return resp, nr, id | |
382 | ||
383 | def statcmd(self, line): | |
384 | """Internal: process a STAT, NEXT or LAST command.""" | |
385 | resp = self.shortcmd(line) | |
386 | return self.statparse(resp) | |
387 | ||
388 | def stat(self, id): | |
389 | """Process a STAT command. Argument: | |
390 | - id: article number or message id | |
391 | Returns: | |
392 | - resp: server response if successful | |
393 | - nr: the article number | |
394 | - id: the message id""" | |
395 | ||
396 | return self.statcmd('STAT ' + id) | |
397 | ||
398 | def next(self): | |
399 | """Process a NEXT command. No arguments. Return as for STAT.""" | |
400 | return self.statcmd('NEXT') | |
401 | ||
402 | def last(self): | |
403 | """Process a LAST command. No arguments. Return as for STAT.""" | |
404 | return self.statcmd('LAST') | |
405 | ||
406 | def artcmd(self, line, file=None): | |
407 | """Internal: process a HEAD, BODY or ARTICLE command.""" | |
408 | resp, list = self.longcmd(line, file) | |
409 | resp, nr, id = self.statparse(resp) | |
410 | return resp, nr, id, list | |
411 | ||
412 | def head(self, id): | |
413 | """Process a HEAD command. Argument: | |
414 | - id: article number or message id | |
415 | Returns: | |
416 | - resp: server response if successful | |
417 | - nr: article number | |
418 | - id: message id | |
419 | - list: the lines of the article's header""" | |
420 | ||
421 | return self.artcmd('HEAD ' + id) | |
422 | ||
423 | def body(self, id, file=None): | |
424 | """Process a BODY command. Argument: | |
425 | - id: article number or message id | |
426 | - file: Filename string or file object to store the article in | |
427 | Returns: | |
428 | - resp: server response if successful | |
429 | - nr: article number | |
430 | - id: message id | |
431 | - list: the lines of the article's body or an empty list | |
432 | if file was used""" | |
433 | ||
434 | return self.artcmd('BODY ' + id, file) | |
435 | ||
436 | def article(self, id): | |
437 | """Process an ARTICLE command. Argument: | |
438 | - id: article number or message id | |
439 | Returns: | |
440 | - resp: server response if successful | |
441 | - nr: article number | |
442 | - id: message id | |
443 | - list: the lines of the article""" | |
444 | ||
445 | return self.artcmd('ARTICLE ' + id) | |
446 | ||
447 | def slave(self): | |
448 | """Process a SLAVE command. Returns: | |
449 | - resp: server response if successful""" | |
450 | ||
451 | return self.shortcmd('SLAVE') | |
452 | ||
453 | def xhdr(self, hdr, str, file=None): | |
454 | """Process an XHDR command (optional server extension). Arguments: | |
455 | - hdr: the header type (e.g. 'subject') | |
456 | - str: an article nr, a message id, or a range nr1-nr2 | |
457 | Returns: | |
458 | - resp: server response if successful | |
459 | - list: list of (nr, value) strings""" | |
460 | ||
461 | pat = re.compile('^([0-9]+) ?(.*)\n?') | |
462 | resp, lines = self.longcmd('XHDR ' + hdr + ' ' + str, file) | |
463 | for i in range(len(lines)): | |
464 | line = lines[i] | |
465 | m = pat.match(line) | |
466 | if m: | |
467 | lines[i] = m.group(1, 2) | |
468 | return resp, lines | |
469 | ||
470 | def xover(self, start, end, file=None): | |
471 | """Process an XOVER command (optional server extension) Arguments: | |
472 | - start: start of range | |
473 | - end: end of range | |
474 | Returns: | |
475 | - resp: server response if successful | |
476 | - list: list of (art-nr, subject, poster, date, | |
477 | id, references, size, lines)""" | |
478 | ||
479 | resp, lines = self.longcmd('XOVER ' + start + '-' + end, file) | |
480 | xover_lines = [] | |
481 | for line in lines: | |
482 | elem = line.split("\t") | |
483 | try: | |
484 | xover_lines.append((elem[0], | |
485 | elem[1], | |
486 | elem[2], | |
487 | elem[3], | |
488 | elem[4], | |
489 | elem[5].split(), | |
490 | elem[6], | |
491 | elem[7])) | |
492 | except IndexError: | |
493 | raise NNTPDataError(line) | |
494 | return resp,xover_lines | |
495 | ||
496 | def xgtitle(self, group, file=None): | |
497 | """Process an XGTITLE command (optional server extension) Arguments: | |
498 | - group: group name wildcard (i.e. news.*) | |
499 | Returns: | |
500 | - resp: server response if successful | |
501 | - list: list of (name,title) strings""" | |
502 | ||
503 | line_pat = re.compile("^([^ \t]+)[ \t]+(.*)$") | |
504 | resp, raw_lines = self.longcmd('XGTITLE ' + group, file) | |
505 | lines = [] | |
506 | for raw_line in raw_lines: | |
507 | match = line_pat.search(raw_line.strip()) | |
508 | if match: | |
509 | lines.append(match.group(1, 2)) | |
510 | return resp, lines | |
511 | ||
512 | def xpath(self,id): | |
513 | """Process an XPATH command (optional server extension) Arguments: | |
514 | - id: Message id of article | |
515 | Returns: | |
516 | resp: server response if successful | |
517 | path: directory path to article""" | |
518 | ||
519 | resp = self.shortcmd("XPATH " + id) | |
520 | if resp[:3] != '223': | |
521 | raise NNTPReplyError(resp) | |
522 | try: | |
523 | [resp_num, path] = resp.split() | |
524 | except ValueError: | |
525 | raise NNTPReplyError(resp) | |
526 | else: | |
527 | return resp, path | |
528 | ||
529 | def date (self): | |
530 | """Process the DATE command. Arguments: | |
531 | None | |
532 | Returns: | |
533 | resp: server response if successful | |
534 | date: Date suitable for newnews/newgroups commands etc. | |
535 | time: Time suitable for newnews/newgroups commands etc.""" | |
536 | ||
537 | resp = self.shortcmd("DATE") | |
538 | if resp[:3] != '111': | |
539 | raise NNTPReplyError(resp) | |
540 | elem = resp.split() | |
541 | if len(elem) != 2: | |
542 | raise NNTPDataError(resp) | |
543 | date = elem[1][2:8] | |
544 | time = elem[1][-6:] | |
545 | if len(date) != 6 or len(time) != 6: | |
546 | raise NNTPDataError(resp) | |
547 | return resp, date, time | |
548 | ||
549 | ||
550 | def post(self, f): | |
551 | """Process a POST command. Arguments: | |
552 | - f: file containing the article | |
553 | Returns: | |
554 | - resp: server response if successful""" | |
555 | ||
556 | resp = self.shortcmd('POST') | |
557 | # Raises error_??? if posting is not allowed | |
558 | if resp[0] != '3': | |
559 | raise NNTPReplyError(resp) | |
560 | while 1: | |
561 | line = f.readline() | |
562 | if not line: | |
563 | break | |
564 | if line[-1] == '\n': | |
565 | line = line[:-1] | |
566 | if line[:1] == '.': | |
567 | line = '.' + line | |
568 | self.putline(line) | |
569 | self.putline('.') | |
570 | return self.getresp() | |
571 | ||
572 | def ihave(self, id, f): | |
573 | """Process an IHAVE command. Arguments: | |
574 | - id: message-id of the article | |
575 | - f: file containing the article | |
576 | Returns: | |
577 | - resp: server response if successful | |
578 | Note that if the server refuses the article an exception is raised.""" | |
579 | ||
580 | resp = self.shortcmd('IHAVE ' + id) | |
581 | # Raises error_??? if the server already has it | |
582 | if resp[0] != '3': | |
583 | raise NNTPReplyError(resp) | |
584 | while 1: | |
585 | line = f.readline() | |
586 | if not line: | |
587 | break | |
588 | if line[-1] == '\n': | |
589 | line = line[:-1] | |
590 | if line[:1] == '.': | |
591 | line = '.' + line | |
592 | self.putline(line) | |
593 | self.putline('.') | |
594 | return self.getresp() | |
595 | ||
596 | def quit(self): | |
597 | """Process a QUIT command and close the socket. Returns: | |
598 | - resp: server response if successful""" | |
599 | ||
600 | resp = self.shortcmd('QUIT') | |
601 | self.file.close() | |
602 | self.sock.close() | |
603 | del self.file, self.sock | |
604 | return resp | |
605 | ||
606 | ||
607 | # Test retrieval when run as a script. | |
608 | # Assumption: if there's a local news server, it's called 'news'. | |
609 | # Assumption: if user queries a remote news server, it's named | |
610 | # in the environment variable NNTPSERVER (used by slrn and kin) | |
611 | # and we want readermode off. | |
612 | if __name__ == '__main__': | |
613 | import os | |
614 | newshost = 'news' and os.environ["NNTPSERVER"] | |
615 | if newshost.find('.') == -1: | |
616 | mode = 'readermode' | |
617 | else: | |
618 | mode = None | |
619 | s = NNTP(newshost, readermode=mode) | |
620 | resp, count, first, last, name = s.group('comp.lang.python') | |
621 | print resp | |
622 | print 'Group', name, 'has', count, 'articles, range', first, 'to', last | |
623 | resp, subs = s.xhdr('subject', first + '-' + last) | |
624 | print resp | |
625 | for item in subs: | |
626 | print "%7s %s" % item | |
627 | resp = s.quit() | |
628 | print resp |