Lib/nntplib.py

   1 # An NNTP client class.  Based on RFC 977: Network News Transfer
   2 # Protocol, by Brian Kantor and Phil Lapsley.
   3
   4
   5 # Example:
   6 #
   7 # >>> from nntplib import NNTP
   8 # >>> s = NNTP('charon')
   9 # >>> resp, count, first, last, name = s.group('nlnet.misc')
  10 # >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
  11 # Group nlnet.misc has 525 articles, range 6960 to 7485
  12 # >>> resp, subs = s.xhdr('subject', first + '-' + last)
  13 # >>> resp = s.quit()
  14 # >>>
  15 #
  16 # Here 'resp' is the server response line.
  17 # Error responses are turned into exceptions.
  18 #
  19 # To post an article from a file:
  20 # >>> f = open(filename, 'r') # file containing article, including header
  21 # >>> resp = s.post(f)
  22 # >>>
  23 #
  24 # For descriptions of all methods, read the comments in the code below.
  25 # Note that all arguments and return values representing article numbers
  26 # are strings, not numbers, since they are rarely used for calculations.
  27
  28
  29 # Imports
  30 import regex
  31 import socket
  32 import string
  33
  34
  35 # Exception raised when an error or invalid response is received
  36
  37 error_reply = 'nntplib.error_reply'     # unexpected [123]xx reply
  38 error_temp = 'nntplib.error_temp'       # 4xx errors
  39 error_perm = 'nntplib.error_perm'       # 5xx errors
  40 error_proto = 'nntplib.error_proto'     # response does not begin with [1-5]
  41
  42
  43 # Standard port used by NNTP servers
  44 NNTP_PORT = 119
  45
  46
  47 # Response numbers that are followed by additional text (e.g. article)
  48 LONGRESP = ['100', '215', '220', '221', '222', '230', '231']
  49
  50
  51 # Line terminators (we always output CRLF, but accept any of CRLF, CR, LF)
  52 CRLF = '\r\n'
  53
  54
  55 # The class itself
  56
  57 class NNTP:
  58
  59         # Initialize an instance.  Arguments:
  60         # - host: hostname to connect to
  61         # - port: port to connect to (default the standard NNTP port)
  62
  63         def __init__(self, host, port = NNTP_PORT):
  64                 self.host = host
  65                 self.port = port
  66                 self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
  67                 self.sock.connect(self.host, self.port)
  68                 self.file = self.sock.makefile('r')
  69                 self.debugging = 0
  70                 self.welcome = self.getresp()
  71
  72         # Get the welcome message from the server
  73         # (this is read and squirreled away by __init__()).
  74         # If the response code is 200, posting is allowed;
  75         # if it 201, posting is not allowed
  76
  77         def getwelcome(self):
  78                 if self.debugging: print '*welcome*', `self.welcome`
  79                 return self.welcome
  80
  81         # Set the debugging level.  Argument level means:
  82         # 0: no debugging output (default)
  83         # 1: print commands and responses but not body text etc.
  84         # 2: also print raw lines read and sent before stripping CR/LF
  85
  86         def debug(self, level):
  87                 self.debugging = level
  88
  89         # Internal: send one line to the server, appending CRLF
  90         def putline(self, line):
  91                 line = line + CRLF
  92                 if self.debugging > 1: print '*put*', `line`
  93                 self.sock.send(line)
  94
  95         # Internal: send one command to the server (through putline())
  96         def putcmd(self, line):
  97                 if self.debugging: print '*cmd*', `line`
  98                 self.putline(line)
  99
 100         # Internal: return one line from the server, stripping CRLF.
 101         # Raise EOFError if the connection is closed
 102         def getline(self):
 103                 line = self.file.readline()
 104                 if self.debugging > 1:
 105                         print '*get*', `line`
 106                 if not line: raise EOFError
 107                 if line[-2:] == CRLF: line = line[:-2]
 108                 elif line[-1:] in CRLF: line = line[:-1]
 109                 return line
 110
 111         # Internal: get a response from the server.
 112         # Raise various errors if the response indicates an error
 113         def getresp(self):
 114                 resp = self.getline()
 115                 if self.debugging: print '*resp*', `resp`
 116                 c = resp[:1]
 117                 if c == '4':
 118                         raise error_temp, resp
 119                 if c == '5':
 120                         raise error_perm, resp
 121                 if c not in '123':
 122                         raise error_proto, resp
 123                 return resp
 124
 125         # Internal: get a response plus following text from the server.
 126         # Raise various errors if the response indicates an error
 127         def getlongresp(self):
 128                 resp = self.getresp()
 129                 if resp[:3] not in LONGRESP:
 130                         raise error_reply, resp
 131                 list = []
 132                 while 1:
 133                         line = self.getline()
 134                         if line == '.':
 135                                 break
 136                         list.append(line)
 137                 return resp, list
 138
 139         # Internal: send a command and get the response
 140         def shortcmd(self, line):
 141                 self.putcmd(line)
 142                 return self.getresp()
 143
 144         # Internal: send a command and get the response plus following text
 145         def longcmd(self, line):
 146                 self.putcmd(line)
 147                 return self.getlongresp()
 148
 149         # Process a NEWGROUPS command.  Arguments:
 150         # - date: string 'yymmdd' indicating the date
 151         # - time: string 'hhmmss' indicating the time
 152         # Return:
 153         # - resp: server response if succesful
 154         # - list: list of newsgroup names
 155
 156         def newgroups(self, date, time):
 157                 return self.longcmd('NEWGROUPS ' + date + ' ' + time)
 158
 159         # Process a NEWNEWS command.  Arguments:
 160         # - group: group name or '*'
 161         # - date: string 'yymmdd' indicating the date
 162         # - time: string 'hhmmss' indicating the time
 163         # Return:
 164         # - resp: server response if succesful
 165         # - list: list of article ids
 166
 167         def newnews(self, group, date, time):
 168                 cmd = 'NEWNEWS ' + group + ' ' + date + ' ' + time
 169                 return self.longcmd(cmd)
 170
 171         # Process a LIST command.  Return:
 172         # - resp: server response if succesful
 173         # - list: list of (group, last, first, flag) (strings)
 174
 175         def list(self):
 176                 resp, list = self.longcmd('LIST')
 177                 for i in range(len(list)):
 178                         # Parse lines into "group last first flag"
 179                         list[i] = string.split(list[i])
 180                 return resp, list
 181
 182         # Process a GROUP command.  Argument:
 183         # - group: the group name
 184         # Returns:
 185         # - resp: server response if succesful
 186         # - count: number of articles (string)
 187         # - first: first article number (string)
 188         # - last: last article number (string)
 189         # - name: the group name
 190
 191         def group(self, name):
 192                 resp = self.shortcmd('GROUP ' + name)
 193                 if resp[:3] <> '211':
 194                         raise error_reply, resp
 195                 words = string.split(resp)
 196                 count = first = last = 0
 197                 n = len(words)
 198                 if n > 1:
 199                         count = words[1]
 200                         if n > 2:
 201                                 first = words[2]
 202                                 if n > 3:
 203                                         last = words[3]
 204                                         if n > 4:
 205                                                 name = string.lower(words[4])
 206                 return resp, count, first, last, name
 207
 208         # Process a HELP command.  Returns:
 209         # - resp: server response if succesful
 210         # - list: list of strings
 211
 212         def help(self):
 213                 return self.longcmd('HELP')
 214
 215         # Internal: parse the response of a STAT, NEXT or LAST command
 216         def statparse(self, resp):
 217                 if resp[:2] <> '22':
 218                         raise error_reply, resp
 219                 words = string.split(resp)
 220                 nr = 0
 221                 id = ''
 222                 n = len(words)
 223                 if n > 1:
 224                         nr = words[1]
 225                         if n > 2:
 226                                 id = string.lower(words[2])
 227                 return resp, nr, id
 228
 229         # Internal: process a STAT, NEXT or LAST command
 230         def statcmd(self, line):
 231                 resp = self.shortcmd(line)
 232                 return self.statparse(resp)
 233
 234         # Process a STAT command.  Argument:
 235         # - id: article number or message id
 236         # Returns:
 237         # - resp: server response if succesful
 238         # - nr:   the article number
 239         # - id:   the article id
 240
 241         def stat(self, id):
 242                 return self.statcmd('STAT ' + id)
 243
 244         # Process a NEXT command.  No arguments.  Return as for STAT
 245
 246         def next(self):
 247                 return self.statcmd('NEXT')
 248
 249         # Process a LAST command.  No arguments.  Return as for STAT
 250
 251         def last(self):
 252                 return self.statcmd('LAST')
 253
 254         # Internal: process a HEAD, BODY or ARTICLE command
 255         def artcmd(self, line):
 256                 resp, list = self.longcmd(line)
 257                 resp, nr, id = self.statparse(resp)
 258                 return resp, nr, id, list
 259
 260         # Process a HEAD command.  Argument:
 261         # - id: article number or message id
 262         # Returns:
 263         # - resp: server response if succesful
 264         # - list: the lines of the article's header
 265
 266         def head(self, id):
 267                 return self.artcmd('HEAD ' + id)
 268
 269         # Process a BODY command.  Argument:
 270         # - id: article number or message id
 271         # Returns:
 272         # - resp: server response if succesful
 273         # - list: the lines of the article's body
 274
 275         def body(self, id):
 276                 return self.artcmd('BODY ' + id)
 277
 278         # Process an ARTICLE command.  Argument:
 279         # - id: article number or message id
 280         # Returns:
 281         # - resp: server response if succesful
 282         # - list: the lines of the article
 283
 284         def article(self, id):
 285                 return self.artcmd('ARTICLE ' + id)
 286
 287         # Process a SLAVE command.  Returns:
 288         # - resp: server response if succesful
 289
 290         def slave(self):
 291                 return self.shortcmd('SLAVE')
 292
 293         # Process an XHDR command (optional server extension).  Arguments:
 294         # - hdr: the header type (e.g. 'subject')
 295         # - str: an article nr, a message id, or a range nr1-nr2
 296         # Returns:
 297         # - resp: server response if succesful
 298         # - list: list of (nr, value) strings
 299
 300         def xhdr(self, hdr, str):
 301                 resp, lines = self.longcmd('XHDR ' + hdr + ' ' + str)
 302                 for i in range(len(lines)):
 303                         line = lines[i]
 304                         n = regex.match('^[0-9]+', line)
 305                         nr = line[:n]
 306                         if n < len(line) and line[n] == ' ': n = n+1
 307                         lines[i] = (nr, line[n:])
 308                 return resp, lines
 309
 310         # Process a POST command.  Arguments:
 311         # - f: file containing the article
 312         # Returns:
 313         # - resp: server response if succesful
 314
 315         def post(self, f):
 316                 resp = self.shortcmd('POST')
 317                 # Raises error_??? if posting is not allowed
 318                 if resp[0] <> '3':
 319                         raise error_reply, resp
 320                 while 1:
 321                         line = f.readline()
 322                         if not line:
 323                                 break
 324                         if line[-1] == '\n':
 325                                 line = line[:-1]
 326                         if line == '.':
 327                                 line = '..'
 328                         self.putline(line)
 329                 self.putline('.')
 330                 return self.getresp()
 331
 332         # Process an IHAVE command.  Arguments:
 333         # - id: message-id of the article
 334         # - f:  file containing the article
 335         # Returns:
 336         # - resp: server response if succesful
 337         # Note that if the server refuses the article an exception is raised
 338
 339         def ihave(self, id, f):
 340                 resp = self.shortcmd('IHAVE ' + id)
 341                 # Raises error_??? if the server already has it
 342                 if resp[0] <> '3':
 343                         raise error_reply, resp
 344                 while 1:
 345                         line = f.readline()
 346                         if not line:
 347                                 break
 348                         if line[-1] == '\n':
 349                                 line = line[:-1]
 350                         if line == '.':
 351                                 line = '..'
 352                         self.putline(line)
 353                 self.putline('.')
 354                 return self.getresp()
 355
 356          # Process a QUIT command and close the socket.  Returns:
 357          # - resp: server response if succesful
 358
 359         def quit(self):
 360                 resp = self.shortcmd('QUIT')
 361                 self.file.close()
 362                 self.sock.close()
 363                 del self.file, self.sock
 364                 return resp