Lib/nntplib.py

   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 import string
  35
  36
  37 \f
  38 # Exceptions raised when an error or invalid response is received
  39 class NNTPError(Exception):
  40         """Base class for all nntplib exceptions"""
  41         def __init__(self, *args):
  42                 apply(Exception.__init__, (self,)+args)
  43                 try:
  44                         self.response = args[0]
  45                 except IndexError:
  46                         self.response = 'No response given'
  47
  48 class NNTPReplyError(NNTPError):
  49         """Unexpected [123]xx reply"""
  50         pass
  51
  52 class NNTPTemporaryError(NNTPError):
  53         """4xx errors"""
  54         pass
  55
  56 class NNTPPermanentError(NNTPError):
  57         """5xx errors"""
  58         pass
  59
  60 class NNTPProtocolError(NNTPError):
  61         """Response does not begin with [1-5]"""
  62         pass
  63
  64 class NNTPDataError(NNTPError):
  65         """Error in response data"""
  66         pass
  67
  68 # for backwards compatibility
  69 error_reply = NNTPReplyError
  70 error_temp = NNTPTemporaryError
  71 error_perm = NNTPPermanentError
  72 error_proto = NNTPProtocolError
  73 error_data = NNTPDataError
  74
  75
  76 \f
  77 # Standard port used by NNTP servers
  78 NNTP_PORT = 119
  79
  80
  81 # Response numbers that are followed by additional text (e.g. article)
  82 LONGRESP = ['100', '215', '220', '221', '222', '224', '230', '231', '282']
  83
  84
  85 # Line terminators (we always output CRLF, but accept any of CRLF, CR, LF)
  86 CRLF = '\r\n'
  87
  88
  89 \f
  90 # The class itself
  91 class NNTP:
  92         def __init__(self, host, port=NNTP_PORT, user=None, password=None,
  93                      readermode=None):
  94                 """Initialize an instance.  Arguments:
  95                 - host: hostname to connect to
  96                 - port: port to connect to (default the standard NNTP port)
  97                 - user: username to authenticate with
  98                 - password: password to use with username
  99                 - readermode: if true, send 'mode reader' command after
 100                               connecting.
 101
 102                 readermode is sometimes necessary if you are connecting to an
 103                 NNTP server on the local machine and intend to call
 104                 reader-specific comamnds, such as `group'.  If you get
 105                 unexpected NNTPPermanentErrors, you might need to set
 106                 readermode.
 107                 """
 108                 self.host = host
 109                 self.port = port
 110                 self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
 111                 self.sock.connect(self.host, self.port)
 112                 self.file = self.sock.makefile('rb')
 113                 self.debugging = 0
 114                 self.welcome = self.getresp()
 115                 if readermode:
 116                         try:
 117                                 self.welcome = self.shortcmd('mode reader')
 118                         except NNTPPermanentError:
 119                                 # error 500, probably 'not implemented'
 120                                 pass
 121                 if user:
 122                         resp = self.shortcmd('authinfo user '+user)
 123                         if resp[:3] == '381':
 124                                 if not password:
 125                                         raise NNTPReplyError(resp)
 126                                 else:
 127                                         resp = self.shortcmd(
 128                                                 'authinfo pass '+password)
 129                                         if resp[:3] != '281':
 130                                                 raise NNTPPermanentError(resp)
 131
 132         # Get the welcome message from the server
 133         # (this is read and squirreled away by __init__()).
 134         # If the response code is 200, posting is allowed;
 135         # if it 201, posting is not allowed
 136
 137         def getwelcome(self):
 138                 """Get the welcome message from the server
 139                 (this is read and squirreled away by __init__()).
 140                 If the response code is 200, posting is allowed;
 141                 if it 201, posting is not allowed."""
 142
 143                 if self.debugging: print '*welcome*', `self.welcome`
 144                 return self.welcome
 145
 146         def set_debuglevel(self, level):
 147                 """Set the debugging level.  Argument 'level' means:
 148                 0: no debugging output (default)
 149                 1: print commands and responses but not body text etc.
 150                 2: also print raw lines read and sent before stripping CR/LF"""
 151
 152                 self.debugging = level
 153         debug = set_debuglevel
 154
 155         def putline(self, line):
 156                 """Internal: send one line to the server, appending CRLF."""
 157                 line = line + CRLF
 158                 if self.debugging > 1: print '*put*', `line`
 159                 self.sock.send(line)
 160
 161         def putcmd(self, line):
 162                 """Internal: send one command to the server (through putline())."""
 163                 if self.debugging: print '*cmd*', `line`
 164                 self.putline(line)
 165
 166         def getline(self):
 167                 """Internal: return one line from the server, stripping CRLF.
 168                 Raise EOFError if the connection is closed."""
 169                 line = self.file.readline()
 170                 if self.debugging > 1:
 171                         print '*get*', `line`
 172                 if not line: raise EOFError
 173                 if line[-2:] == CRLF: line = line[:-2]
 174                 elif line[-1:] in CRLF: line = line[:-1]
 175                 return line
 176
 177         def getresp(self):
 178                 """Internal: get a response from the server.
 179                 Raise various errors if the response indicates an error."""
 180                 resp = self.getline()
 181                 if self.debugging: print '*resp*', `resp`
 182                 c = resp[:1]
 183                 if c == '4':
 184                         raise NNTPTemporaryError(resp)
 185                 if c == '5':
 186                         raise NNTPPermanentError(resp)
 187                 if c not in '123':
 188                         raise NNTPProtocolError(resp)
 189                 return resp
 190
 191         def getlongresp(self):
 192                 """Internal: get a response plus following text from the server.
 193                 Raise various errors if the response indicates an error."""
 194                 resp = self.getresp()
 195                 if resp[:3] not in LONGRESP:
 196                         raise NNTPReplyError(resp)
 197                 list = []
 198                 while 1:
 199                         line = self.getline()
 200                         if line == '.':
 201                                 break
 202                         if line[:2] == '..':
 203                                 line = line[1:]
 204                         list.append(line)
 205                 return resp, list
 206
 207         def shortcmd(self, line):
 208                 """Internal: send a command and get the response."""
 209                 self.putcmd(line)
 210                 return self.getresp()
 211
 212         def longcmd(self, line):
 213                 """Internal: send a command and get the response plus following text."""
 214                 self.putcmd(line)
 215                 return self.getlongresp()
 216
 217         def newgroups(self, date, time):
 218                 """Process a NEWGROUPS command.  Arguments:
 219                 - date: string 'yymmdd' indicating the date
 220                 - time: string 'hhmmss' indicating the time
 221                 Return:
 222                 - resp: server response if succesful
 223                 - list: list of newsgroup names"""
 224
 225                 return self.longcmd('NEWGROUPS ' + date + ' ' + time)
 226
 227         def newnews(self, group, date, time):
 228                 """Process a NEWNEWS command.  Arguments:
 229                 - group: group name or '*'
 230                 - date: string 'yymmdd' indicating the date
 231                 - time: string 'hhmmss' indicating the time
 232                 Return:
 233                 - resp: server response if succesful
 234                 - list: list of article ids"""
 235
 236                 cmd = 'NEWNEWS ' + group + ' ' + date + ' ' + time
 237                 return self.longcmd(cmd)
 238
 239         def list(self):
 240                 """Process a LIST command.  Return:
 241                 - resp: server response if succesful
 242                 - list: list of (group, last, first, flag) (strings)"""
 243
 244                 resp, list = self.longcmd('LIST')
 245                 for i in range(len(list)):
 246                         # Parse lines into "group last first flag"
 247                         list[i] = tuple(string.split(list[i]))
 248                 return resp, list
 249
 250         def group(self, name):
 251                 """Process a GROUP command.  Argument:
 252                 - group: the group name
 253                 Returns:
 254                 - resp: server response if succesful
 255                 - count: number of articles (string)
 256                 - first: first article number (string)
 257                 - last: last article number (string)
 258                 - name: the group name"""
 259
 260                 resp = self.shortcmd('GROUP ' + name)
 261                 if resp[:3] <> '211':
 262                         raise NNTPReplyError(resp)
 263                 words = string.split(resp)
 264                 count = first = last = 0
 265                 n = len(words)
 266                 if n > 1:
 267                         count = words[1]
 268                         if n > 2:
 269                                 first = words[2]
 270                                 if n > 3:
 271                                         last = words[3]
 272                                         if n > 4:
 273                                                 name = string.lower(words[4])
 274                 return resp, count, first, last, name
 275
 276         def help(self):
 277                 """Process a HELP command.  Returns:
 278                 - resp: server response if succesful
 279                 - list: list of strings"""
 280
 281                 return self.longcmd('HELP')
 282
 283         def statparse(self, resp):
 284                 """Internal: parse the response of a STAT, NEXT or LAST command."""
 285                 if resp[:2] <> '22':
 286                         raise NNTPReplyError(resp)
 287                 words = string.split(resp)
 288                 nr = 0
 289                 id = ''
 290                 n = len(words)
 291                 if n > 1:
 292                         nr = words[1]
 293                         if n > 2:
 294                                 id = words[2]
 295                 return resp, nr, id
 296
 297         def statcmd(self, line):
 298                 """Internal: process a STAT, NEXT or LAST command."""
 299                 resp = self.shortcmd(line)
 300                 return self.statparse(resp)
 301
 302         def stat(self, id):
 303                 """Process a STAT command.  Argument:
 304                 - id: article number or message id
 305                 Returns:
 306                 - resp: server response if succesful
 307                 - nr:   the article number
 308                 - id:   the article id"""
 309
 310                 return self.statcmd('STAT ' + id)
 311
 312         def next(self):
 313                 """Process a NEXT command.  No arguments.  Return as for STAT."""
 314                 return self.statcmd('NEXT')
 315
 316         def last(self):
 317                 """Process a LAST command.  No arguments.  Return as for STAT."""
 318                 return self.statcmd('LAST')
 319
 320         def artcmd(self, line):
 321                 """Internal: process a HEAD, BODY or ARTICLE command."""
 322                 resp, list = self.longcmd(line)
 323                 resp, nr, id = self.statparse(resp)
 324                 return resp, nr, id, list
 325
 326         def head(self, id):
 327                 """Process a HEAD command.  Argument:
 328                 - id: article number or message id
 329                 Returns:
 330                 - resp: server response if succesful
 331                 - nr: article number
 332                 - id: message id
 333                 - list: the lines of the article's header"""
 334
 335                 return self.artcmd('HEAD ' + id)
 336
 337         def body(self, id):
 338                 """Process a BODY command.  Argument:
 339                 - id: article number or message id
 340                 Returns:
 341                 - resp: server response if succesful
 342                 - nr: article number
 343                 - id: message id
 344                 - list: the lines of the article's body"""
 345
 346                 return self.artcmd('BODY ' + id)
 347
 348         def article(self, id):
 349                 """Process an ARTICLE command.  Argument:
 350                 - id: article number or message id
 351                 Returns:
 352                 - resp: server response if succesful
 353                 - nr: article number
 354                 - id: message id
 355                 - list: the lines of the article"""
 356
 357                 return self.artcmd('ARTICLE ' + id)
 358
 359         def slave(self):
 360                 """Process a SLAVE command.  Returns:
 361                 - resp: server response if succesful"""
 362
 363                 return self.shortcmd('SLAVE')
 364
 365         def xhdr(self, hdr, str):
 366                 """Process an XHDR command (optional server extension).  Arguments:
 367                 - hdr: the header type (e.g. 'subject')
 368                 - str: an article nr, a message id, or a range nr1-nr2
 369                 Returns:
 370                 - resp: server response if succesful
 371                 - list: list of (nr, value) strings"""
 372
 373                 pat = re.compile('^([0-9]+) ?(.*)\n?')
 374                 resp, lines = self.longcmd('XHDR ' + hdr + ' ' + str)
 375                 for i in range(len(lines)):
 376                         line = lines[i]
 377                         m = pat.match(line)
 378                         if m:
 379                                 lines[i] = m.group(1, 2)
 380                 return resp, lines
 381
 382         def xover(self,start,end):
 383                 """Process an XOVER command (optional server extension) Arguments:
 384                 - start: start of range
 385                 - end: end of range
 386                 Returns:
 387                 - resp: server response if succesful
 388                 - list: list of (art-nr, subject, poster, date,
 389                                  id, references, size, lines)"""
 390
 391                 resp, lines = self.longcmd('XOVER ' + start + '-' + end)
 392                 xover_lines = []
 393                 for line in lines:
 394                         elem = string.splitfields(line,"\t")
 395                         try:
 396                                 xover_lines.append((elem[0],
 397                                                     elem[1],
 398                                                     elem[2],
 399                                                     elem[3],
 400                                                     elem[4],
 401                                                     string.split(elem[5]),
 402                                                     elem[6],
 403                                                     elem[7]))
 404                         except IndexError:
 405                                 raise NNTPDataError(line)
 406                 return resp,xover_lines
 407
 408         def xgtitle(self, group):
 409                 """Process an XGTITLE command (optional server extension) Arguments:
 410                 - group: group name wildcard (i.e. news.*)
 411                 Returns:
 412                 - resp: server response if succesful
 413                 - list: list of (name,title) strings"""
 414
 415                 line_pat = re.compile("^([^ \t]+)[ \t]+(.*)$")
 416                 resp, raw_lines = self.longcmd('XGTITLE ' + group)
 417                 lines = []
 418                 for raw_line in raw_lines:
 419                         match = line_pat.search(string.strip(raw_line))
 420                         if match:
 421                                 lines.append(match.group(1, 2))
 422                 return resp, lines
 423
 424         def xpath(self,id):
 425                 """Process an XPATH command (optional server extension) Arguments:
 426                 - id: Message id of article
 427                 Returns:
 428                 resp: server response if succesful
 429                 path: directory path to article"""
 430
 431                 resp = self.shortcmd("XPATH " + id)
 432                 if resp[:3] <> '223':
 433                         raise NNTPReplyError(resp)
 434                 try:
 435                         [resp_num, path] = string.split(resp)
 436                 except ValueError:
 437                         raise NNTPReplyError(resp)
 438                 else:
 439                         return resp, path
 440
 441         def date (self):
 442                 """Process the DATE command. Arguments:
 443                 None
 444                 Returns:
 445                 resp: server response if succesful
 446                 date: Date suitable for newnews/newgroups commands etc.
 447                 time: Time suitable for newnews/newgroups commands etc."""
 448
 449                 resp = self.shortcmd("DATE")
 450                 if resp[:3] <> '111':
 451                         raise NNTPReplyError(resp)
 452                 elem = string.split(resp)
 453                 if len(elem) != 2:
 454                         raise NNTPDataError(resp)
 455                 date = elem[1][2:8]
 456                 time = elem[1][-6:]
 457                 if len(date) != 6 or len(time) != 6:
 458                         raise NNTPDataError(resp)
 459                 return resp, date, time
 460
 461
 462         def post(self, f):
 463                 """Process a POST command.  Arguments:
 464                 - f: file containing the article
 465                 Returns:
 466                 - resp: server response if succesful"""
 467
 468                 resp = self.shortcmd('POST')
 469                 # Raises error_??? if posting is not allowed
 470                 if resp[0] <> '3':
 471                         raise NNTPReplyError(resp)
 472                 while 1:
 473                         line = f.readline()
 474                         if not line:
 475                                 break
 476                         if line[-1] == '\n':
 477                                 line = line[:-1]
 478                         if line[:1] == '.':
 479                                 line = '.' + line
 480                         self.putline(line)
 481                 self.putline('.')
 482                 return self.getresp()
 483
 484         def ihave(self, id, f):
 485                 """Process an IHAVE command.  Arguments:
 486                 - id: message-id of the article
 487                 - f:  file containing the article
 488                 Returns:
 489                 - resp: server response if succesful
 490                 Note that if the server refuses the article an exception is raised."""
 491
 492                 resp = self.shortcmd('IHAVE ' + id)
 493                 # Raises error_??? if the server already has it
 494                 if resp[0] <> '3':
 495                         raise NNTPReplyError(resp)
 496                 while 1:
 497                         line = f.readline()
 498                         if not line:
 499                                 break
 500                         if line[-1] == '\n':
 501                                 line = line[:-1]
 502                         if line[:1] == '.':
 503                                 line = '.' + line
 504                         self.putline(line)
 505                 self.putline('.')
 506                 return self.getresp()
 507
 508         def quit(self):
 509                 """Process a QUIT command and close the socket.  Returns:
 510                 - resp: server response if succesful"""
 511
 512                 resp = self.shortcmd('QUIT')
 513                 self.file.close()
 514                 self.sock.close()
 515                 del self.file, self.sock
 516                 return resp
 517
 518
 519 def _test():
 520         """Minimal test function."""
 521         s = NNTP('news', readermode='reader')
 522         resp, count, first, last, name = s.group('comp.lang.python')
 523         print resp
 524         print 'Group', name, 'has', count, 'articles, range', first, 'to', last
 525         resp, subs = s.xhdr('subject', first + '-' + last)
 526         print resp
 527         for item in subs:
 528                 print "%7s %s" % item
 529         resp = s.quit()
 530         print resp
 531
 532
 533 # Run the test when run as a script
 534 if __name__ == '__main__':
 535         _test()