"""An NNTP client class. Based on RFC 977: Network News Transfer Protocol, by Brian Kantor and Phil Lapsley; and successor drafts. This is a modified version of the nntplib.py module that appeared in Python 1.5.2. As such, you may use it in accordance with the terms that Python itself is distributed. See your Python distribution for details. Usage: >>> from nntpclient import NNTP >>> s = NNTP('news') >>> resp, count, first, last, name = s.group('comp.lang.python') >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last Group comp.lang.python has 51 articles, range 5770 to 5821 >>> resp, subs = s.xhdr('subject', first + '-' + last) >>> resp = s.quit() >>> Here 'resp' is the server response line. Error responses are turned into exceptions. To post an article from a file: >>> f = open(filename, 'r') # file containing article, including header >>> resp = s.post(f) >>> For descriptions of all methods, read the comments in the code below. Note that all arguments and return values representing article numbers are strings, not numbers, since they are rarely used for calculations. Changes: - xover, xgtitle, xpath, date methods by Kevan Heydon - LIST and XOVER extensions, MODE, CHECK/TAKETHIS and extension discovery by G.J. Andruk. """ # Imports import re, socket, string, sys from types import * # Exceptions raised when an error or invalid response is received error_reply = 'nntplib.error_reply' # unexpected [123]xx reply error_temp = 'nntplib.error_temp' # 4xx errors error_perm = 'nntplib.error_perm' # 5xx errors error_proto = 'nntplib.error_proto' # response does not begin with [1-5] error_data = 'nntplib.error_data' # error in response data # Standard port used by NNTP servers NNTP_PORT = 119 # Response numbers that are followed by additional text (e.g. article) LONGRESP = ['100', '202', '211', '215', '220', '221', '222', '224', '230', '231', '282'] # Line terminators (we always output CRLF, but accept any of CRLF, CR, LF) CRLF = '\015\012' # The class itself class NNTP: def __init__(self, host, port = NNTP_PORT, user=None, password=None, discovery=0): """Initialize an instance. Arguments: host: hostname to connect to port: port to connect to (default the standard NNTP port) """ self.host = host self.port = port self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self.sock.connect((self.host, self.port)) self.file = self.sock.makefile('rb') self.debugging = 0 self.extensions = {} self.welcome = self.getresp() self.groupname = None if user: self.authinfo(user, password) if discovery: self.discovery() # Yeesh, that sounds so touchy-feely! def capability(self, command, longcmd=0): """Return the response code elicited by command. This is used by the discovery method to see if commands are implemented. """ self.putcmd(command) try: if longcmd: resp = self.getlongresp() else: resp = self.getresp() return resp[0][:3] except: return sys.exc_info()[1][:3] def discovery(self): """Learn what this server can do beyond RFC-977. Most current news servers implement a superset of NNTP, but they don't all support the same extensions. We try all the ones we care about, and record what's available. If you don't do a discovery or the required features are unavailable, we will emulate commands like XOVER and XHDR using the slow and painful (but standard) HEAD command. The self.extensions dictionary will contain a key for each supported extension. The ones beginning with an underscore are that way to avoid conflicts with the LIST EXTENSIONS command which is expected to appear in the successor to RFC-977. """ try: extensions = self.list('EXTENSIONS') for key in extensions: self.extensions[key] = None except: pass if self.extensions.has_key('OVER'): self.extensions['_XOVER'] = None else: if self.capability('XOVER', 1)[0] != '5': self.extensions['_XOVER'] = None if self.extensions.has_key('PAT'): self.extensions['_XPAT'] = None self.extensions['_XHDR'] = None else: if self.capability('XHDR', 1) == '501': self.extensions['_XHDR'] = None if self.capability('XPAT', 1) == '501': self.extensions['_XPAT'] = None if self.capability('XGTITLE meow', 1)[1] == '8': self.extensions['_XGTITLE'] = None if self.capability('LIST ACTIVE meow', 1) == '215': self.extensions['_LIST_ACTIVE'] = None if self.capability('LIST NEWSGROUPS meow', 1) == '215': self.extensions['_LIST_NEWSGROUPS_WILD'] = None def getwelcome(self): """Get the welcome message from the server (this is read and squirreled away by __init__()). If the response code is 200, posting is allowed; if 201, posting is not allowed """ if self.debugging: print '*welcome*', `self.welcome` return self.welcome def set_debuglevel(self, level): """Set the debugging level. Argument level means: 0: no debugging output (default) 1: print commands and responses but not body text etc. 2: also print raw lines read and sent before stripping CR/LF """ self.debugging = level debug = set_debuglevel def putline(self, line): """Internal: send one line to the server, appending CRLF""" line = line + CRLF if self.debugging > 1: print '*put*', `line` self.sock.send(line) def putcmd(self, line): """Internal: send one command to the server (through putline())""" if self.debugging: print '*cmd*', `line` self.putline(line) def getline(self): """Internal: return one line from the server, stripping CRLF. Raise EOFError if the connection is closed """ line = self.file.readline() if self.debugging > 1: print '*get*', `line` if not line: raise EOFError if line[-2:] == CRLF: line = line[:-2] elif line[-1:] in CRLF: line = line[:-1] return line def getresp(self): """Internal: get a response from the server. Raise various errors if the response indicates an error """ resp = self.getline() if self.debugging: print '*resp*', `resp` c = resp[:1] if c == '4': raise error_temp, resp if c == '5': raise error_perm, resp if c not in '123': raise error_proto, resp return resp def getlongresp(self): """Internal: get a response plus following text from the server. Raise various errors if the response indicates an error """ resp = self.getresp() if resp[:3] not in LONGRESP: raise error_reply, resp list = [] while 1: line = self.getline() if line == '.': break if line[:2] == '..': line = line[1:] list.append(line) return resp, list def shortcmd(self, line): """Internal: send a command and get the response""" self.putcmd(line) return self.getresp() def longcmd(self, line): """Internal: send a command and get the response plus following text""" self.putcmd(line) return self.getlongresp() def newgroups(self, date, time): """Process a NEWGROUPS command. Arguments: - date: string '[yy]yymmdd' indicating the date - time: string 'hhmmss' indicating the time Return: - resp: server response if succesful - list: list of newsgroup names """ return self.longcmd('NEWGROUPS ' + date + ' ' + time) def newnews(self, group, date, time): """Process a NEWNEWS command Arguments: - group: group name or wildmat pattern - date: string 'yymmdd' indicating the date - time: string 'hhmmss' indicating the time Return: - resp: server response if succesful - list: list of article ids """ cmd = 'NEWNEWS ' + group + ' ' + date + ' ' + time return self.longcmd(cmd) def list(self, params=None): """Process a LIST command. The LIST command as defined in RFC-977 takes no params and returns the entire group list. All other forms are extensions. Return: - resp: server response if succesful - list: if params == None or params == ('active',. . . ): list of (group, last, first, flag) (strings) elif params == ('newsgroups',. . . ): list of (group, description) (strings) elif params == ('distributions',. . . ): list of (dist, description) (strings) elif params == ('active.times',): list of (group, create-time, creator) (strings) elif params == ('distrib.pats',): list of (weight, pattern, value) (strings) elif params == ('moderators',): list of (group-pattern, mail-pattern) (strings) else: # motd, subscriptions, overview.fmt, any others list of 'raw' listing strings Icky hack: If you want to skip the string splitting stuff, sneak a space info the first param, as in: list('NEWSGROUPS ') """ if params == None: resp, list = self.longcmd('LIST') for i in range(len(list)): list[i] = string.split(list[i]) else: if type(params) not in (TupleType, ListType): params = (params,) param0 = string.upper(params[0]) resp, list = self.longcmd('LIST '+ string.join(params)) if param0 == 'ACTIVE': for i in range(len(list)): list[i] = string.split(list[i]) elif param0 in ('NEWSGROUPS', 'DISTRIBUTIONS'): for i in range(len(list)): list[i] = string.split(list[i], None, 1) elif param0 == 'DISTRIB.PATS': for i in range(len(list)): list[i] = string.split(list[i], ':', 2) elif param0 == 'MODERATORS': for i in range(len(list)): list[i] = string.split(list[i], ':', 1) elif param0 == 'ACTIVE.TIMES': for i in range(len(list)): list[i] = string.split(list[i], None, 2) return resp, list def group(self, name): """Process a GROUP command. Argument: - group: the group name Returns: - resp: server response if succesful - count: number of articles (string) - first: first article number (string) - last: last article number (string) - name: the group name """ resp = self.shortcmd('GROUP ' + name) if resp[:3] <> '211': raise error_reply, resp words = string.split(resp) count = first = last = 0 n = len(words) if n > 1: count = words[1] if n > 2: first = words[2] if n > 3: last = words[3] if n > 4: self.groupname = string.lower(words[4]) return resp, count, first, last, self.groupname def listgroup(self, name=None): """Process a LISTGROUP command (common extension) Argument: - group: the group name Returns: - resp: server response if succesful - list: list of available article numbers (strings) """ if name == None: resp, list = self.longcmd('LISTGROUP') else: resp, list = self.longcmd('LISTGROUP ' + name) if resp[:3] <> '211': raise error_reply, resp return resp, list def help(self): """Process a HELP command. Returns: - resp: server response if succesful - list: list of strings """ return self.longcmd('HELP') def statparse(self, resp): """Internal: parse the response of a STAT, NEXT or LAST command""" if resp[:2] <> '22': raise error_reply, resp words = string.split(resp) nr = 0 id = '' n = len(words) if n > 1: nr = words[1] if n > 2: id = words[2] return resp, nr, id def statcmd(self, line): """Internal: process a STAT, NEXT or LAST command""" resp = self.shortcmd(line) return self.statparse(resp) def stat(self, id=None): """Process a STAT command. Argument: - id: article number or message id Returns: - resp: server response if succesful - nr: the article number - id: the article id """ if id == None: return self.statcmd('STAT') else: return self.statcmd('STAT ' + id) def next(self): """Process a NEXT command. No arguments. Return as for STAT""" return self.statcmd('NEXT') def last(self): """Process a LAST command. No arguments. Return as for STAT""" return self.statcmd('LAST') def artcmd(self, line): """Internal: process a HEAD, BODY or ARTICLE command""" resp, list = self.longcmd(line) resp, nr, id = self.statparse(resp) return resp, nr, id, list def head(self, id=None): """Process a HEAD command. Argument: - id: article number or message id Returns: - resp: server response if succesful - nr: article number - id: message id - list: the lines of the article's header """ if id == None: return self.artcmd('HEAD') else: return self.artcmd('HEAD ' + id) def body(self, id=None): """Process a BODY command. Argument: - id: article number or message id Returns: - resp: server response if succesful - nr: article number - id: message id - list: the lines of the article's body """ if id == None: return self.artcmd('BODY') else: return self.artcmd('BODY ' + id) def article(self, id=None): """Process an ARTICLE command. Argument: - id: article number or message id Returns: - resp: server response if succesful - nr: article number - id: message id - list: the lines of the article """ if id == None: return self.artcmd('ARTICLE') else: return self.artcmd('ARTICLE ' + id) def slave(self): """Process a SLAVE command This command is deprecated. It was not completely defined in RFC-977, so implementations are rare and inconsistent. Returns: - resp: server response if succesful """ return self.shortcmd('SLAVE') def mode(self, modename): """Process a MODE command The most common modename is 'READER', used with INN to switch from innd to nnrpd. Returns: - resp: server response if succesful """ return self.shortcmd('MODE ' + modename) def xhdr(self, hdr, str, xpat=None): """Process an XHDR or XPAT command (optional server extensions). Arguments: - hdr: the header type (e.g. 'subject') - str: an article nr, a message id, or a range nr1-nr2 - xpat: if present, a wildmat for selecting articles - ianaext: if true, use OVER instead of XOVER/XPAT Returns: - resp: server response if succesful - list: list of (nr, value) strings """ if len(str) and '<' in str[0]: pat = re.compile('^(<[^>]+>) ?(.*)\n?') else: pat = re.compile('^([0-9]+) ?(.*)\n?') if self.extensions.has_key('PAT'): if xpat: resp, lines = self.longcmd('PAT %s %s %s' % (hdr, str, xpat)) else: resp, lines = self.longcmd('PAT %s %s' % (hdr, str)) else: if xpat: resp, lines = self.longcmd('XPAT %s %s %s' % (hdr, str, xpat)) else: resp, lines = self.longcmd('XHDR %s %s' % (hdr, str)) for i in range(len(lines)): line = lines[i] m = pat.match(line) if m: lines[i] = m.group(1, 2) return resp, lines ## def fakexover(self, start=None, end=None): ## """Emulate XOVER using the HEAD command ## Arguments: ## - start: start of range (string) ## - end: end of range (string) ## If start is None, return for current article only. ## If start is a string and end is None, return for start only. ## Returns: ## - resp: "224 emulated overview" if we are successful. ## - list: list of (artnum, subject, from, date, message-id, ## references, bytes, lines, extra{}) ## extra is a dictionary ## of {'header-name': 'value', . . .} ## containing all the headers not in the standard ## XOVER list. ## The bytes field always returns zero. Fixing this would ## require using ARTICLE instead of HEAD, defeating the point of ## this exercise. ## """ ## if start == None: ## startnum = -1 ## else: ## startnum = int(start) ## if end == None: ## endnum = startnum + 1 ## else: ## endnum = int(end) + 1 ## xover_lines = [] ## self.stat() # to make sure we are in a group def xover(self, start=None, end=None): """Process an XOVER command (optional server extension) Arguments: - start: start of range (string) - end: end of range (string) If start is None, return for current article only. If start is a string and end is None, return for start only. Note that some b0rken XOVER implementations may not support the above two variations. For maximum happiness, always supply a start and end. Returns: - resp: server response if succesful - list: list of (artnum, subject, from, date, message-id, references, bytes, lines, extra{}) extra is a (possibly empty) dictionary of {'header-name': 'value', . . .} for grabbing extended NOV info like Xref:. TODO: support overview.fmt; right now we assume that all extension fields will include the keyword; this ain't necessarily so in newer implementations, though it's supposed to be that way in the original NOV spec. """ if end == None: if start == None: params = '' else: params = start else: params = start + '-' + end if self.extensions.has_key('OVER'): resp, lines = self.longcmd('OVER' + params) else: resp, lines = self.longcmd('XOVER ' + params) xover_lines = [] for line in lines: elem = string.splitfields(line,"\t") try: extrastuff = {} if len(elem) > 8: for extra in range(8, len(elem)): hname, hcontent = string.split(elem[extra], ':', 1) ##if hname == 'Xref': ## extrastuff[hname] = string.split(hcontent) ##else: extrastuff[hname] = string.lstrip(hcontent) xover_lines.append((elem[0], elem[1], elem[2], elem[3], elem[4], string.split(elem[5]), elem[6], elem[7], extrastuff)) except IndexError: raise error_data,line return resp,xover_lines def xgtitle(self, group=None): """Process an XGTITLE command (optional extension) This is an old ANU News hack. New code should use LIST NEWSGROUPS [pattern]. Arguments: - group: group name wildcard (i.e. news.*) Returns: - resp: server response if succesful - list: list of (name,title) strings """ line_pat = re.compile("^([^ \t]+)[ \t]+(.*)$") if group == None: resp, raw_lines = self.longcmd('XGTITLE') else: resp, raw_lines = self.longcmd('XGTITLE ' + group) lines = [] for raw_line in raw_lines: match = line_pat.search(string.strip(raw_line)) if match: lines.append(match.group(1, 2)) return resp, lines def xpath(self, id): """Process an XPATH command (optional server extension) This command appeared in some versions of INN but shouldn't be relied on because of the variety of spools in use now. A more portable way to get this kind of info is the Xref: header. Arguments: - id: Message id of article Returns: resp: server response if succesful path: directory path to article """ resp = self.shortcmd("XPATH " + id) if resp[:3] <> '223': raise error_reply, resp try: [resp_num, path] = string.split(resp) except ValueError: raise error_reply, resp else: return resp, path def date (self): """Process the DATE command. Arguments: None Returns: resp: server response if succesful date: Date suitable for newnews/newgroups commands etc. time: Time suitable for newnews/newgroups commands etc. """ resp = self.shortcmd("DATE") if resp[:3] <> '111': raise error_reply, resp elem = string.split(resp) if len(elem) != 2: raise error_data, resp date = elem[1][2:8] time = elem[1][-6:] if len(date) != 6 or len(time) != 6: raise error_data, resp return resp, date, time def post(self, f): """Process a POST command. Arguments: - f: file containing the article Returns: - resp: server response if succesful """ resp = self.shortcmd('POST') # Raises error_??? if posting is not allowed if resp[0] <> '3': raise error_reply, resp while 1: line = f.readline() if not line: break if line[-1] == '\n': line = line[:-1] if line[:1] == '.': line = '.' + line self.putline(line) self.putline('.') return self.getresp() def ihave(self, id, f): """Process an IHAVE command. Arguments: - id: message-id of the article - f: file containing the article Returns: - resp: server response if succesful Note that if the server refuses the article an exception is raised """ resp = self.shortcmd('IHAVE ' + id) # Raises error_??? if the server already has it if resp[0] <> '3': raise error_reply, resp while 1: line = f.readline() if not line: break if line[-1] == '\n': line = line[:-1] if line[:1] == '.': line = '.' + line self.putline(line) self.putline('.') return self.getresp() def check(self, id): """Process a CHECK command (common extension) Generally used with streaming transfers. Like STAT, but reserves the message ID for us to send on success. This is a lame implementation; CHECK works best when the requests are batched up, but we would have to do async I/O to do that. Don't try to use this unless you've done a mode("STREAM") and it was successful. Returns: - resp: server response if succesful, will include id. A failed CHECK (server doesn't want the article) will raise an exception. """ return self.shortcmd('CHECK ' + id) def takethis(self, id, f): """Process a TAKETHIS command (common extension) Ideally this and CHECK would work asynchronously, but hey. Don't try to use this unless you've done a mode("STREAM") and it was successful. Arguments: - id: message-id of the article - f: file containing the article Returns: - resp: server response if succesful Note that on rejection or error an exception is raised. """ self.putcmd('TAKETHIS ' + id) # Yes, there is no response here. while 1: line = f.readline() if not line: break if line[-1] == '\n': line = line[:-1] if line[:1] == '.': line = '.' + line self.putline(line) self.putline('.') return self.getresp() def authinfo(self, user, password, authtype='ORIG'): """ Log into an NNTP server (common extension). Arguments: - user: username - password: You guessed it, password! - authtype: 'ORIG' or 'SIMPLE' ORIG is the AUTHINFO used by the vast majority of servers and clients. In most cases, this is the one you want. AUTHINFO SIMPLE is an alternative implementation supported by INN. """ authtype = string.upper(authtype) if authtype == 'ORIG': resp = self.shortcmd('AUTHINFO USER '+ user) if resp[:3] == '381': if not password: raise error_reply, resp else: resp = self.shortcmd('AUTHINFO PASS '+ password) if resp[:3] != '281': raise error_perm, resp elif authtype == 'SIMPLE': resp = self.shortcmd('AUTHINFO SIMPLE') if resp[:3] == '350': resp = self.shortcmd(user + ' ' + password) if resp[:3] != '250': raise error_perm, resp else: raise ValueError, 'Unsupported authtype' def quit(self): """Process a QUIT command and close the socket. Returns: - resp: server response if succesful """ resp = self.shortcmd('QUIT') self.file.close() self.sock.close() del self.file, self.sock return resp def _test(): """Minimal test function""" s = NNTP('localhost') resp, count, first, last, name = s.group('comp.lang.python') print resp print 'Group', name, 'has', count, 'articles, range', first, 'to', last resp, subs = s.xhdr('subject', first + '-' + last) print resp for item in subs: print "%7s %s" % item resp = s.quit() print resp # Run the test when run as a script if __name__ == '__main__': _test()