Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 1 | """A POP3 client class. |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 2 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 3 | Based on the J. Myers POP3 draft, Jan. 96 |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 4 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 5 | Author: David Ascher <david_ascher@brown.edu> |
| 6 | [heavily stealing from nntplib.py] |
| 7 | Updated: Piers Lauder <piers@cs.su.oz.au> [Jul '97] |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 8 | """ |
| 9 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 10 | # Example (see the test function at the end of this file) |
| 11 | |
| 12 | TESTSERVER = "localhost" |
| 13 | TESTACCOUNT = "test" |
| 14 | TESTPASSWORD = "_passwd_" |
| 15 | |
| 16 | # Imports |
| 17 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 18 | import regex, socket, string |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 19 | |
| 20 | # Exception raised when an error or invalid response is received: |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 21 | |
| 22 | class error_proto(Exception): pass |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 23 | |
| 24 | # Standard Port |
| 25 | POP3_PORT = 110 |
| 26 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 27 | # Line terminators (we always output CRLF, but accept any of CRLF, LFCR, LF) |
| 28 | CR = '\r' |
| 29 | LF = '\n' |
| 30 | CRLF = CR+LF |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 31 | |
| 32 | |
| 33 | class POP3: |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 34 | |
| 35 | """This class supports both the minimal and optional command sets. |
| 36 | Arguments can be strings or integers (where appropriate) |
| 37 | (e.g.: retr(1) and retr('1') both work equally well. |
| 38 | |
| 39 | Minimal Command Set: |
| 40 | USER name user(name) |
| 41 | PASS string pass_(string) |
| 42 | STAT stat() |
| 43 | LIST [msg] list(msg = None) |
| 44 | RETR msg retr(msg) |
| 45 | DELE msg dele(msg) |
| 46 | NOOP noop() |
| 47 | RSET rset() |
| 48 | QUIT quit() |
| 49 | |
| 50 | Optional Commands (some servers support these): |
| 51 | RPOP name rpop(name) |
| 52 | APOP name digest apop(name, digest) |
| 53 | TOP msg n top(msg, n) |
| 54 | UIDL [msg] uidl(msg = None) |
| 55 | |
| 56 | Raises one exception: 'error_proto'. |
| 57 | |
| 58 | Instantiate with: |
| 59 | POP3(hostname, port=110) |
| 60 | |
| 61 | NB: the POP protocol locks the mailbox from user |
| 62 | authorisation until QUIT, so be sure to get in, suck |
| 63 | the messages, and quit, each time you access the |
| 64 | mailbox. |
| 65 | |
| 66 | POP is a line-based protocol, which means large mail |
| 67 | messages consume lots of python cycles reading them |
| 68 | line-by-line. |
| 69 | |
| 70 | If it's available on your mail server, use IMAP4 |
| 71 | instead, it doesn't suffer from the two problems |
| 72 | above. |
| 73 | """ |
| 74 | |
| 75 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 76 | def __init__(self, host, port = POP3_PORT): |
| 77 | self.host = host |
| 78 | self.port = port |
| 79 | self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| 80 | self.sock.connect(self.host, self.port) |
| 81 | self.file = self.sock.makefile('rb') |
| 82 | self._debugging = 0 |
| 83 | self.welcome = self._getresp() |
| 84 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 85 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 86 | def _putline(self, line): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 87 | #if self._debugging > 1: print '*put*', `line` |
| 88 | self.sock.send('%s%s' % (line, CRLF)) |
| 89 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 90 | |
| 91 | # Internal: send one command to the server (through _putline()) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 92 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 93 | def _putcmd(self, line): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 94 | #if self._debugging: print '*cmd*', `line` |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 95 | self._putline(line) |
| 96 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 97 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 98 | # Internal: return one line from the server, stripping CRLF. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 99 | # This is where all the CPU time of this module is consumed. |
| 100 | # Raise error_proto('-ERR EOF') if the connection is closed. |
| 101 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 102 | def _getline(self): |
| 103 | line = self.file.readline() |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 104 | #if self._debugging > 1: print '*get*', `line` |
| 105 | if not line: raise error_proto('-ERR EOF') |
| 106 | octets = len(line) |
| 107 | # server can send any combination of CR & LF |
| 108 | # however, 'readline()' returns lines ending in LF |
| 109 | # so only possibilities are ...LF, ...CRLF, CR...LF |
| 110 | if line[-2:] == CRLF: |
| 111 | return line[:-2], octets |
| 112 | if line[0] == CR: |
| 113 | return line[1:-1], octets |
| 114 | return line[:-1], octets |
| 115 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 116 | |
| 117 | # Internal: get a response from the server. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 118 | # Raise 'error_proto' if the response doesn't start with '+'. |
| 119 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 120 | def _getresp(self): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 121 | resp, o = self._getline() |
| 122 | #if self._debugging > 1: print '*resp*', `resp` |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 123 | c = resp[:1] |
| 124 | if c != '+': |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 125 | raise error_proto(resp) |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 126 | return resp |
| 127 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 128 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 129 | # Internal: get a response plus following text from the server. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 130 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 131 | def _getlongresp(self): |
| 132 | resp = self._getresp() |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 133 | list = []; octets = 0 |
| 134 | line, o = self._getline() |
| 135 | while line != '.': |
| 136 | octets = octets + o |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 137 | list.append(line) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 138 | line, o = self._getline() |
| 139 | return resp, list, octets |
| 140 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 141 | |
| 142 | # Internal: send a command and get the response |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 143 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 144 | def _shortcmd(self, line): |
| 145 | self._putcmd(line) |
| 146 | return self._getresp() |
| 147 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 148 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 149 | # Internal: send a command and get the response plus following text |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 150 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 151 | def _longcmd(self, line): |
| 152 | self._putcmd(line) |
| 153 | return self._getlongresp() |
| 154 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 155 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 156 | # These can be useful: |
| 157 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 158 | def getwelcome(self): |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 159 | return self.welcome |
| 160 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 161 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 162 | def set_debuglevel(self, level): |
| 163 | self._debugging = level |
| 164 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 165 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 166 | # Here are all the POP commands: |
| 167 | |
| 168 | def user(self, user): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 169 | """Send user name, return response |
| 170 | |
| 171 | (should indicate password required). |
| 172 | """ |
| 173 | return self._shortcmd('USER %s' % user) |
| 174 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 175 | |
| 176 | def pass_(self, pswd): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 177 | """Send password, return response |
| 178 | |
| 179 | (response includes message count, mailbox size). |
| 180 | |
| 181 | NB: mailbox is locked by server from here to 'quit()' |
| 182 | """ |
| 183 | return self._shortcmd('PASS %s' % pswd) |
| 184 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 185 | |
| 186 | def stat(self): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 187 | """Get mailbox status. |
| 188 | |
| 189 | Result is tuple of 2 ints (message count, mailbox size) |
| 190 | """ |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 191 | retval = self._shortcmd('STAT') |
| 192 | rets = string.split(retval) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 193 | #if self._debugging: print '*stat*', `rets` |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 194 | numMessages = string.atoi(rets[1]) |
| 195 | sizeMessages = string.atoi(rets[2]) |
| 196 | return (numMessages, sizeMessages) |
| 197 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 198 | |
| 199 | def list(self, which=None): |
| 200 | """Request listing, return result. |
| 201 | Result is in form ['response', ['mesg_num octets', ...]]. |
| 202 | |
| 203 | Unsure what the optional 'msg' arg does. |
| 204 | """ |
| 205 | if which: |
| 206 | return self._longcmd('LIST %s' % which) |
| 207 | return self._longcmd('LIST') |
| 208 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 209 | |
| 210 | def retr(self, which): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 211 | """Retrieve whole message number 'which'. |
| 212 | |
| 213 | Result is in form ['response', ['line', ...], octets]. |
| 214 | """ |
| 215 | return self._longcmd('RETR %s' % which) |
| 216 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 217 | |
| 218 | def dele(self, which): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 219 | """Delete message number 'which'. |
| 220 | |
| 221 | Result is 'response'. |
| 222 | """ |
| 223 | return self._shortcmd('DELE %s' % which) |
| 224 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 225 | |
| 226 | def noop(self): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 227 | """Does nothing. |
| 228 | |
| 229 | One supposes the response indicates the server is alive. |
| 230 | """ |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 231 | return self._shortcmd('NOOP') |
| 232 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 233 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 234 | def rset(self): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 235 | """Not sure what this does.""" |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 236 | return self._shortcmd('RSET') |
| 237 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 238 | |
| 239 | def quit(self): |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 240 | """Signoff: commit changes on server, unlock mailbox, close connection.""" |
| 241 | try: |
| 242 | resp = self._shortcmd('QUIT') |
Guido van Rossum | de23cb0 | 1998-08-06 02:59:07 +0000 | [diff] [blame^] | 243 | except error_proto, val: |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 244 | resp = val |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 245 | self.file.close() |
| 246 | self.sock.close() |
| 247 | del self.file, self.sock |
| 248 | return resp |
| 249 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 250 | #__del__ = quit |
| 251 | |
| 252 | |
| 253 | # optional commands: |
| 254 | |
| 255 | def rpop(self, user): |
| 256 | """Not sure what this does.""" |
| 257 | return self._shortcmd('RPOP %s' % user) |
| 258 | |
| 259 | |
| 260 | timestamp = regex.compile('\+OK.*\(<[^>]+>\)') |
| 261 | |
| 262 | def apop(self, user, secret): |
| 263 | """Authorisation |
| 264 | |
| 265 | - only possible if server has supplied a timestamp in initial greeting. |
| 266 | |
| 267 | Args: |
| 268 | user - mailbox user; |
| 269 | secret - secret shared between client and server. |
| 270 | |
| 271 | NB: mailbox is locked by server from here to 'quit()' |
| 272 | """ |
| 273 | if self.timestamp.match(self.welcome) <= 0: |
| 274 | raise error_proto('-ERR APOP not supported by server') |
| 275 | import md5 |
| 276 | digest = md5.new(self.timestamp.group(1)+secret).digest() |
| 277 | digest = string.join(map(lambda x:'%02x'%ord(x), digest), '') |
| 278 | return self._shortcmd('APOP %s %s' % (user, digest)) |
| 279 | |
| 280 | |
| 281 | def top(self, which, howmuch): |
| 282 | """Retrieve message header of message number 'which' |
| 283 | and first 'howmuch' lines of message body. |
| 284 | |
| 285 | Result is in form ['response', ['line', ...], octets]. |
| 286 | """ |
| 287 | return self._longcmd('TOP %s %s' % (which, howmuch)) |
| 288 | |
| 289 | |
| 290 | def uidl(self, which=None): |
| 291 | """Return message digest (unique id) list. |
| 292 | |
| 293 | If 'which', result contains unique id for that message, |
| 294 | otherwise result is list ['response', ['mesgnum uid', ...], octets] |
| 295 | """ |
| 296 | if which: |
| 297 | return self._shortcmd('UIDL %s' % which) |
| 298 | return self._longcmd('UIDL') |
| 299 | |
| 300 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 301 | if __name__ == "__main__": |
| 302 | a = POP3(TESTSERVER) |
| 303 | print a.getwelcome() |
| 304 | a.user(TESTACCOUNT) |
| 305 | a.pass_(TESTPASSWORD) |
| 306 | a.list() |
| 307 | (numMsgs, totalSize) = a.stat() |
| 308 | for i in range(1, numMsgs + 1): |
| 309 | (header, msg, octets) = a.retr(i) |
| 310 | print "Message ", `i`, ':' |
| 311 | for line in msg: |
| 312 | print ' ' + line |
| 313 | print '-----------------------' |
| 314 | a.quit() |