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