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 | """ |
| 5 | |
Guido van Rossum | 98d9fd3 | 2000-02-28 15:12:25 +0000 | [diff] [blame] | 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] |
Eric S. Raymond | 341f929 | 2001-02-09 06:56:56 +0000 | [diff] [blame] | 9 | # String method conversion and test jig improvements by ESR, February 2001. |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 10 | # Added the POP3_SSL class. Methods loosely based on IMAP_SSL. Hector Urtubia <urtubia@mrbook.org> Aug 2003 |
Guido van Rossum | 98d9fd3 | 2000-02-28 15:12:25 +0000 | [diff] [blame] | 11 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 12 | # Example (see the test function at the end of this file) |
| 13 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 14 | # Imports |
| 15 | |
Antoine Pitrou | 7fde5b3 | 2012-11-24 18:14:12 +0100 | [diff] [blame] | 16 | import errno |
| 17 | import re |
| 18 | import socket |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 19 | |
Antoine Pitrou | 8618d74 | 2012-11-23 20:13:48 +0100 | [diff] [blame] | 20 | try: |
| 21 | import ssl |
| 22 | HAVE_SSL = True |
| 23 | except ImportError: |
| 24 | HAVE_SSL = False |
| 25 | |
Thomas Wouters | 47b49bf | 2007-08-30 22:15:33 +0000 | [diff] [blame] | 26 | __all__ = ["POP3","error_proto"] |
Skip Montanaro | c62c81e | 2001-02-12 02:00:42 +0000 | [diff] [blame] | 27 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 28 | # Exception raised when an error or invalid response is received: |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 29 | |
| 30 | class error_proto(Exception): pass |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 31 | |
| 32 | # Standard Port |
| 33 | POP3_PORT = 110 |
| 34 | |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 35 | # POP SSL PORT |
| 36 | POP3_SSL_PORT = 995 |
| 37 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 38 | # Line terminators (we always output CRLF, but accept any of CRLF, LFCR, LF) |
Jeremy Hylton | 88d06a7 | 2007-08-29 19:08:30 +0000 | [diff] [blame] | 39 | CR = b'\r' |
| 40 | LF = b'\n' |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 41 | CRLF = CR+LF |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 42 | |
| 43 | |
| 44 | class POP3: |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 45 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 46 | """This class supports both the minimal and optional command sets. |
| 47 | Arguments can be strings or integers (where appropriate) |
| 48 | (e.g.: retr(1) and retr('1') both work equally well. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 49 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 50 | Minimal Command Set: |
| 51 | USER name user(name) |
| 52 | PASS string pass_(string) |
| 53 | STAT stat() |
| 54 | LIST [msg] list(msg = None) |
| 55 | RETR msg retr(msg) |
| 56 | DELE msg dele(msg) |
| 57 | NOOP noop() |
| 58 | RSET rset() |
| 59 | QUIT quit() |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 60 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 61 | Optional Commands (some servers support these): |
| 62 | RPOP name rpop(name) |
| 63 | APOP name digest apop(name, digest) |
| 64 | TOP msg n top(msg, n) |
| 65 | UIDL [msg] uidl(msg = None) |
Antoine Pitrou | 25cee19 | 2012-11-23 20:07:39 +0100 | [diff] [blame] | 66 | CAPA capa() |
Antoine Pitrou | 8618d74 | 2012-11-23 20:13:48 +0100 | [diff] [blame] | 67 | STLS stls() |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 68 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 69 | Raises one exception: 'error_proto'. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 70 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 71 | Instantiate with: |
| 72 | POP3(hostname, port=110) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 73 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 74 | NB: the POP protocol locks the mailbox from user |
| 75 | authorization until QUIT, so be sure to get in, suck |
| 76 | the messages, and quit, each time you access the |
| 77 | mailbox. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 78 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 79 | POP is a line-based protocol, which means large mail |
| 80 | messages consume lots of python cycles reading them |
| 81 | line-by-line. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 82 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 83 | If it's available on your mail server, use IMAP4 |
| 84 | instead, it doesn't suffer from the two problems |
| 85 | above. |
| 86 | """ |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 87 | |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 88 | encoding = 'UTF-8' |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 89 | |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 90 | def __init__(self, host, port=POP3_PORT, |
| 91 | timeout=socket._GLOBAL_DEFAULT_TIMEOUT): |
Martin v. Löwis | 4eb5940 | 2001-07-26 13:37:33 +0000 | [diff] [blame] | 92 | self.host = host |
| 93 | self.port = port |
Antoine Pitrou | 8618d74 | 2012-11-23 20:13:48 +0100 | [diff] [blame] | 94 | self._tls_established = False |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 95 | self.sock = self._create_socket(timeout) |
Martin v. Löwis | 4eb5940 | 2001-07-26 13:37:33 +0000 | [diff] [blame] | 96 | self.file = self.sock.makefile('rb') |
| 97 | self._debugging = 0 |
| 98 | self.welcome = self._getresp() |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 99 | |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 100 | def _create_socket(self, timeout): |
| 101 | return socket.create_connection((self.host, self.port), timeout) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 102 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 103 | def _putline(self, line): |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 104 | if self._debugging > 1: print('*put*', repr(line)) |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 105 | self.sock.sendall(line + CRLF) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 106 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 107 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 108 | # Internal: send one command to the server (through _putline()) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 109 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 110 | def _putcmd(self, line): |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 111 | if self._debugging: print('*cmd*', repr(line)) |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 112 | line = bytes(line, self.encoding) |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 113 | self._putline(line) |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 114 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 115 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 116 | # Internal: return one line from the server, stripping CRLF. |
| 117 | # This is where all the CPU time of this module is consumed. |
| 118 | # Raise error_proto('-ERR EOF') if the connection is closed. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 119 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 120 | def _getline(self): |
| 121 | line = self.file.readline() |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 122 | if self._debugging > 1: print('*get*', repr(line)) |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 123 | if not line: raise error_proto('-ERR EOF') |
| 124 | octets = len(line) |
| 125 | # server can send any combination of CR & LF |
| 126 | # however, 'readline()' returns lines ending in LF |
| 127 | # so only possibilities are ...LF, ...CRLF, CR...LF |
| 128 | if line[-2:] == CRLF: |
| 129 | return line[:-2], octets |
| 130 | if line[0] == CR: |
| 131 | return line[1:-1], octets |
| 132 | return line[:-1], octets |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 133 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 134 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 135 | # Internal: get a response from the server. |
| 136 | # Raise 'error_proto' if the response doesn't start with '+'. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 137 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 138 | def _getresp(self): |
| 139 | resp, o = self._getline() |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 140 | if self._debugging > 1: print('*resp*', repr(resp)) |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 141 | if not resp.startswith(b'+'): |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 142 | raise error_proto(resp) |
| 143 | return resp |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 144 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 145 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 146 | # Internal: get a response plus following text from the server. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 147 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 148 | def _getlongresp(self): |
| 149 | resp = self._getresp() |
| 150 | list = []; octets = 0 |
| 151 | line, o = self._getline() |
Guido van Rossum | 0ec3477 | 2007-09-10 00:27:13 +0000 | [diff] [blame] | 152 | while line != b'.': |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 153 | if line.startswith(b'..'): |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 154 | o = o-1 |
| 155 | line = line[1:] |
| 156 | octets = octets + o |
| 157 | list.append(line) |
| 158 | line, o = self._getline() |
| 159 | return resp, list, octets |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 160 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 161 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 162 | # Internal: send a command and get the response |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 163 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 164 | def _shortcmd(self, line): |
| 165 | self._putcmd(line) |
| 166 | return self._getresp() |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 167 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 168 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 169 | # Internal: send a command and get the response plus following text |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 170 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 171 | def _longcmd(self, line): |
| 172 | self._putcmd(line) |
| 173 | return self._getlongresp() |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 174 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 175 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 176 | # These can be useful: |
| 177 | |
| 178 | def getwelcome(self): |
| 179 | return self.welcome |
| 180 | |
| 181 | |
| 182 | def set_debuglevel(self, level): |
| 183 | self._debugging = level |
| 184 | |
| 185 | |
| 186 | # Here are all the POP commands: |
| 187 | |
| 188 | def user(self, user): |
| 189 | """Send user name, return response |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 190 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 191 | (should indicate password required). |
| 192 | """ |
| 193 | return self._shortcmd('USER %s' % user) |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 194 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 195 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 196 | def pass_(self, pswd): |
| 197 | """Send password, return response |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 198 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 199 | (response includes message count, mailbox size). |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 200 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 201 | NB: mailbox is locked by server from here to 'quit()' |
| 202 | """ |
| 203 | return self._shortcmd('PASS %s' % pswd) |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 204 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 205 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 206 | def stat(self): |
| 207 | """Get mailbox status. |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 208 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 209 | Result is tuple of 2 ints (message count, mailbox size) |
| 210 | """ |
| 211 | retval = self._shortcmd('STAT') |
Eric S. Raymond | 341f929 | 2001-02-09 06:56:56 +0000 | [diff] [blame] | 212 | rets = retval.split() |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 213 | if self._debugging: print('*stat*', repr(rets)) |
Eric S. Raymond | 341f929 | 2001-02-09 06:56:56 +0000 | [diff] [blame] | 214 | numMessages = int(rets[1]) |
| 215 | sizeMessages = int(rets[2]) |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 216 | return (numMessages, sizeMessages) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 217 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 218 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 219 | def list(self, which=None): |
| 220 | """Request listing, return result. |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 221 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 222 | Result without a message number argument is in form |
Georg Brandl | 2772c67 | 2005-08-05 21:01:58 +0000 | [diff] [blame] | 223 | ['response', ['mesg_num octets', ...], octets]. |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 224 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 225 | Result when a message number argument is given is a |
| 226 | single response: the "scan listing" for that message. |
| 227 | """ |
Raymond Hettinger | 16e3c42 | 2002-06-01 16:07:16 +0000 | [diff] [blame] | 228 | if which is not None: |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 229 | return self._shortcmd('LIST %s' % which) |
| 230 | return self._longcmd('LIST') |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 231 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 232 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 233 | def retr(self, which): |
| 234 | """Retrieve whole message number 'which'. |
Guido van Rossum | f6ae743 | 1998-09-02 14:42:02 +0000 | [diff] [blame] | 235 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 236 | Result is in form ['response', ['line', ...], octets]. |
| 237 | """ |
| 238 | return self._longcmd('RETR %s' % which) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 239 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 240 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 241 | def dele(self, which): |
| 242 | """Delete message number 'which'. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 243 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 244 | Result is 'response'. |
| 245 | """ |
| 246 | return self._shortcmd('DELE %s' % which) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 247 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 248 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 249 | def noop(self): |
| 250 | """Does nothing. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 251 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 252 | One supposes the response indicates the server is alive. |
| 253 | """ |
| 254 | return self._shortcmd('NOOP') |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 255 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 256 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 257 | def rset(self): |
Benjamin Peterson | a37cfc6 | 2008-05-26 13:48:34 +0000 | [diff] [blame] | 258 | """Unmark all messages marked for deletion.""" |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 259 | return self._shortcmd('RSET') |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 260 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 261 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 262 | def quit(self): |
| 263 | """Signoff: commit changes on server, unlock mailbox, close connection.""" |
Giampaolo Rodolà | 95bcb93 | 2011-02-25 22:28:24 +0000 | [diff] [blame] | 264 | resp = self._shortcmd('QUIT') |
| 265 | self.close() |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 266 | return resp |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 267 | |
Giampaolo Rodolà | 95bcb93 | 2011-02-25 22:28:24 +0000 | [diff] [blame] | 268 | def close(self): |
| 269 | """Close the connection without assuming anything about it.""" |
| 270 | if self.file is not None: |
| 271 | self.file.close() |
| 272 | if self.sock is not None: |
Antoine Pitrou | d89824b | 2012-11-23 20:04:45 +0100 | [diff] [blame] | 273 | try: |
| 274 | self.sock.shutdown(socket.SHUT_RDWR) |
Andrew Svetlov | 0832af6 | 2012-12-18 23:10:48 +0200 | [diff] [blame] | 275 | except OSError as e: |
Antoine Pitrou | d89824b | 2012-11-23 20:04:45 +0100 | [diff] [blame] | 276 | # The server might already have closed the connection |
| 277 | if e.errno != errno.ENOTCONN: |
| 278 | raise |
| 279 | finally: |
| 280 | self.sock.close() |
Giampaolo Rodolà | 95bcb93 | 2011-02-25 22:28:24 +0000 | [diff] [blame] | 281 | self.file = self.sock = None |
| 282 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 283 | #__del__ = quit |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 284 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 285 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 286 | # optional commands: |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 287 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 288 | def rpop(self, user): |
| 289 | """Not sure what this does.""" |
| 290 | return self._shortcmd('RPOP %s' % user) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 291 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 292 | |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 293 | timestamp = re.compile(br'\+OK.*(<[^>]+>)') |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 294 | |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 295 | def apop(self, user, password): |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 296 | """Authorisation |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 297 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 298 | - only possible if server has supplied a timestamp in initial greeting. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 299 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 300 | Args: |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 301 | user - mailbox user; |
| 302 | password - mailbox password. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 303 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 304 | NB: mailbox is locked by server from here to 'quit()' |
| 305 | """ |
Mark Dickinson | ea1158f | 2009-08-06 16:06:25 +0000 | [diff] [blame] | 306 | secret = bytes(password, self.encoding) |
Moshe Zadka | ccc2e3d | 2001-01-19 19:56:27 +0000 | [diff] [blame] | 307 | m = self.timestamp.match(self.welcome) |
| 308 | if not m: |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 309 | raise error_proto('-ERR APOP not supported by server') |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 310 | import hashlib |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 311 | digest = m.group(1)+secret |
| 312 | digest = hashlib.md5(digest).hexdigest() |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 313 | return self._shortcmd('APOP %s %s' % (user, digest)) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 314 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 315 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 316 | def top(self, which, howmuch): |
| 317 | """Retrieve message header of message number 'which' |
| 318 | and first 'howmuch' lines of message body. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 319 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 320 | Result is in form ['response', ['line', ...], octets]. |
| 321 | """ |
| 322 | return self._longcmd('TOP %s %s' % (which, howmuch)) |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 323 | |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 324 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 325 | def uidl(self, which=None): |
| 326 | """Return message digest (unique id) list. |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 327 | |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 328 | If 'which', result contains unique id for that message |
| 329 | in the form 'response mesgnum uid', otherwise result is |
| 330 | the list ['response', ['mesgnum uid', ...], octets] |
| 331 | """ |
Raymond Hettinger | 16e3c42 | 2002-06-01 16:07:16 +0000 | [diff] [blame] | 332 | if which is not None: |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 333 | return self._shortcmd('UIDL %s' % which) |
| 334 | return self._longcmd('UIDL') |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 335 | |
Antoine Pitrou | 25cee19 | 2012-11-23 20:07:39 +0100 | [diff] [blame] | 336 | |
| 337 | def capa(self): |
| 338 | """Return server capabilities (RFC 2449) as a dictionary |
| 339 | >>> c=poplib.POP3('localhost') |
| 340 | >>> c.capa() |
| 341 | {'IMPLEMENTATION': ['Cyrus', 'POP3', 'server', 'v2.2.12'], |
| 342 | 'TOP': [], 'LOGIN-DELAY': ['0'], 'AUTH-RESP-CODE': [], |
| 343 | 'EXPIRE': ['NEVER'], 'USER': [], 'STLS': [], 'PIPELINING': [], |
| 344 | 'UIDL': [], 'RESP-CODES': []} |
| 345 | >>> |
| 346 | |
| 347 | Really, according to RFC 2449, the cyrus folks should avoid |
| 348 | having the implementation splitted into multiple arguments... |
| 349 | """ |
| 350 | def _parsecap(line): |
| 351 | lst = line.decode('ascii').split() |
| 352 | return lst[0], lst[1:] |
| 353 | |
| 354 | caps = {} |
| 355 | try: |
| 356 | resp = self._longcmd('CAPA') |
| 357 | rawcaps = resp[1] |
| 358 | for capline in rawcaps: |
| 359 | capnm, capargs = _parsecap(capline) |
| 360 | caps[capnm] = capargs |
| 361 | except error_proto as _err: |
| 362 | raise error_proto('-ERR CAPA not supported by server') |
| 363 | return caps |
| 364 | |
Antoine Pitrou | 8618d74 | 2012-11-23 20:13:48 +0100 | [diff] [blame] | 365 | |
| 366 | def stls(self, context=None): |
| 367 | """Start a TLS session on the active connection as specified in RFC 2595. |
| 368 | |
| 369 | context - a ssl.SSLContext |
| 370 | """ |
| 371 | if not HAVE_SSL: |
| 372 | raise error_proto('-ERR TLS support missing') |
| 373 | if self._tls_established: |
| 374 | raise error_proto('-ERR TLS session already established') |
| 375 | caps = self.capa() |
| 376 | if not 'STLS' in caps: |
| 377 | raise error_proto('-ERR STLS not supported by server') |
| 378 | if context is None: |
| 379 | context = ssl.SSLContext(ssl.PROTOCOL_SSLv23) |
| 380 | context.options |= ssl.OP_NO_SSLv2 |
| 381 | resp = self._shortcmd('STLS') |
| 382 | self.sock = context.wrap_socket(self.sock) |
| 383 | self.file = self.sock.makefile('rb') |
| 384 | self._tls_established = True |
| 385 | return resp |
| 386 | |
| 387 | |
| 388 | if HAVE_SSL: |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 389 | |
Thomas Wouters | 47b49bf | 2007-08-30 22:15:33 +0000 | [diff] [blame] | 390 | class POP3_SSL(POP3): |
| 391 | """POP3 client class over SSL connection |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 392 | |
Antoine Pitrou | 8618d74 | 2012-11-23 20:13:48 +0100 | [diff] [blame] | 393 | Instantiate with: POP3_SSL(hostname, port=995, keyfile=None, certfile=None, |
| 394 | context=None) |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 395 | |
Thomas Wouters | 47b49bf | 2007-08-30 22:15:33 +0000 | [diff] [blame] | 396 | hostname - the hostname of the pop3 over ssl server |
| 397 | port - port number |
| 398 | keyfile - PEM formatted file that countains your private key |
| 399 | certfile - PEM formatted certificate chain file |
Antoine Pitrou | 8618d74 | 2012-11-23 20:13:48 +0100 | [diff] [blame] | 400 | context - a ssl.SSLContext |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 401 | |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 402 | See the methods of the parent class POP3 for more documentation. |
Thomas Wouters | 47b49bf | 2007-08-30 22:15:33 +0000 | [diff] [blame] | 403 | """ |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 404 | |
Giampaolo Rodolà | 42382fe | 2010-08-17 16:09:53 +0000 | [diff] [blame] | 405 | def __init__(self, host, port=POP3_SSL_PORT, keyfile=None, certfile=None, |
| 406 | timeout=socket._GLOBAL_DEFAULT_TIMEOUT, context=None): |
| 407 | if context is not None and keyfile is not None: |
| 408 | raise ValueError("context and keyfile arguments are mutually " |
| 409 | "exclusive") |
| 410 | if context is not None and certfile is not None: |
| 411 | raise ValueError("context and certfile arguments are mutually " |
| 412 | "exclusive") |
Thomas Wouters | 47b49bf | 2007-08-30 22:15:33 +0000 | [diff] [blame] | 413 | self.keyfile = keyfile |
| 414 | self.certfile = certfile |
Giampaolo Rodolà | 42382fe | 2010-08-17 16:09:53 +0000 | [diff] [blame] | 415 | self.context = context |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 416 | POP3.__init__(self, host, port, timeout) |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 417 | |
Christian Heimes | d395629 | 2008-11-05 19:48:27 +0000 | [diff] [blame] | 418 | def _create_socket(self, timeout): |
| 419 | sock = POP3._create_socket(self, timeout) |
Giampaolo Rodolà | 42382fe | 2010-08-17 16:09:53 +0000 | [diff] [blame] | 420 | if self.context is not None: |
| 421 | sock = self.context.wrap_socket(sock) |
| 422 | else: |
| 423 | sock = ssl.wrap_socket(sock, self.keyfile, self.certfile) |
| 424 | return sock |
Martin v. Löwis | 48440b7 | 2003-10-31 12:52:35 +0000 | [diff] [blame] | 425 | |
Antoine Pitrou | 8618d74 | 2012-11-23 20:13:48 +0100 | [diff] [blame] | 426 | def stls(self, keyfile=None, certfile=None, context=None): |
| 427 | """The method unconditionally raises an exception since the |
| 428 | STLS command doesn't make any sense on an already established |
| 429 | SSL/TLS session. |
| 430 | """ |
| 431 | raise error_proto('-ERR TLS session already established') |
| 432 | |
Thomas Wouters | 47b49bf | 2007-08-30 22:15:33 +0000 | [diff] [blame] | 433 | __all__.append("POP3_SSL") |
Guido van Rossum | 03774bb | 1998-04-09 13:50:55 +0000 | [diff] [blame] | 434 | |
Guido van Rossum | 484772d | 1998-04-06 18:27:27 +0000 | [diff] [blame] | 435 | if __name__ == "__main__": |
Eric S. Raymond | 341f929 | 2001-02-09 06:56:56 +0000 | [diff] [blame] | 436 | import sys |
| 437 | a = POP3(sys.argv[1]) |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 438 | print(a.getwelcome()) |
Eric S. Raymond | 341f929 | 2001-02-09 06:56:56 +0000 | [diff] [blame] | 439 | a.user(sys.argv[2]) |
| 440 | a.pass_(sys.argv[3]) |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 441 | a.list() |
| 442 | (numMsgs, totalSize) = a.stat() |
| 443 | for i in range(1, numMsgs + 1): |
| 444 | (header, msg, octets) = a.retr(i) |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 445 | print("Message %d:" % i) |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 446 | for line in msg: |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 447 | print(' ' + line) |
| 448 | print('-----------------------') |
Tim Peters | 2344fae | 2001-01-15 00:50:52 +0000 | [diff] [blame] | 449 | a.quit() |