Lib/poplib.py

   1 """A POP3 client class.
   2
   3 Based on the J. Myers POP3 draft, Jan. 96
   4 """
   5
   6 # Author: David Ascher <david_ascher@brown.edu>
   7 #         [heavily stealing from nntplib.py]
   8 # Updated: Piers Lauder <piers@cs.su.oz.au> [Jul '97]
   9 # String method conversion and test jig improvements by ESR, February 2001.
  10 # Added the POP3_SSL class. Methods loosely based on IMAP_SSL. Hector Urtubia <urtubia@mrbook.org> Aug 2003
  11
  12 # Example (see the test function at the end of this file)
  13
  14 # Imports
  15
  16 import re, socket
  17
  18 __all__ = ["POP3","error_proto"]
  19
  20 # Exception raised when an error or invalid response is received:
  21
  22 class error_proto(Exception): pass
  23
  24 # Standard Port
  25 POP3_PORT = 110
  26
  27 # POP SSL PORT
  28 POP3_SSL_PORT = 995
  29
  30 # Line terminators (we always output CRLF, but accept any of CRLF, LFCR, LF)
  31 CR = '\r'
  32 LF = '\n'
  33 CRLF = CR+LF
  34
  35
  36 class POP3:
  37
  38     """This class supports both the minimal and optional command sets.
  39     Arguments can be strings or integers (where appropriate)
  40     (e.g.: retr(1) and retr('1') both work equally well.
  41
  42     Minimal Command Set:
  43             USER name               user(name)
  44             PASS string             pass_(string)
  45             STAT                    stat()
  46             LIST [msg]              list(msg = None)
  47             RETR msg                retr(msg)
  48             DELE msg                dele(msg)
  49             NOOP                    noop()
  50             RSET                    rset()
  51             QUIT                    quit()
  52
  53     Optional Commands (some servers support these):
  54             RPOP name               rpop(name)
  55             APOP name digest        apop(name, digest)
  56             TOP msg n               top(msg, n)
  57             UIDL [msg]              uidl(msg = None)
  58
  59     Raises one exception: 'error_proto'.
  60
  61     Instantiate with:
  62             POP3(hostname, port=110)
  63
  64     NB:     the POP protocol locks the mailbox from user
  65             authorization until QUIT, so be sure to get in, suck
  66             the messages, and quit, each time you access the
  67             mailbox.
  68
  69             POP is a line-based protocol, which means large mail
  70             messages consume lots of python cycles reading them
  71             line-by-line.
  72
  73             If it's available on your mail server, use IMAP4
  74             instead, it doesn't suffer from the two problems
  75             above.
  76     """
  77
  78
  79     def __init__(self, host, port=POP3_PORT,
  80                  timeout=socket._GLOBAL_DEFAULT_TIMEOUT):
  81         self.host = host
  82         self.port = port
  83         self.sock = socket.create_connection((host, port), timeout)
  84         self.file = self.sock.makefile('rb')
  85         self._debugging = 0
  86         self.welcome = self._getresp()
  87
  88
  89     def _putline(self, line):
  90         if self._debugging > 1: print '*put*', repr(line)
  91         self.sock.sendall('%s%s' % (line, CRLF))
  92
  93
  94     # Internal: send one command to the server (through _putline())
  95
  96     def _putcmd(self, line):
  97         if self._debugging: print '*cmd*', repr(line)
  98         self._putline(line)
  99
 100
 101     # Internal: return one line from the server, stripping CRLF.
 102     # This is where all the CPU time of this module is consumed.
 103     # Raise error_proto('-ERR EOF') if the connection is closed.
 104
 105     def _getline(self):
 106         line = self.file.readline()
 107         if self._debugging > 1: print '*get*', repr(line)
 108         if not line: raise error_proto('-ERR EOF')
 109         octets = len(line)
 110         # server can send any combination of CR & LF
 111         # however, 'readline()' returns lines ending in LF
 112         # so only possibilities are ...LF, ...CRLF, CR...LF
 113         if line[-2:] == CRLF:
 114             return line[:-2], octets
 115         if line[0] == CR:
 116             return line[1:-1], octets
 117         return line[:-1], octets
 118
 119
 120     # Internal: get a response from the server.
 121     # Raise 'error_proto' if the response doesn't start with '+'.
 122
 123     def _getresp(self):
 124         resp, o = self._getline()
 125         if self._debugging > 1: print '*resp*', repr(resp)
 126         c = resp[:1]
 127         if c != '+':
 128             raise error_proto(resp)
 129         return resp
 130
 131
 132     # Internal: get a response plus following text from the server.
 133
 134     def _getlongresp(self):
 135         resp = self._getresp()
 136         list = []; octets = 0
 137         line, o = self._getline()
 138         while line != '.':
 139             if line[:2] == '..':
 140                 o = o-1
 141                 line = line[1:]
 142             octets = octets + o
 143             list.append(line)
 144             line, o = self._getline()
 145         return resp, list, octets
 146
 147
 148     # Internal: send a command and get the response
 149
 150     def _shortcmd(self, line):
 151         self._putcmd(line)
 152         return self._getresp()
 153
 154
 155     # Internal: send a command and get the response plus following text
 156
 157     def _longcmd(self, line):
 158         self._putcmd(line)
 159         return self._getlongresp()
 160
 161
 162     # These can be useful:
 163
 164     def getwelcome(self):
 165         return self.welcome
 166
 167
 168     def set_debuglevel(self, level):
 169         self._debugging = level
 170
 171
 172     # Here are all the POP commands:
 173
 174     def user(self, user):
 175         """Send user name, return response
 176
 177         (should indicate password required).
 178         """
 179         return self._shortcmd('USER %s' % user)
 180
 181
 182     def pass_(self, pswd):
 183         """Send password, return response
 184
 185         (response includes message count, mailbox size).
 186
 187         NB: mailbox is locked by server from here to 'quit()'
 188         """
 189         return self._shortcmd('PASS %s' % pswd)
 190
 191
 192     def stat(self):
 193         """Get mailbox status.
 194
 195         Result is tuple of 2 ints (message count, mailbox size)
 196         """
 197         retval = self._shortcmd('STAT')
 198         rets = retval.split()
 199         if self._debugging: print '*stat*', repr(rets)
 200         numMessages = int(rets[1])
 201         sizeMessages = int(rets[2])
 202         return (numMessages, sizeMessages)
 203
 204
 205     def list(self, which=None):
 206         """Request listing, return result.
 207
 208         Result without a message number argument is in form
 209         ['response', ['mesg_num octets', ...], octets].
 210
 211         Result when a message number argument is given is a
 212         single response: the "scan listing" for that message.
 213         """
 214         if which is not None:
 215             return self._shortcmd('LIST %s' % which)
 216         return self._longcmd('LIST')
 217
 218
 219     def retr(self, which):
 220         """Retrieve whole message number 'which'.
 221
 222         Result is in form ['response', ['line', ...], octets].
 223         """
 224         return self._longcmd('RETR %s' % which)
 225
 226
 227     def dele(self, which):
 228         """Delete message number 'which'.
 229
 230         Result is 'response'.
 231         """
 232         return self._shortcmd('DELE %s' % which)
 233
 234
 235     def noop(self):
 236         """Does nothing.
 237
 238         One supposes the response indicates the server is alive.
 239         """
 240         return self._shortcmd('NOOP')
 241
 242
 243     def rset(self):
 244         """Unmark all messages marked for deletion."""
 245         return self._shortcmd('RSET')
 246
 247
 248     def quit(self):
 249         """Signoff: commit changes on server, unlock mailbox, close connection."""
 250         try:
 251             resp = self._shortcmd('QUIT')
 252         except error_proto, val:
 253             resp = val
 254         self.file.close()
 255         self.sock.close()
 256         del self.file, self.sock
 257         return resp
 258
 259     #__del__ = quit
 260
 261
 262     # optional commands:
 263
 264     def rpop(self, user):
 265         """Not sure what this does."""
 266         return self._shortcmd('RPOP %s' % user)
 267
 268
 269     timestamp = re.compile(r'\+OK.*(<[^>]+>)')
 270
 271     def apop(self, user, secret):
 272         """Authorisation
 273
 274         - only possible if server has supplied a timestamp in initial greeting.
 275
 276         Args:
 277                 user    - mailbox user;
 278                 secret  - secret shared between client and server.
 279
 280         NB: mailbox is locked by server from here to 'quit()'
 281         """
 282         m = self.timestamp.match(self.welcome)
 283         if not m:
 284             raise error_proto('-ERR APOP not supported by server')
 285         import hashlib
 286         digest = hashlib.md5(m.group(1)+secret).digest()
 287         digest = ''.join(map(lambda x:'%02x'%ord(x), digest))
 288         return self._shortcmd('APOP %s %s' % (user, digest))
 289
 290
 291     def top(self, which, howmuch):
 292         """Retrieve message header of message number 'which'
 293         and first 'howmuch' lines of message body.
 294
 295         Result is in form ['response', ['line', ...], octets].
 296         """
 297         return self._longcmd('TOP %s %s' % (which, howmuch))
 298
 299
 300     def uidl(self, which=None):
 301         """Return message digest (unique id) list.
 302
 303         If 'which', result contains unique id for that message
 304         in the form 'response mesgnum uid', otherwise result is
 305         the list ['response', ['mesgnum uid', ...], octets]
 306         """
 307         if which is not None:
 308             return self._shortcmd('UIDL %s' % which)
 309         return self._longcmd('UIDL')
 310
 311 try:
 312     import ssl
 313 except ImportError:
 314     pass
 315 else:
 316
 317     class POP3_SSL(POP3):
 318         """POP3 client class over SSL connection
 319
 320         Instantiate with: POP3_SSL(hostname, port=995, keyfile=None, certfile=None)
 321
 322                hostname - the hostname of the pop3 over ssl server
 323                port - port number
 324                keyfile - PEM formatted file that countains your private key
 325                certfile - PEM formatted certificate chain file
 326
 327             See the methods of the parent class POP3 for more documentation.
 328         """
 329
 330         def __init__(self, host, port = POP3_SSL_PORT, keyfile = None, certfile = None):
 331             self.host = host
 332             self.port = port
 333             self.keyfile = keyfile
 334             self.certfile = certfile
 335             self.buffer = ""
 336             msg = "getaddrinfo returns an empty list"
 337             self.sock = None
 338             for res in socket.getaddrinfo(self.host, self.port, 0, socket.SOCK_STREAM):
 339                 af, socktype, proto, canonname, sa = res
 340                 try:
 341                     self.sock = socket.socket(af, socktype, proto)
 342                     self.sock.connect(sa)
 343                 except socket.error, msg:
 344                     if self.sock:
 345                         self.sock.close()
 346                     self.sock = None
 347                     continue
 348                 break
 349             if not self.sock:
 350                 raise socket.error, msg
 351             self.file = self.sock.makefile('rb')
 352             self.sslobj = ssl.wrap_socket(self.sock, self.keyfile, self.certfile)
 353             self._debugging = 0
 354             self.welcome = self._getresp()
 355
 356         def _fillBuffer(self):
 357             localbuf = self.sslobj.read()
 358             if len(localbuf) == 0:
 359                 raise error_proto('-ERR EOF')
 360             self.buffer += localbuf
 361
 362         def _getline(self):
 363             line = ""
 364             renewline = re.compile(r'.*?\n')
 365             match = renewline.match(self.buffer)
 366             while not match:
 367                 self._fillBuffer()
 368                 match = renewline.match(self.buffer)
 369             line = match.group(0)
 370             self.buffer = renewline.sub('' ,self.buffer, 1)
 371             if self._debugging > 1: print '*get*', repr(line)
 372
 373             octets = len(line)
 374             if line[-2:] == CRLF:
 375                 return line[:-2], octets
 376             if line[0] == CR:
 377                 return line[1:-1], octets
 378             return line[:-1], octets
 379
 380         def _putline(self, line):
 381             if self._debugging > 1: print '*put*', repr(line)
 382             line += CRLF
 383             bytes = len(line)
 384             while bytes > 0:
 385                 sent = self.sslobj.write(line)
 386                 if sent == bytes:
 387                     break    # avoid copy
 388                 line = line[sent:]
 389                 bytes = bytes - sent
 390
 391         def quit(self):
 392             """Signoff: commit changes on server, unlock mailbox, close connection."""
 393             try:
 394                 resp = self._shortcmd('QUIT')
 395             except error_proto, val:
 396                 resp = val
 397             self.sock.close()
 398             del self.sslobj, self.sock
 399             return resp
 400
 401     __all__.append("POP3_SSL")
 402
 403 if __name__ == "__main__":
 404     import sys
 405     a = POP3(sys.argv[1])
 406     print a.getwelcome()
 407     a.user(sys.argv[2])
 408     a.pass_(sys.argv[3])
 409     a.list()
 410     (numMsgs, totalSize) = a.stat()
 411     for i in range(1, numMsgs + 1):
 412         (header, msg, octets) = a.retr(i)
 413         print "Message %d:" % i
 414         for line in msg:
 415             print '   ' + line
 416         print '-----------------------'
 417     a.quit()