| """A POP3 client class. |
| |
| Based on the J. Myers POP3 draft, Jan. 96 |
| """ |
| |
| # Author: David Ascher <david_ascher@brown.edu> |
| # [heavily stealing from nntplib.py] |
| # Updated: Piers Lauder <piers@cs.su.oz.au> [Jul '97] |
| # String method conversion and test jig improvements by ESR, February 2001. |
| # Added the POP3_SSL class. Methods loosely based on IMAP_SSL. Hector Urtubia <urtubia@mrbook.org> Aug 2003 |
| |
| # Example (see the test function at the end of this file) |
| |
| # Imports |
| |
| import errno |
| import re |
| import socket |
| import sys |
| |
| try: |
| import ssl |
| HAVE_SSL = True |
| except ImportError: |
| HAVE_SSL = False |
| |
| __all__ = ["POP3","error_proto"] |
| |
| # Exception raised when an error or invalid response is received: |
| |
| class error_proto(Exception): pass |
| |
| # Standard Port |
| POP3_PORT = 110 |
| |
| # POP SSL PORT |
| POP3_SSL_PORT = 995 |
| |
| # Line terminators (we always output CRLF, but accept any of CRLF, LFCR, LF) |
| CR = b'\r' |
| LF = b'\n' |
| CRLF = CR+LF |
| |
| # maximal line length when calling readline(). This is to prevent |
| # reading arbitrary length lines. RFC 1939 limits POP3 line length to |
| # 512 characters, including CRLF. We have selected 2048 just to be on |
| # the safe side. |
| _MAXLINE = 2048 |
| |
| |
| class POP3: |
| |
| """This class supports both the minimal and optional command sets. |
| Arguments can be strings or integers (where appropriate) |
| (e.g.: retr(1) and retr('1') both work equally well. |
| |
| Minimal Command Set: |
| USER name user(name) |
| PASS string pass_(string) |
| STAT stat() |
| LIST [msg] list(msg = None) |
| RETR msg retr(msg) |
| DELE msg dele(msg) |
| NOOP noop() |
| RSET rset() |
| QUIT quit() |
| |
| Optional Commands (some servers support these): |
| RPOP name rpop(name) |
| APOP name digest apop(name, digest) |
| TOP msg n top(msg, n) |
| UIDL [msg] uidl(msg = None) |
| CAPA capa() |
| STLS stls() |
| UTF8 utf8() |
| |
| Raises one exception: 'error_proto'. |
| |
| Instantiate with: |
| POP3(hostname, port=110) |
| |
| NB: the POP protocol locks the mailbox from user |
| authorization until QUIT, so be sure to get in, suck |
| the messages, and quit, each time you access the |
| mailbox. |
| |
| POP is a line-based protocol, which means large mail |
| messages consume lots of python cycles reading them |
| line-by-line. |
| |
| If it's available on your mail server, use IMAP4 |
| instead, it doesn't suffer from the two problems |
| above. |
| """ |
| |
| encoding = 'UTF-8' |
| |
| def __init__(self, host, port=POP3_PORT, |
| timeout=socket._GLOBAL_DEFAULT_TIMEOUT): |
| self.host = host |
| self.port = port |
| self._tls_established = False |
| sys.audit("poplib.connect", self, host, port) |
| self.sock = self._create_socket(timeout) |
| self.file = self.sock.makefile('rb') |
| self._debugging = 0 |
| self.welcome = self._getresp() |
| |
| def _create_socket(self, timeout): |
| if timeout is not None and not timeout: |
| raise ValueError('Non-blocking socket (timeout=0) is not supported') |
| return socket.create_connection((self.host, self.port), timeout) |
| |
| def _putline(self, line): |
| if self._debugging > 1: print('*put*', repr(line)) |
| sys.audit("poplib.putline", self, line) |
| self.sock.sendall(line + CRLF) |
| |
| |
| # Internal: send one command to the server (through _putline()) |
| |
| def _putcmd(self, line): |
| if self._debugging: print('*cmd*', repr(line)) |
| line = bytes(line, self.encoding) |
| self._putline(line) |
| |
| |
| # Internal: return one line from the server, stripping CRLF. |
| # This is where all the CPU time of this module is consumed. |
| # Raise error_proto('-ERR EOF') if the connection is closed. |
| |
| def _getline(self): |
| line = self.file.readline(_MAXLINE + 1) |
| if len(line) > _MAXLINE: |
| raise error_proto('line too long') |
| |
| if self._debugging > 1: print('*get*', repr(line)) |
| if not line: raise error_proto('-ERR EOF') |
| octets = len(line) |
| # server can send any combination of CR & LF |
| # however, 'readline()' returns lines ending in LF |
| # so only possibilities are ...LF, ...CRLF, CR...LF |
| if line[-2:] == CRLF: |
| return line[:-2], octets |
| if line[:1] == CR: |
| return line[1:-1], octets |
| return line[:-1], octets |
| |
| |
| # Internal: get a response from the server. |
| # Raise 'error_proto' if the response doesn't start with '+'. |
| |
| def _getresp(self): |
| resp, o = self._getline() |
| if self._debugging > 1: print('*resp*', repr(resp)) |
| if not resp.startswith(b'+'): |
| raise error_proto(resp) |
| return resp |
| |
| |
| # Internal: get a response plus following text from the server. |
| |
| def _getlongresp(self): |
| resp = self._getresp() |
| list = []; octets = 0 |
| line, o = self._getline() |
| while line != b'.': |
| if line.startswith(b'..'): |
| o = o-1 |
| line = line[1:] |
| octets = octets + o |
| list.append(line) |
| line, o = self._getline() |
| return resp, list, octets |
| |
| |
| # Internal: send a command and get the response |
| |
| def _shortcmd(self, line): |
| self._putcmd(line) |
| return self._getresp() |
| |
| |
| # Internal: send a command and get the response plus following text |
| |
| def _longcmd(self, line): |
| self._putcmd(line) |
| return self._getlongresp() |
| |
| |
| # These can be useful: |
| |
| def getwelcome(self): |
| return self.welcome |
| |
| |
| def set_debuglevel(self, level): |
| self._debugging = level |
| |
| |
| # Here are all the POP commands: |
| |
| def user(self, user): |
| """Send user name, return response |
| |
| (should indicate password required). |
| """ |
| return self._shortcmd('USER %s' % user) |
| |
| |
| def pass_(self, pswd): |
| """Send password, return response |
| |
| (response includes message count, mailbox size). |
| |
| NB: mailbox is locked by server from here to 'quit()' |
| """ |
| return self._shortcmd('PASS %s' % pswd) |
| |
| |
| def stat(self): |
| """Get mailbox status. |
| |
| Result is tuple of 2 ints (message count, mailbox size) |
| """ |
| retval = self._shortcmd('STAT') |
| rets = retval.split() |
| if self._debugging: print('*stat*', repr(rets)) |
| numMessages = int(rets[1]) |
| sizeMessages = int(rets[2]) |
| return (numMessages, sizeMessages) |
| |
| |
| def list(self, which=None): |
| """Request listing, return result. |
| |
| Result without a message number argument is in form |
| ['response', ['mesg_num octets', ...], octets]. |
| |
| Result when a message number argument is given is a |
| single response: the "scan listing" for that message. |
| """ |
| if which is not None: |
| return self._shortcmd('LIST %s' % which) |
| return self._longcmd('LIST') |
| |
| |
| def retr(self, which): |
| """Retrieve whole message number 'which'. |
| |
| Result is in form ['response', ['line', ...], octets]. |
| """ |
| return self._longcmd('RETR %s' % which) |
| |
| |
| def dele(self, which): |
| """Delete message number 'which'. |
| |
| Result is 'response'. |
| """ |
| return self._shortcmd('DELE %s' % which) |
| |
| |
| def noop(self): |
| """Does nothing. |
| |
| One supposes the response indicates the server is alive. |
| """ |
| return self._shortcmd('NOOP') |
| |
| |
| def rset(self): |
| """Unmark all messages marked for deletion.""" |
| return self._shortcmd('RSET') |
| |
| |
| def quit(self): |
| """Signoff: commit changes on server, unlock mailbox, close connection.""" |
| resp = self._shortcmd('QUIT') |
| self.close() |
| return resp |
| |
| def close(self): |
| """Close the connection without assuming anything about it.""" |
| try: |
| file = self.file |
| self.file = None |
| if file is not None: |
| file.close() |
| finally: |
| sock = self.sock |
| self.sock = None |
| if sock is not None: |
| try: |
| sock.shutdown(socket.SHUT_RDWR) |
| except OSError as exc: |
| # The server might already have closed the connection. |
| # On Windows, this may result in WSAEINVAL (error 10022): |
| # An invalid operation was attempted. |
| if (exc.errno != errno.ENOTCONN |
| and getattr(exc, 'winerror', 0) != 10022): |
| raise |
| finally: |
| sock.close() |
| |
| #__del__ = quit |
| |
| |
| # optional commands: |
| |
| def rpop(self, user): |
| """Not sure what this does.""" |
| return self._shortcmd('RPOP %s' % user) |
| |
| |
| timestamp = re.compile(br'\+OK.[^<]*(<.*>)') |
| |
| def apop(self, user, password): |
| """Authorisation |
| |
| - only possible if server has supplied a timestamp in initial greeting. |
| |
| Args: |
| user - mailbox user; |
| password - mailbox password. |
| |
| NB: mailbox is locked by server from here to 'quit()' |
| """ |
| secret = bytes(password, self.encoding) |
| m = self.timestamp.match(self.welcome) |
| if not m: |
| raise error_proto('-ERR APOP not supported by server') |
| import hashlib |
| digest = m.group(1)+secret |
| digest = hashlib.md5(digest).hexdigest() |
| return self._shortcmd('APOP %s %s' % (user, digest)) |
| |
| |
| def top(self, which, howmuch): |
| """Retrieve message header of message number 'which' |
| and first 'howmuch' lines of message body. |
| |
| Result is in form ['response', ['line', ...], octets]. |
| """ |
| return self._longcmd('TOP %s %s' % (which, howmuch)) |
| |
| |
| def uidl(self, which=None): |
| """Return message digest (unique id) list. |
| |
| If 'which', result contains unique id for that message |
| in the form 'response mesgnum uid', otherwise result is |
| the list ['response', ['mesgnum uid', ...], octets] |
| """ |
| if which is not None: |
| return self._shortcmd('UIDL %s' % which) |
| return self._longcmd('UIDL') |
| |
| |
| def utf8(self): |
| """Try to enter UTF-8 mode (see RFC 6856). Returns server response. |
| """ |
| return self._shortcmd('UTF8') |
| |
| |
| def capa(self): |
| """Return server capabilities (RFC 2449) as a dictionary |
| >>> c=poplib.POP3('localhost') |
| >>> c.capa() |
| {'IMPLEMENTATION': ['Cyrus', 'POP3', 'server', 'v2.2.12'], |
| 'TOP': [], 'LOGIN-DELAY': ['0'], 'AUTH-RESP-CODE': [], |
| 'EXPIRE': ['NEVER'], 'USER': [], 'STLS': [], 'PIPELINING': [], |
| 'UIDL': [], 'RESP-CODES': []} |
| >>> |
| |
| Really, according to RFC 2449, the cyrus folks should avoid |
| having the implementation split into multiple arguments... |
| """ |
| def _parsecap(line): |
| lst = line.decode('ascii').split() |
| return lst[0], lst[1:] |
| |
| caps = {} |
| try: |
| resp = self._longcmd('CAPA') |
| rawcaps = resp[1] |
| for capline in rawcaps: |
| capnm, capargs = _parsecap(capline) |
| caps[capnm] = capargs |
| except error_proto: |
| raise error_proto('-ERR CAPA not supported by server') |
| return caps |
| |
| |
| def stls(self, context=None): |
| """Start a TLS session on the active connection as specified in RFC 2595. |
| |
| context - a ssl.SSLContext |
| """ |
| if not HAVE_SSL: |
| raise error_proto('-ERR TLS support missing') |
| if self._tls_established: |
| raise error_proto('-ERR TLS session already established') |
| caps = self.capa() |
| if not 'STLS' in caps: |
| raise error_proto('-ERR STLS not supported by server') |
| if context is None: |
| context = ssl._create_stdlib_context() |
| resp = self._shortcmd('STLS') |
| self.sock = context.wrap_socket(self.sock, |
| server_hostname=self.host) |
| self.file = self.sock.makefile('rb') |
| self._tls_established = True |
| return resp |
| |
| |
| if HAVE_SSL: |
| |
| class POP3_SSL(POP3): |
| """POP3 client class over SSL connection |
| |
| Instantiate with: POP3_SSL(hostname, port=995, keyfile=None, certfile=None, |
| context=None) |
| |
| hostname - the hostname of the pop3 over ssl server |
| port - port number |
| keyfile - PEM formatted file that contains your private key |
| certfile - PEM formatted certificate chain file |
| context - a ssl.SSLContext |
| |
| See the methods of the parent class POP3 for more documentation. |
| """ |
| |
| def __init__(self, host, port=POP3_SSL_PORT, keyfile=None, certfile=None, |
| timeout=socket._GLOBAL_DEFAULT_TIMEOUT, context=None): |
| if context is not None and keyfile is not None: |
| raise ValueError("context and keyfile arguments are mutually " |
| "exclusive") |
| if context is not None and certfile is not None: |
| raise ValueError("context and certfile arguments are mutually " |
| "exclusive") |
| if keyfile is not None or certfile is not None: |
| import warnings |
| warnings.warn("keyfile and certfile are deprecated, use a " |
| "custom context instead", DeprecationWarning, 2) |
| self.keyfile = keyfile |
| self.certfile = certfile |
| if context is None: |
| context = ssl._create_stdlib_context(certfile=certfile, |
| keyfile=keyfile) |
| self.context = context |
| POP3.__init__(self, host, port, timeout) |
| |
| def _create_socket(self, timeout): |
| sock = POP3._create_socket(self, timeout) |
| sock = self.context.wrap_socket(sock, |
| server_hostname=self.host) |
| return sock |
| |
| def stls(self, keyfile=None, certfile=None, context=None): |
| """The method unconditionally raises an exception since the |
| STLS command doesn't make any sense on an already established |
| SSL/TLS session. |
| """ |
| raise error_proto('-ERR TLS session already established') |
| |
| __all__.append("POP3_SSL") |
| |
| if __name__ == "__main__": |
| import sys |
| a = POP3(sys.argv[1]) |
| print(a.getwelcome()) |
| a.user(sys.argv[2]) |
| a.pass_(sys.argv[3]) |
| a.list() |
| (numMsgs, totalSize) = a.stat() |
| for i in range(1, numMsgs + 1): |
| (header, msg, octets) = a.retr(i) |
| print("Message %d:" % i) |
| for line in msg: |
| print(' ' + line) |
| print('-----------------------') |
| a.quit() |
