"""An NNTP client class based on RFC 977: Network News Transfer Protocol. | |
Example: | |
>>> from nntplib 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. | |
""" | |
# RFC 977 by Brian Kantor and Phil Lapsley. | |
# xover, xgtitle, xpath, date methods by Kevan Heydon | |
# Imports | |
import re | |
import socket | |
__all__ = ["NNTP","NNTPReplyError","NNTPTemporaryError", | |
"NNTPPermanentError","NNTPProtocolError","NNTPDataError", | |
"error_reply","error_temp","error_perm","error_proto", | |
"error_data",] | |
# Exceptions raised when an error or invalid response is received | |
class NNTPError(Exception): | |
"""Base class for all nntplib exceptions""" | |
def __init__(self, *args): | |
Exception.__init__(self, *args) | |
try: | |
self.response = args[0] | |
except IndexError: | |
self.response = 'No response given' | |
class NNTPReplyError(NNTPError): | |
"""Unexpected [123]xx reply""" | |
pass | |
class NNTPTemporaryError(NNTPError): | |
"""4xx errors""" | |
pass | |
class NNTPPermanentError(NNTPError): | |
"""5xx errors""" | |
pass | |
class NNTPProtocolError(NNTPError): | |
"""Response does not begin with [1-5]""" | |
pass | |
class NNTPDataError(NNTPError): | |
"""Error in response data""" | |
pass | |
# for backwards compatibility | |
error_reply = NNTPReplyError | |
error_temp = NNTPTemporaryError | |
error_perm = NNTPPermanentError | |
error_proto = NNTPProtocolError | |
error_data = NNTPDataError | |
# Standard port used by NNTP servers | |
NNTP_PORT = 119 | |
# Response numbers that are followed by additional text (e.g. article) | |
LONGRESP = ['100', '215', '220', '221', '222', '224', '230', '231', '282'] | |
# Line terminators (we always output CRLF, but accept any of CRLF, CR, LF) | |
CRLF = '\r\n' | |
# The class itself | |
class NNTP: | |
def __init__(self, host, port=NNTP_PORT, user=None, password=None, | |
readermode=None, usenetrc=True): | |
"""Initialize an instance. Arguments: | |
- host: hostname to connect to | |
- port: port to connect to (default the standard NNTP port) | |
- user: username to authenticate with | |
- password: password to use with username | |
- readermode: if true, send 'mode reader' command after | |
connecting. | |
readermode is sometimes necessary if you are connecting to an | |
NNTP server on the local machine and intend to call | |
reader-specific commands, such as `group'. If you get | |
unexpected NNTPPermanentErrors, you might need to set | |
readermode. | |
""" | |
self.host = host | |
self.port = port | |
self.sock = socket.create_connection((host, port)) | |
self.file = self.sock.makefile('rb') | |
self.debugging = 0 | |
self.welcome = self.getresp() | |
# 'mode reader' is sometimes necessary to enable 'reader' mode. | |
# However, the order in which 'mode reader' and 'authinfo' need to | |
# arrive differs between some NNTP servers. Try to send | |
# 'mode reader', and if it fails with an authorization failed | |
# error, try again after sending authinfo. | |
readermode_afterauth = 0 | |
if readermode: | |
try: | |
self.welcome = self.shortcmd('mode reader') | |
except NNTPPermanentError: | |
# error 500, probably 'not implemented' | |
pass | |
except NNTPTemporaryError, e: | |
if user and e.response[:3] == '480': | |
# Need authorization before 'mode reader' | |
readermode_afterauth = 1 | |
else: | |
raise | |
# If no login/password was specified, try to get them from ~/.netrc | |
# Presume that if .netc has an entry, NNRP authentication is required. | |
try: | |
if usenetrc and not user: | |
import netrc | |
credentials = netrc.netrc() | |
auth = credentials.authenticators(host) | |
if auth: | |
user = auth[0] | |
password = auth[2] | |
except IOError: | |
pass | |
# Perform NNRP authentication if needed. | |
if user: | |
resp = self.shortcmd('authinfo user '+user) | |
if resp[:3] == '381': | |
if not password: | |
raise NNTPReplyError(resp) | |
else: | |
resp = self.shortcmd( | |
'authinfo pass '+password) | |
if resp[:3] != '281': | |
raise NNTPPermanentError(resp) | |
if readermode_afterauth: | |
try: | |
self.welcome = self.shortcmd('mode reader') | |
except NNTPPermanentError: | |
# error 500, probably 'not implemented' | |
pass | |
# 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 it 201, posting is not allowed | |
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 it 201, posting is not allowed.""" | |
if self.debugging: print '*welcome*', repr(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*', repr(line) | |
self.sock.sendall(line) | |
def putcmd(self, line): | |
"""Internal: send one command to the server (through putline()).""" | |
if self.debugging: print '*cmd*', repr(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*', repr(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*', repr(resp) | |
c = resp[:1] | |
if c == '4': | |
raise NNTPTemporaryError(resp) | |
if c == '5': | |
raise NNTPPermanentError(resp) | |
if c not in '123': | |
raise NNTPProtocolError(resp) | |
return resp | |
def getlongresp(self, file=None): | |
"""Internal: get a response plus following text from the server. | |
Raise various errors if the response indicates an error.""" | |
openedFile = None | |
try: | |
# If a string was passed then open a file with that name | |
if isinstance(file, str): | |
openedFile = file = open(file, "w") | |
resp = self.getresp() | |
if resp[:3] not in LONGRESP: | |
raise NNTPReplyError(resp) | |
list = [] | |
while 1: | |
line = self.getline() | |
if line == '.': | |
break | |
if line[:2] == '..': | |
line = line[1:] | |
if file: | |
file.write(line + "\n") | |
else: | |
list.append(line) | |
finally: | |
# If this method created the file, then it must close it | |
if openedFile: | |
openedFile.close() | |
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, file=None): | |
"""Internal: send a command and get the response plus following text.""" | |
self.putcmd(line) | |
return self.getlongresp(file) | |
def newgroups(self, date, time, file=None): | |
"""Process a NEWGROUPS command. Arguments: | |
- date: string 'yymmdd' indicating the date | |
- time: string 'hhmmss' indicating the time | |
Return: | |
- resp: server response if successful | |
- list: list of newsgroup names""" | |
return self.longcmd('NEWGROUPS ' + date + ' ' + time, file) | |
def newnews(self, group, date, time, file=None): | |
"""Process a NEWNEWS command. Arguments: | |
- group: group name or '*' | |
- date: string 'yymmdd' indicating the date | |
- time: string 'hhmmss' indicating the time | |
Return: | |
- resp: server response if successful | |
- list: list of message ids""" | |
cmd = 'NEWNEWS ' + group + ' ' + date + ' ' + time | |
return self.longcmd(cmd, file) | |
def list(self, file=None): | |
"""Process a LIST command. Return: | |
- resp: server response if successful | |
- list: list of (group, last, first, flag) (strings)""" | |
resp, list = self.longcmd('LIST', file) | |
for i in range(len(list)): | |
# Parse lines into "group last first flag" | |
list[i] = tuple(list[i].split()) | |
return resp, list | |
def description(self, group): | |
"""Get a description for a single group. If more than one | |
group matches ('group' is a pattern), return the first. If no | |
group matches, return an empty string. | |
This elides the response code from the server, since it can | |
only be '215' or '285' (for xgtitle) anyway. If the response | |
code is needed, use the 'descriptions' method. | |
NOTE: This neither checks for a wildcard in 'group' nor does | |
it check whether the group actually exists.""" | |
resp, lines = self.descriptions(group) | |
if len(lines) == 0: | |
return "" | |
else: | |
return lines[0][1] | |
def descriptions(self, group_pattern): | |
"""Get descriptions for a range of groups.""" | |
line_pat = re.compile("^(?P<group>[^ \t]+)[ \t]+(.*)$") | |
# Try the more std (acc. to RFC2980) LIST NEWSGROUPS first | |
resp, raw_lines = self.longcmd('LIST NEWSGROUPS ' + group_pattern) | |
if resp[:3] != "215": | |
# Now the deprecated XGTITLE. This either raises an error | |
# or succeeds with the same output structure as LIST | |
# NEWSGROUPS. | |
resp, raw_lines = self.longcmd('XGTITLE ' + group_pattern) | |
lines = [] | |
for raw_line in raw_lines: | |
match = line_pat.search(raw_line.strip()) | |
if match: | |
lines.append(match.group(1, 2)) | |
return resp, lines | |
def group(self, name): | |
"""Process a GROUP command. Argument: | |
- group: the group name | |
Returns: | |
- resp: server response if successful | |
- 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 NNTPReplyError(resp) | |
words = resp.split() | |
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: | |
name = words[4].lower() | |
return resp, count, first, last, name | |
def help(self, file=None): | |
"""Process a HELP command. Returns: | |
- resp: server response if successful | |
- list: list of strings""" | |
return self.longcmd('HELP',file) | |
def statparse(self, resp): | |
"""Internal: parse the response of a STAT, NEXT or LAST command.""" | |
if resp[:2] != '22': | |
raise NNTPReplyError(resp) | |
words = resp.split() | |
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): | |
"""Process a STAT command. Argument: | |
- id: article number or message id | |
Returns: | |
- resp: server response if successful | |
- nr: the article number | |
- id: the message id""" | |
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, file=None): | |
"""Internal: process a HEAD, BODY or ARTICLE command.""" | |
resp, list = self.longcmd(line, file) | |
resp, nr, id = self.statparse(resp) | |
return resp, nr, id, list | |
def head(self, id): | |
"""Process a HEAD command. Argument: | |
- id: article number or message id | |
Returns: | |
- resp: server response if successful | |
- nr: article number | |
- id: message id | |
- list: the lines of the article's header""" | |
return self.artcmd('HEAD ' + id) | |
def body(self, id, file=None): | |
"""Process a BODY command. Argument: | |
- id: article number or message id | |
- file: Filename string or file object to store the article in | |
Returns: | |
- resp: server response if successful | |
- nr: article number | |
- id: message id | |
- list: the lines of the article's body or an empty list | |
if file was used""" | |
return self.artcmd('BODY ' + id, file) | |
def article(self, id): | |
"""Process an ARTICLE command. Argument: | |
- id: article number or message id | |
Returns: | |
- resp: server response if successful | |
- nr: article number | |
- id: message id | |
- list: the lines of the article""" | |
return self.artcmd('ARTICLE ' + id) | |
def slave(self): | |
"""Process a SLAVE command. Returns: | |
- resp: server response if successful""" | |
return self.shortcmd('SLAVE') | |
def xhdr(self, hdr, str, file=None): | |
"""Process an XHDR command (optional server extension). Arguments: | |
- hdr: the header type (e.g. 'subject') | |
- str: an article nr, a message id, or a range nr1-nr2 | |
Returns: | |
- resp: server response if successful | |
- list: list of (nr, value) strings""" | |
pat = re.compile('^([0-9]+) ?(.*)\n?') | |
resp, lines = self.longcmd('XHDR ' + hdr + ' ' + str, file) | |
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 xover(self, start, end, file=None): | |
"""Process an XOVER command (optional server extension) Arguments: | |
- start: start of range | |
- end: end of range | |
Returns: | |
- resp: server response if successful | |
- list: list of (art-nr, subject, poster, date, | |
id, references, size, lines)""" | |
resp, lines = self.longcmd('XOVER ' + start + '-' + end, file) | |
xover_lines = [] | |
for line in lines: | |
elem = line.split("\t") | |
try: | |
xover_lines.append((elem[0], | |
elem[1], | |
elem[2], | |
elem[3], | |
elem[4], | |
elem[5].split(), | |
elem[6], | |
elem[7])) | |
except IndexError: | |
raise NNTPDataError(line) | |
return resp,xover_lines | |
def xgtitle(self, group, file=None): | |
"""Process an XGTITLE command (optional server extension) Arguments: | |
- group: group name wildcard (i.e. news.*) | |
Returns: | |
- resp: server response if successful | |
- list: list of (name,title) strings""" | |
line_pat = re.compile("^([^ \t]+)[ \t]+(.*)$") | |
resp, raw_lines = self.longcmd('XGTITLE ' + group, file) | |
lines = [] | |
for raw_line in raw_lines: | |
match = line_pat.search(raw_line.strip()) | |
if match: | |
lines.append(match.group(1, 2)) | |
return resp, lines | |
def xpath(self,id): | |
"""Process an XPATH command (optional server extension) Arguments: | |
- id: Message id of article | |
Returns: | |
resp: server response if successful | |
path: directory path to article""" | |
resp = self.shortcmd("XPATH " + id) | |
if resp[:3] != '223': | |
raise NNTPReplyError(resp) | |
try: | |
[resp_num, path] = resp.split() | |
except ValueError: | |
raise NNTPReplyError(resp) | |
else: | |
return resp, path | |
def date (self): | |
"""Process the DATE command. Arguments: | |
None | |
Returns: | |
resp: server response if successful | |
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 NNTPReplyError(resp) | |
elem = resp.split() | |
if len(elem) != 2: | |
raise NNTPDataError(resp) | |
date = elem[1][2:8] | |
time = elem[1][-6:] | |
if len(date) != 6 or len(time) != 6: | |
raise NNTPDataError(resp) | |
return resp, date, time | |
def post(self, f): | |
"""Process a POST command. Arguments: | |
- f: file containing the article | |
Returns: | |
- resp: server response if successful""" | |
resp = self.shortcmd('POST') | |
# Raises error_??? if posting is not allowed | |
if resp[0] != '3': | |
raise NNTPReplyError(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 successful | |
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 NNTPReplyError(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 quit(self): | |
"""Process a QUIT command and close the socket. Returns: | |
- resp: server response if successful""" | |
resp = self.shortcmd('QUIT') | |
self.file.close() | |
self.sock.close() | |
del self.file, self.sock | |
return resp | |
# Test retrieval when run as a script. | |
# Assumption: if there's a local news server, it's called 'news'. | |
# Assumption: if user queries a remote news server, it's named | |
# in the environment variable NNTPSERVER (used by slrn and kin) | |
# and we want readermode off. | |
if __name__ == '__main__': | |
import os | |
newshost = 'news' and os.environ["NNTPSERVER"] | |
if newshost.find('.') == -1: | |
mode = 'readermode' | |
else: | |
mode = None | |
s = NNTP(newshost, readermode=mode) | |
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 |