Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1 | """IMAP4 client. |
| 2 | |
| 3 | Based on RFC 2060. |
| 4 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 5 | Public class: IMAP4 |
| 6 | Public variable: Debug |
| 7 | Public functions: Internaldate2tuple |
| 8 | Int2AP |
| 9 | ParseFlags |
| 10 | Time2Internaldate |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 11 | """ |
Guido van Rossum | b1f0812 | 1998-06-25 02:22:16 +0000 | [diff] [blame] | 12 | |
Guido van Rossum | 98d9fd3 | 2000-02-28 15:12:25 +0000 | [diff] [blame] | 13 | # Author: Piers Lauder <piers@cs.su.oz.au> December 1997. |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 14 | # |
Guido van Rossum | 98d9fd3 | 2000-02-28 15:12:25 +0000 | [diff] [blame] | 15 | # Authentication code contributed by Donn Cave <donn@u.washington.edu> June 1998. |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 16 | # String method conversion by ESR, February 2001. |
Guido van Rossum | 98d9fd3 | 2000-02-28 15:12:25 +0000 | [diff] [blame] | 17 | |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 18 | __version__ = "2.40" |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 19 | |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 20 | import binascii, re, socket, time, random, sys |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 21 | |
Barry Warsaw | f449391 | 2001-01-24 04:16:09 +0000 | [diff] [blame] | 22 | __all__ = ["IMAP4", "Internaldate2tuple", |
| 23 | "Int2AP", "ParseFlags", "Time2Internaldate"] |
Skip Montanaro | 2dd4276 | 2001-01-23 15:35:05 +0000 | [diff] [blame] | 24 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 25 | # Globals |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 26 | |
| 27 | CRLF = '\r\n' |
| 28 | Debug = 0 |
| 29 | IMAP4_PORT = 143 |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 30 | AllowedVersions = ('IMAP4REV1', 'IMAP4') # Most recent first |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 31 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 32 | # Commands |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 33 | |
| 34 | Commands = { |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 35 | # name valid states |
| 36 | 'APPEND': ('AUTH', 'SELECTED'), |
| 37 | 'AUTHENTICATE': ('NONAUTH',), |
| 38 | 'CAPABILITY': ('NONAUTH', 'AUTH', 'SELECTED', 'LOGOUT'), |
| 39 | 'CHECK': ('SELECTED',), |
| 40 | 'CLOSE': ('SELECTED',), |
| 41 | 'COPY': ('SELECTED',), |
| 42 | 'CREATE': ('AUTH', 'SELECTED'), |
| 43 | 'DELETE': ('AUTH', 'SELECTED'), |
| 44 | 'EXAMINE': ('AUTH', 'SELECTED'), |
| 45 | 'EXPUNGE': ('SELECTED',), |
| 46 | 'FETCH': ('SELECTED',), |
| 47 | 'LIST': ('AUTH', 'SELECTED'), |
| 48 | 'LOGIN': ('NONAUTH',), |
| 49 | 'LOGOUT': ('NONAUTH', 'AUTH', 'SELECTED', 'LOGOUT'), |
| 50 | 'LSUB': ('AUTH', 'SELECTED'), |
| 51 | 'NOOP': ('NONAUTH', 'AUTH', 'SELECTED', 'LOGOUT'), |
| 52 | 'PARTIAL': ('SELECTED',), |
| 53 | 'RENAME': ('AUTH', 'SELECTED'), |
| 54 | 'SEARCH': ('SELECTED',), |
| 55 | 'SELECT': ('AUTH', 'SELECTED'), |
| 56 | 'STATUS': ('AUTH', 'SELECTED'), |
| 57 | 'STORE': ('SELECTED',), |
| 58 | 'SUBSCRIBE': ('AUTH', 'SELECTED'), |
| 59 | 'UID': ('SELECTED',), |
| 60 | 'UNSUBSCRIBE': ('AUTH', 'SELECTED'), |
Guido van Rossum | a85e2c8 | 2001-06-17 13:31:25 +0000 | [diff] [blame] | 61 | 'NAMESPACE': ('AUTH', 'SELECTED'), |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 62 | } |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 63 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 64 | # Patterns to match server responses |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 65 | |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 66 | Continuation = re.compile(r'\+( (?P<data>.*))?') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 67 | Flags = re.compile(r'.*FLAGS \((?P<flags>[^\)]*)\)') |
| 68 | InternalDate = re.compile(r'.*INTERNALDATE "' |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 69 | r'(?P<day>[ 123][0-9])-(?P<mon>[A-Z][a-z][a-z])-(?P<year>[0-9][0-9][0-9][0-9])' |
| 70 | r' (?P<hour>[0-9][0-9]):(?P<min>[0-9][0-9]):(?P<sec>[0-9][0-9])' |
| 71 | r' (?P<zonen>[-+])(?P<zoneh>[0-9][0-9])(?P<zonem>[0-9][0-9])' |
| 72 | r'"') |
Guido van Rossum | f36b182 | 2000-02-17 17:12:39 +0000 | [diff] [blame] | 73 | Literal = re.compile(r'.*{(?P<size>\d+)}$') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 74 | Response_code = re.compile(r'\[(?P<type>[A-Z-]+)( (?P<data>[^\]]*))?\]') |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 75 | Untagged_response = re.compile(r'\* (?P<type>[A-Z-]+)( (?P<data>.*))?') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 76 | Untagged_status = re.compile(r'\* (?P<data>\d+) (?P<type>[A-Z-]+)( (?P<data2>.*))?') |
| 77 | |
| 78 | |
| 79 | |
| 80 | class IMAP4: |
| 81 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 82 | """IMAP4 client class. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 83 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 84 | Instantiate with: IMAP4([host[, port]]) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 85 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 86 | host - host's name (default: localhost); |
| 87 | port - port number (default: standard IMAP4 port). |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 88 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 89 | All IMAP4rev1 commands are supported by methods of the same |
| 90 | name (in lower-case). |
Guido van Rossum | 6884af7 | 1998-05-29 13:34:03 +0000 | [diff] [blame] | 91 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 92 | All arguments to commands are converted to strings, except for |
| 93 | AUTHENTICATE, and the last argument to APPEND which is passed as |
| 94 | an IMAP4 literal. If necessary (the string contains any |
| 95 | non-printing characters or white-space and isn't enclosed with |
| 96 | either parentheses or double quotes) each string is quoted. |
| 97 | However, the 'password' argument to the LOGIN command is always |
| 98 | quoted. If you want to avoid having an argument string quoted |
| 99 | (eg: the 'flags' argument to STORE) then enclose the string in |
| 100 | parentheses (eg: "(\Deleted)"). |
Guido van Rossum | 6884af7 | 1998-05-29 13:34:03 +0000 | [diff] [blame] | 101 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 102 | Each command returns a tuple: (type, [data, ...]) where 'type' |
| 103 | is usually 'OK' or 'NO', and 'data' is either the text from the |
| 104 | tagged response, or untagged results from command. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 105 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 106 | Errors raise the exception class <instance>.error("<reason>"). |
| 107 | IMAP4 server errors raise <instance>.abort("<reason>"), |
| 108 | which is a sub-class of 'error'. Mailbox status changes |
| 109 | from READ-WRITE to READ-ONLY raise the exception class |
| 110 | <instance>.readonly("<reason>"), which is a sub-class of 'abort'. |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 111 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 112 | "error" exceptions imply a program error. |
| 113 | "abort" exceptions imply the connection should be reset, and |
| 114 | the command re-tried. |
| 115 | "readonly" exceptions imply the command should be re-tried. |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 116 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 117 | Note: to use this module, you must read the RFCs pertaining |
| 118 | to the IMAP4 protocol, as the semantics of the arguments to |
| 119 | each IMAP4 command are left to the invoker, not to mention |
| 120 | the results. |
| 121 | """ |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 122 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 123 | class error(Exception): pass # Logical errors - debug required |
| 124 | class abort(error): pass # Service errors - close and retry |
| 125 | class readonly(abort): pass # Mailbox status changed to READ-ONLY |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 126 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 127 | mustquote = re.compile(r"[^\w!#$%&'*+,.:;<=>?^`|~-]") |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 128 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 129 | def __init__(self, host = '', port = IMAP4_PORT): |
| 130 | self.host = host |
| 131 | self.port = port |
| 132 | self.debug = Debug |
| 133 | self.state = 'LOGOUT' |
| 134 | self.literal = None # A literal argument to a command |
| 135 | self.tagged_commands = {} # Tagged commands awaiting response |
| 136 | self.untagged_responses = {} # {typ: [data, ...], ...} |
| 137 | self.continuation_response = '' # Last continuation response |
| 138 | self.is_readonly = None # READ-ONLY desired state |
| 139 | self.tagnum = 0 |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 140 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 141 | # Open socket to server. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 142 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 143 | self.open(host, port) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 144 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 145 | # Create unique tag for this session, |
| 146 | # and compile tagged response matcher. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 147 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 148 | self.tagpre = Int2AP(random.randint(0, 31999)) |
| 149 | self.tagre = re.compile(r'(?P<tag>' |
| 150 | + self.tagpre |
| 151 | + r'\d+) (?P<type>[A-Z]+) (?P<data>.*)') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 152 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 153 | # Get server welcome message, |
| 154 | # request and store CAPABILITY response. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 155 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 156 | if __debug__: |
| 157 | if self.debug >= 1: |
| 158 | _mesg('new IMAP4 connection, tag=%s' % self.tagpre) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 159 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 160 | self.welcome = self._get_response() |
| 161 | if self.untagged_responses.has_key('PREAUTH'): |
| 162 | self.state = 'AUTH' |
| 163 | elif self.untagged_responses.has_key('OK'): |
| 164 | self.state = 'NONAUTH' |
| 165 | else: |
| 166 | raise self.error(self.welcome) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 167 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 168 | cap = 'CAPABILITY' |
| 169 | self._simple_command(cap) |
| 170 | if not self.untagged_responses.has_key(cap): |
| 171 | raise self.error('no CAPABILITY response from server') |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 172 | self.capabilities = tuple(self.untagged_responses[cap][-1].upper().split()) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 173 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 174 | if __debug__: |
| 175 | if self.debug >= 3: |
| 176 | _mesg('CAPABILITIES: %s' % `self.capabilities`) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 177 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 178 | for version in AllowedVersions: |
| 179 | if not version in self.capabilities: |
| 180 | continue |
| 181 | self.PROTOCOL_VERSION = version |
| 182 | return |
Guido van Rossum | b1f0812 | 1998-06-25 02:22:16 +0000 | [diff] [blame] | 183 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 184 | raise self.error('server not IMAP4 compliant') |
Guido van Rossum | 38d8f4e | 1998-04-11 01:22:34 +0000 | [diff] [blame] | 185 | |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 186 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 187 | def __getattr__(self, attr): |
| 188 | # Allow UPPERCASE variants of IMAP4 command methods. |
| 189 | if Commands.has_key(attr): |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 190 | return eval("self.%s" % attr.lower()) |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 191 | raise AttributeError("Unknown IMAP4 command: '%s'" % attr) |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 192 | |
| 193 | |
| 194 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 195 | # Public methods |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 196 | |
| 197 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 198 | def open(self, host, port): |
| 199 | """Setup 'self.sock' and 'self.file'.""" |
| 200 | self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| 201 | self.sock.connect((self.host, self.port)) |
| 202 | self.file = self.sock.makefile('r') |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 203 | |
| 204 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 205 | def recent(self): |
| 206 | """Return most recent 'RECENT' responses if any exist, |
| 207 | else prompt server for an update using the 'NOOP' command. |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 208 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 209 | (typ, [data]) = <instance>.recent() |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 210 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 211 | 'data' is None if no new messages, |
| 212 | else list of RECENT responses, most recent last. |
| 213 | """ |
| 214 | name = 'RECENT' |
| 215 | typ, dat = self._untagged_response('OK', [None], name) |
| 216 | if dat[-1]: |
| 217 | return typ, dat |
| 218 | typ, dat = self.noop() # Prod server for response |
| 219 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 220 | |
| 221 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 222 | def response(self, code): |
| 223 | """Return data for response 'code' if received, or None. |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 224 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 225 | Old value for response 'code' is cleared. |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 226 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 227 | (code, [data]) = <instance>.response(code) |
| 228 | """ |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 229 | return self._untagged_response(code, [None], code.upper()) |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 230 | |
| 231 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 232 | def socket(self): |
| 233 | """Return socket instance used to connect to IMAP4 server. |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 234 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 235 | socket = <instance>.socket() |
| 236 | """ |
| 237 | return self.sock |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 238 | |
| 239 | |
| 240 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 241 | # IMAP4 commands |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 242 | |
| 243 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 244 | def append(self, mailbox, flags, date_time, message): |
| 245 | """Append message to named mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 246 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 247 | (typ, [data]) = <instance>.append(mailbox, flags, date_time, message) |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 248 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 249 | All args except `message' can be None. |
| 250 | """ |
| 251 | name = 'APPEND' |
| 252 | if not mailbox: |
| 253 | mailbox = 'INBOX' |
| 254 | if flags: |
| 255 | if (flags[0],flags[-1]) != ('(',')'): |
| 256 | flags = '(%s)' % flags |
| 257 | else: |
| 258 | flags = None |
| 259 | if date_time: |
| 260 | date_time = Time2Internaldate(date_time) |
| 261 | else: |
| 262 | date_time = None |
| 263 | self.literal = message |
| 264 | return self._simple_command(name, mailbox, flags, date_time) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 265 | |
| 266 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 267 | def authenticate(self, mechanism, authobject): |
| 268 | """Authenticate command - requires response processing. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 269 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 270 | 'mechanism' specifies which authentication mechanism is to |
| 271 | be used - it must appear in <instance>.capabilities in the |
| 272 | form AUTH=<mechanism>. |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 273 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 274 | 'authobject' must be a callable object: |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 275 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 276 | data = authobject(response) |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 277 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 278 | It will be called to process server continuation responses. |
| 279 | It should return data that will be encoded and sent to server. |
| 280 | It should return None if the client abort response '*' should |
| 281 | be sent instead. |
| 282 | """ |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 283 | mech = mechanism.upper() |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 284 | cap = 'AUTH=%s' % mech |
| 285 | if not cap in self.capabilities: |
| 286 | raise self.error("Server doesn't allow %s authentication." % mech) |
| 287 | self.literal = _Authenticator(authobject).process |
| 288 | typ, dat = self._simple_command('AUTHENTICATE', mech) |
| 289 | if typ != 'OK': |
| 290 | raise self.error(dat[-1]) |
| 291 | self.state = 'AUTH' |
| 292 | return typ, dat |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 293 | |
| 294 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 295 | def check(self): |
| 296 | """Checkpoint mailbox on server. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 297 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 298 | (typ, [data]) = <instance>.check() |
| 299 | """ |
| 300 | return self._simple_command('CHECK') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 301 | |
| 302 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 303 | def close(self): |
| 304 | """Close currently selected mailbox. |
Guido van Rossum | eeec0af | 1998-04-09 14:20:31 +0000 | [diff] [blame] | 305 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 306 | Deleted messages are removed from writable mailbox. |
| 307 | This is the recommended command before 'LOGOUT'. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 308 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 309 | (typ, [data]) = <instance>.close() |
| 310 | """ |
| 311 | try: |
| 312 | typ, dat = self._simple_command('CLOSE') |
| 313 | finally: |
| 314 | self.state = 'AUTH' |
| 315 | return typ, dat |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 316 | |
| 317 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 318 | def copy(self, message_set, new_mailbox): |
| 319 | """Copy 'message_set' messages onto end of 'new_mailbox'. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 320 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 321 | (typ, [data]) = <instance>.copy(message_set, new_mailbox) |
| 322 | """ |
| 323 | return self._simple_command('COPY', message_set, new_mailbox) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 324 | |
| 325 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 326 | def create(self, mailbox): |
| 327 | """Create new mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 328 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 329 | (typ, [data]) = <instance>.create(mailbox) |
| 330 | """ |
| 331 | return self._simple_command('CREATE', mailbox) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 332 | |
| 333 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 334 | def delete(self, mailbox): |
| 335 | """Delete old mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 336 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 337 | (typ, [data]) = <instance>.delete(mailbox) |
| 338 | """ |
| 339 | return self._simple_command('DELETE', mailbox) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 340 | |
| 341 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 342 | def expunge(self): |
| 343 | """Permanently remove deleted items from selected mailbox. |
Guido van Rossum | eeec0af | 1998-04-09 14:20:31 +0000 | [diff] [blame] | 344 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 345 | Generates 'EXPUNGE' response for each deleted message. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 346 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 347 | (typ, [data]) = <instance>.expunge() |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 348 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 349 | 'data' is list of 'EXPUNGE'd message numbers in order received. |
| 350 | """ |
| 351 | name = 'EXPUNGE' |
| 352 | typ, dat = self._simple_command(name) |
| 353 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 354 | |
| 355 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 356 | def fetch(self, message_set, message_parts): |
| 357 | """Fetch (parts of) messages. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 358 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 359 | (typ, [data, ...]) = <instance>.fetch(message_set, message_parts) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 360 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 361 | 'message_parts' should be a string of selected parts |
| 362 | enclosed in parentheses, eg: "(UID BODY[TEXT])". |
Fred Drake | fd267d9 | 2000-05-25 03:25:26 +0000 | [diff] [blame] | 363 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 364 | 'data' are tuples of message part envelope and data. |
| 365 | """ |
| 366 | name = 'FETCH' |
| 367 | typ, dat = self._simple_command(name, message_set, message_parts) |
| 368 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 369 | |
| 370 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 371 | def list(self, directory='""', pattern='*'): |
| 372 | """List mailbox names in directory matching pattern. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 373 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 374 | (typ, [data]) = <instance>.list(directory='""', pattern='*') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 375 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 376 | 'data' is list of LIST responses. |
| 377 | """ |
| 378 | name = 'LIST' |
| 379 | typ, dat = self._simple_command(name, directory, pattern) |
| 380 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 381 | |
| 382 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 383 | def login(self, user, password): |
| 384 | """Identify client using plaintext password. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 385 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 386 | (typ, [data]) = <instance>.login(user, password) |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 387 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 388 | NB: 'password' will be quoted. |
| 389 | """ |
| 390 | #if not 'AUTH=LOGIN' in self.capabilities: |
| 391 | # raise self.error("Server doesn't allow LOGIN authentication." % mech) |
| 392 | typ, dat = self._simple_command('LOGIN', user, self._quote(password)) |
| 393 | if typ != 'OK': |
| 394 | raise self.error(dat[-1]) |
| 395 | self.state = 'AUTH' |
| 396 | return typ, dat |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 397 | |
| 398 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 399 | def logout(self): |
| 400 | """Shutdown connection to server. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 401 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 402 | (typ, [data]) = <instance>.logout() |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 403 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 404 | Returns server 'BYE' response. |
| 405 | """ |
| 406 | self.state = 'LOGOUT' |
| 407 | try: typ, dat = self._simple_command('LOGOUT') |
| 408 | except: typ, dat = 'NO', ['%s: %s' % sys.exc_info()[:2]] |
| 409 | self.file.close() |
| 410 | self.sock.close() |
| 411 | if self.untagged_responses.has_key('BYE'): |
| 412 | return 'BYE', self.untagged_responses['BYE'] |
| 413 | return typ, dat |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 414 | |
| 415 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 416 | def lsub(self, directory='""', pattern='*'): |
| 417 | """List 'subscribed' mailbox names in directory matching pattern. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 418 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 419 | (typ, [data, ...]) = <instance>.lsub(directory='""', pattern='*') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 420 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 421 | 'data' are tuples of message part envelope and data. |
| 422 | """ |
| 423 | name = 'LSUB' |
| 424 | typ, dat = self._simple_command(name, directory, pattern) |
| 425 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 426 | |
| 427 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 428 | def noop(self): |
| 429 | """Send NOOP command. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 430 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 431 | (typ, data) = <instance>.noop() |
| 432 | """ |
| 433 | if __debug__: |
| 434 | if self.debug >= 3: |
| 435 | _dump_ur(self.untagged_responses) |
| 436 | return self._simple_command('NOOP') |
Guido van Rossum | 6884af7 | 1998-05-29 13:34:03 +0000 | [diff] [blame] | 437 | |
| 438 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 439 | def partial(self, message_num, message_part, start, length): |
| 440 | """Fetch truncated part of a message. |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 441 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 442 | (typ, [data, ...]) = <instance>.partial(message_num, message_part, start, length) |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 443 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 444 | 'data' is tuple of message part envelope and data. |
| 445 | """ |
| 446 | name = 'PARTIAL' |
| 447 | typ, dat = self._simple_command(name, message_num, message_part, start, length) |
| 448 | return self._untagged_response(typ, dat, 'FETCH') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 449 | |
| 450 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 451 | def rename(self, oldmailbox, newmailbox): |
| 452 | """Rename old mailbox name to new. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 453 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 454 | (typ, data) = <instance>.rename(oldmailbox, newmailbox) |
| 455 | """ |
| 456 | return self._simple_command('RENAME', oldmailbox, newmailbox) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 457 | |
| 458 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 459 | def search(self, charset, *criteria): |
| 460 | """Search mailbox for matching messages. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 461 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 462 | (typ, [data]) = <instance>.search(charset, criterium, ...) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 463 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 464 | 'data' is space separated list of matching message numbers. |
| 465 | """ |
| 466 | name = 'SEARCH' |
| 467 | if charset: |
| 468 | charset = 'CHARSET ' + charset |
| 469 | typ, dat = apply(self._simple_command, (name, charset) + criteria) |
| 470 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 471 | |
| 472 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 473 | def select(self, mailbox='INBOX', readonly=None): |
| 474 | """Select a mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 475 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 476 | Flush all untagged responses. |
Guido van Rossum | 4658682 | 1998-05-18 14:39:42 +0000 | [diff] [blame] | 477 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 478 | (typ, [data]) = <instance>.select(mailbox='INBOX', readonly=None) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 479 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 480 | 'data' is count of messages in mailbox ('EXISTS' response). |
| 481 | """ |
| 482 | # Mandated responses are ('FLAGS', 'EXISTS', 'RECENT', 'UIDVALIDITY') |
| 483 | self.untagged_responses = {} # Flush old responses. |
| 484 | self.is_readonly = readonly |
| 485 | if readonly: |
| 486 | name = 'EXAMINE' |
| 487 | else: |
| 488 | name = 'SELECT' |
| 489 | typ, dat = self._simple_command(name, mailbox) |
| 490 | if typ != 'OK': |
| 491 | self.state = 'AUTH' # Might have been 'SELECTED' |
| 492 | return typ, dat |
| 493 | self.state = 'SELECTED' |
| 494 | if self.untagged_responses.has_key('READ-ONLY') \ |
| 495 | and not readonly: |
| 496 | if __debug__: |
| 497 | if self.debug >= 1: |
| 498 | _dump_ur(self.untagged_responses) |
| 499 | raise self.readonly('%s is not writable' % mailbox) |
| 500 | return typ, self.untagged_responses.get('EXISTS', [None]) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 501 | |
| 502 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 503 | def status(self, mailbox, names): |
| 504 | """Request named status conditions for mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 505 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 506 | (typ, [data]) = <instance>.status(mailbox, names) |
| 507 | """ |
| 508 | name = 'STATUS' |
| 509 | if self.PROTOCOL_VERSION == 'IMAP4': |
| 510 | raise self.error('%s unimplemented in IMAP4 (obtain IMAP4rev1 server, or re-code)' % name) |
| 511 | typ, dat = self._simple_command(name, mailbox, names) |
| 512 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 513 | |
| 514 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 515 | def store(self, message_set, command, flags): |
| 516 | """Alters flag dispositions for messages in mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 517 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 518 | (typ, [data]) = <instance>.store(message_set, command, flags) |
| 519 | """ |
| 520 | if (flags[0],flags[-1]) != ('(',')'): |
| 521 | flags = '(%s)' % flags # Avoid quoting the flags |
| 522 | typ, dat = self._simple_command('STORE', message_set, command, flags) |
| 523 | return self._untagged_response(typ, dat, 'FETCH') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 524 | |
| 525 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 526 | def subscribe(self, mailbox): |
| 527 | """Subscribe to new mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 528 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 529 | (typ, [data]) = <instance>.subscribe(mailbox) |
| 530 | """ |
| 531 | return self._simple_command('SUBSCRIBE', mailbox) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 532 | |
| 533 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 534 | def uid(self, command, *args): |
| 535 | """Execute "command arg ..." with messages identified by UID, |
| 536 | rather than message number. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 537 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 538 | (typ, [data]) = <instance>.uid(command, arg1, arg2, ...) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 539 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 540 | Returns response appropriate to 'command'. |
| 541 | """ |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 542 | command = command.upper() |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 543 | if not Commands.has_key(command): |
| 544 | raise self.error("Unknown IMAP4 UID command: %s" % command) |
| 545 | if self.state not in Commands[command]: |
| 546 | raise self.error('command %s illegal in state %s' |
| 547 | % (command, self.state)) |
| 548 | name = 'UID' |
| 549 | typ, dat = apply(self._simple_command, (name, command) + args) |
| 550 | if command == 'SEARCH': |
| 551 | name = 'SEARCH' |
| 552 | else: |
| 553 | name = 'FETCH' |
| 554 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 555 | |
| 556 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 557 | def unsubscribe(self, mailbox): |
| 558 | """Unsubscribe from old mailbox. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 559 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 560 | (typ, [data]) = <instance>.unsubscribe(mailbox) |
| 561 | """ |
| 562 | return self._simple_command('UNSUBSCRIBE', mailbox) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 563 | |
| 564 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 565 | def xatom(self, name, *args): |
| 566 | """Allow simple extension commands |
| 567 | notified by server in CAPABILITY response. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 568 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 569 | (typ, [data]) = <instance>.xatom(name, arg, ...) |
| 570 | """ |
| 571 | if name[0] != 'X' or not name in self.capabilities: |
| 572 | raise self.error('unknown extension command: %s' % name) |
| 573 | return apply(self._simple_command, (name,) + args) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 574 | |
Guido van Rossum | a85e2c8 | 2001-06-17 13:31:25 +0000 | [diff] [blame] | 575 | def namespace(self): |
Tim Peters | ff0a2bb | 2001-06-18 23:56:36 +0000 | [diff] [blame] | 576 | """ Returns IMAP namespaces ala rfc2342 |
| 577 | """ |
| 578 | name = 'NAMESPACE' |
| 579 | typ, dat = self._simple_command(name) |
| 580 | return self._untagged_response(typ, dat, name) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 581 | |
| 582 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 583 | # Private methods |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 584 | |
| 585 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 586 | def _append_untagged(self, typ, dat): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 587 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 588 | if dat is None: dat = '' |
| 589 | ur = self.untagged_responses |
| 590 | if __debug__: |
| 591 | if self.debug >= 5: |
| 592 | _mesg('untagged_responses[%s] %s += ["%s"]' % |
| 593 | (typ, len(ur.get(typ,'')), dat)) |
| 594 | if ur.has_key(typ): |
| 595 | ur[typ].append(dat) |
| 596 | else: |
| 597 | ur[typ] = [dat] |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 598 | |
| 599 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 600 | def _check_bye(self): |
| 601 | bye = self.untagged_responses.get('BYE') |
| 602 | if bye: |
| 603 | raise self.abort(bye[-1]) |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 604 | |
| 605 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 606 | def _command(self, name, *args): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 607 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 608 | if self.state not in Commands[name]: |
| 609 | self.literal = None |
| 610 | raise self.error( |
| 611 | 'command %s illegal in state %s' % (name, self.state)) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 612 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 613 | for typ in ('OK', 'NO', 'BAD'): |
| 614 | if self.untagged_responses.has_key(typ): |
| 615 | del self.untagged_responses[typ] |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 616 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 617 | if self.untagged_responses.has_key('READ-ONLY') \ |
| 618 | and not self.is_readonly: |
| 619 | raise self.readonly('mailbox status changed to READ-ONLY') |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 620 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 621 | tag = self._new_tag() |
| 622 | data = '%s %s' % (tag, name) |
| 623 | for arg in args: |
| 624 | if arg is None: continue |
| 625 | data = '%s %s' % (data, self._checkquote(arg)) |
Guido van Rossum | 6884af7 | 1998-05-29 13:34:03 +0000 | [diff] [blame] | 626 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 627 | literal = self.literal |
| 628 | if literal is not None: |
| 629 | self.literal = None |
| 630 | if type(literal) is type(self._command): |
| 631 | literator = literal |
| 632 | else: |
| 633 | literator = None |
| 634 | data = '%s {%s}' % (data, len(literal)) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 635 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 636 | if __debug__: |
| 637 | if self.debug >= 4: |
| 638 | _mesg('> %s' % data) |
| 639 | else: |
| 640 | _log('> %s' % data) |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 641 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 642 | try: |
| 643 | self.sock.send('%s%s' % (data, CRLF)) |
| 644 | except socket.error, val: |
| 645 | raise self.abort('socket error: %s' % val) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 646 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 647 | if literal is None: |
| 648 | return tag |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 649 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 650 | while 1: |
| 651 | # Wait for continuation response |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 652 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 653 | while self._get_response(): |
| 654 | if self.tagged_commands[tag]: # BAD/NO? |
| 655 | return tag |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 656 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 657 | # Send literal |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 658 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 659 | if literator: |
| 660 | literal = literator(self.continuation_response) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 661 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 662 | if __debug__: |
| 663 | if self.debug >= 4: |
| 664 | _mesg('write literal size %s' % len(literal)) |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 665 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 666 | try: |
| 667 | self.sock.send(literal) |
| 668 | self.sock.send(CRLF) |
| 669 | except socket.error, val: |
| 670 | raise self.abort('socket error: %s' % val) |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 671 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 672 | if not literator: |
| 673 | break |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 674 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 675 | return tag |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 676 | |
| 677 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 678 | def _command_complete(self, name, tag): |
| 679 | self._check_bye() |
| 680 | try: |
| 681 | typ, data = self._get_tagged_response(tag) |
| 682 | except self.abort, val: |
| 683 | raise self.abort('command: %s => %s' % (name, val)) |
| 684 | except self.error, val: |
| 685 | raise self.error('command: %s => %s' % (name, val)) |
| 686 | self._check_bye() |
| 687 | if typ == 'BAD': |
| 688 | raise self.error('%s command error: %s %s' % (name, typ, data)) |
| 689 | return typ, data |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 690 | |
| 691 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 692 | def _get_response(self): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 693 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 694 | # Read response and store. |
| 695 | # |
| 696 | # Returns None for continuation responses, |
| 697 | # otherwise first response line received. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 698 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 699 | resp = self._get_line() |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 700 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 701 | # Command completion response? |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 702 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 703 | if self._match(self.tagre, resp): |
| 704 | tag = self.mo.group('tag') |
| 705 | if not self.tagged_commands.has_key(tag): |
| 706 | raise self.abort('unexpected tagged response: %s' % resp) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 707 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 708 | typ = self.mo.group('type') |
| 709 | dat = self.mo.group('data') |
| 710 | self.tagged_commands[tag] = (typ, [dat]) |
| 711 | else: |
| 712 | dat2 = None |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 713 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 714 | # '*' (untagged) responses? |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 715 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 716 | if not self._match(Untagged_response, resp): |
| 717 | if self._match(Untagged_status, resp): |
| 718 | dat2 = self.mo.group('data2') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 719 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 720 | if self.mo is None: |
| 721 | # Only other possibility is '+' (continuation) response... |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 722 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 723 | if self._match(Continuation, resp): |
| 724 | self.continuation_response = self.mo.group('data') |
| 725 | return None # NB: indicates continuation |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 726 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 727 | raise self.abort("unexpected response: '%s'" % resp) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 728 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 729 | typ = self.mo.group('type') |
| 730 | dat = self.mo.group('data') |
| 731 | if dat is None: dat = '' # Null untagged response |
| 732 | if dat2: dat = dat + ' ' + dat2 |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 733 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 734 | # Is there a literal to come? |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 735 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 736 | while self._match(Literal, dat): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 737 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 738 | # Read literal direct from connection. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 739 | |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 740 | size = int(self.mo.group('size')) |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 741 | if __debug__: |
| 742 | if self.debug >= 4: |
| 743 | _mesg('read literal size %s' % size) |
| 744 | data = self.file.read(size) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 745 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 746 | # Store response with literal as tuple |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 747 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 748 | self._append_untagged(typ, (dat, data)) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 749 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 750 | # Read trailer - possibly containing another literal |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 751 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 752 | dat = self._get_line() |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 753 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 754 | self._append_untagged(typ, dat) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 755 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 756 | # Bracketed response information? |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 757 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 758 | if typ in ('OK', 'NO', 'BAD') and self._match(Response_code, dat): |
| 759 | self._append_untagged(self.mo.group('type'), self.mo.group('data')) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 760 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 761 | if __debug__: |
| 762 | if self.debug >= 1 and typ in ('NO', 'BAD', 'BYE'): |
| 763 | _mesg('%s response: %s' % (typ, dat)) |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 764 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 765 | return resp |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 766 | |
| 767 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 768 | def _get_tagged_response(self, tag): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 769 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 770 | while 1: |
| 771 | result = self.tagged_commands[tag] |
| 772 | if result is not None: |
| 773 | del self.tagged_commands[tag] |
| 774 | return result |
Guido van Rossum | f36b182 | 2000-02-17 17:12:39 +0000 | [diff] [blame] | 775 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 776 | # Some have reported "unexpected response" exceptions. |
| 777 | # Note that ignoring them here causes loops. |
| 778 | # Instead, send me details of the unexpected response and |
| 779 | # I'll update the code in `_get_response()'. |
Guido van Rossum | f36b182 | 2000-02-17 17:12:39 +0000 | [diff] [blame] | 780 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 781 | try: |
| 782 | self._get_response() |
| 783 | except self.abort, val: |
| 784 | if __debug__: |
| 785 | if self.debug >= 1: |
| 786 | print_log() |
| 787 | raise |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 788 | |
| 789 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 790 | def _get_line(self): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 791 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 792 | line = self.file.readline() |
| 793 | if not line: |
| 794 | raise self.abort('socket error: EOF') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 795 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 796 | # Protocol mandates all lines terminated by CRLF |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 797 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 798 | line = line[:-2] |
| 799 | if __debug__: |
| 800 | if self.debug >= 4: |
| 801 | _mesg('< %s' % line) |
| 802 | else: |
| 803 | _log('< %s' % line) |
| 804 | return line |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 805 | |
| 806 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 807 | def _match(self, cre, s): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 808 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 809 | # Run compiled regular expression match method on 's'. |
| 810 | # Save result, return success. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 811 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 812 | self.mo = cre.match(s) |
| 813 | if __debug__: |
| 814 | if self.mo is not None and self.debug >= 5: |
| 815 | _mesg("\tmatched r'%s' => %s" % (cre.pattern, `self.mo.groups()`)) |
| 816 | return self.mo is not None |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 817 | |
| 818 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 819 | def _new_tag(self): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 820 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 821 | tag = '%s%s' % (self.tagpre, self.tagnum) |
| 822 | self.tagnum = self.tagnum + 1 |
| 823 | self.tagged_commands[tag] = None |
| 824 | return tag |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 825 | |
| 826 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 827 | def _checkquote(self, arg): |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 828 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 829 | # Must quote command args if non-alphanumeric chars present, |
| 830 | # and not already quoted. |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 831 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 832 | if type(arg) is not type(''): |
| 833 | return arg |
| 834 | if (arg[0],arg[-1]) in (('(',')'),('"','"')): |
| 835 | return arg |
| 836 | if self.mustquote.search(arg) is None: |
| 837 | return arg |
| 838 | return self._quote(arg) |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 839 | |
| 840 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 841 | def _quote(self, arg): |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 842 | |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 843 | arg = arg.replace('\\', '\\\\') |
| 844 | arg = arg.replace('"', '\\"') |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 845 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 846 | return '"%s"' % arg |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 847 | |
| 848 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 849 | def _simple_command(self, name, *args): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 850 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 851 | return self._command_complete(name, apply(self._command, (name,) + args)) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 852 | |
| 853 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 854 | def _untagged_response(self, typ, dat, name): |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 855 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 856 | if typ == 'NO': |
| 857 | return typ, dat |
| 858 | if not self.untagged_responses.has_key(name): |
| 859 | return typ, [None] |
| 860 | data = self.untagged_responses[name] |
| 861 | if __debug__: |
| 862 | if self.debug >= 5: |
| 863 | _mesg('untagged_responses[%s] => %s' % (name, data)) |
| 864 | del self.untagged_responses[name] |
| 865 | return typ, data |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 866 | |
| 867 | |
| 868 | |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 869 | class _Authenticator: |
| 870 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 871 | """Private class to provide en/decoding |
| 872 | for base64-based authentication conversation. |
| 873 | """ |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 874 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 875 | def __init__(self, mechinst): |
| 876 | self.mech = mechinst # Callable object to provide/process data |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 877 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 878 | def process(self, data): |
| 879 | ret = self.mech(self.decode(data)) |
| 880 | if ret is None: |
| 881 | return '*' # Abort conversation |
| 882 | return self.encode(ret) |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 883 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 884 | def encode(self, inp): |
| 885 | # |
| 886 | # Invoke binascii.b2a_base64 iteratively with |
| 887 | # short even length buffers, strip the trailing |
| 888 | # line feed from the result and append. "Even" |
| 889 | # means a number that factors to both 6 and 8, |
| 890 | # so when it gets to the end of the 8-bit input |
| 891 | # there's no partial 6-bit output. |
| 892 | # |
| 893 | oup = '' |
| 894 | while inp: |
| 895 | if len(inp) > 48: |
| 896 | t = inp[:48] |
| 897 | inp = inp[48:] |
| 898 | else: |
| 899 | t = inp |
| 900 | inp = '' |
| 901 | e = binascii.b2a_base64(t) |
| 902 | if e: |
| 903 | oup = oup + e[:-1] |
| 904 | return oup |
| 905 | |
| 906 | def decode(self, inp): |
| 907 | if not inp: |
| 908 | return '' |
| 909 | return binascii.a2b_base64(inp) |
| 910 | |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 911 | |
| 912 | |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 913 | Mon2num = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6, |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 914 | 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12} |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 915 | |
| 916 | def Internaldate2tuple(resp): |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 917 | """Convert IMAP4 INTERNALDATE to UT. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 918 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 919 | Returns Python time module tuple. |
| 920 | """ |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 921 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 922 | mo = InternalDate.match(resp) |
| 923 | if not mo: |
| 924 | return None |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 925 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 926 | mon = Mon2num[mo.group('mon')] |
| 927 | zonen = mo.group('zonen') |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 928 | |
Jeremy Hylton | f5d3ea0 | 2001-02-22 13:24:27 +0000 | [diff] [blame] | 929 | day = int(mo.group('day')) |
| 930 | year = int(mo.group('year')) |
| 931 | hour = int(mo.group('hour')) |
| 932 | min = int(mo.group('min')) |
| 933 | sec = int(mo.group('sec')) |
| 934 | zoneh = int(mo.group('zoneh')) |
| 935 | zonem = int(mo.group('zonem')) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 936 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 937 | # INTERNALDATE timezone must be subtracted to get UT |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 938 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 939 | zone = (zoneh*60 + zonem)*60 |
| 940 | if zonen == '-': |
| 941 | zone = -zone |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 942 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 943 | tt = (year, mon, day, hour, min, sec, -1, -1, -1) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 944 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 945 | utc = time.mktime(tt) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 946 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 947 | # Following is necessary because the time module has no 'mkgmtime'. |
| 948 | # 'mktime' assumes arg in local timezone, so adds timezone/altzone. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 949 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 950 | lt = time.localtime(utc) |
| 951 | if time.daylight and lt[-1]: |
| 952 | zone = zone + time.altzone |
| 953 | else: |
| 954 | zone = zone + time.timezone |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 955 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 956 | return time.localtime(utc - zone) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 957 | |
| 958 | |
| 959 | |
| 960 | def Int2AP(num): |
| 961 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 962 | """Convert integer to A-P string representation.""" |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 963 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 964 | val = ''; AP = 'ABCDEFGHIJKLMNOP' |
| 965 | num = int(abs(num)) |
| 966 | while num: |
| 967 | num, mod = divmod(num, 16) |
| 968 | val = AP[mod] + val |
| 969 | return val |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 970 | |
| 971 | |
| 972 | |
| 973 | def ParseFlags(resp): |
| 974 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 975 | """Convert IMAP4 flags response to python tuple.""" |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 976 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 977 | mo = Flags.match(resp) |
| 978 | if not mo: |
| 979 | return () |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 980 | |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 981 | return tuple(mo.group('flags').split()) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 982 | |
| 983 | |
| 984 | def Time2Internaldate(date_time): |
| 985 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 986 | """Convert 'date_time' to IMAP4 INTERNALDATE representation. |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 987 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 988 | Return string in form: '"DD-Mmm-YYYY HH:MM:SS +HHMM"' |
| 989 | """ |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 990 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 991 | dttype = type(date_time) |
| 992 | if dttype is type(1) or dttype is type(1.1): |
| 993 | tt = time.localtime(date_time) |
| 994 | elif dttype is type(()): |
| 995 | tt = date_time |
| 996 | elif dttype is type(""): |
| 997 | return date_time # Assume in correct format |
| 998 | else: raise ValueError |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 999 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1000 | dt = time.strftime("%d-%b-%Y %H:%M:%S", tt) |
| 1001 | if dt[0] == '0': |
| 1002 | dt = ' ' + dt[1:] |
| 1003 | if time.daylight and tt[-1]: |
| 1004 | zone = -time.altzone |
| 1005 | else: |
| 1006 | zone = -time.timezone |
| 1007 | return '"' + dt + " %+02d%02d" % divmod(zone/60, 60) + '"' |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1008 | |
| 1009 | |
| 1010 | |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 1011 | if __debug__: |
| 1012 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1013 | def _mesg(s, secs=None): |
| 1014 | if secs is None: |
| 1015 | secs = time.time() |
| 1016 | tm = time.strftime('%M:%S', time.localtime(secs)) |
| 1017 | sys.stderr.write(' %s.%02d %s\n' % (tm, (secs*100)%100, s)) |
| 1018 | sys.stderr.flush() |
Guido van Rossum | 26367a0 | 1998-09-28 15:34:46 +0000 | [diff] [blame] | 1019 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1020 | def _dump_ur(dict): |
| 1021 | # Dump untagged responses (in `dict'). |
| 1022 | l = dict.items() |
| 1023 | if not l: return |
| 1024 | t = '\n\t\t' |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 1025 | l = map(lambda x:'%s: "%s"' % (x[0], x[1][0] and '" "'.join(x[1]) or ''), l) |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1026 | _mesg('untagged responses dump:%s%s' % (t, j(l, t))) |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 1027 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1028 | _cmd_log = [] # Last `_cmd_log_len' interactions |
| 1029 | _cmd_log_len = 10 |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 1030 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1031 | def _log(line): |
| 1032 | # Keep log of last `_cmd_log_len' interactions for debugging. |
| 1033 | if len(_cmd_log) == _cmd_log_len: |
| 1034 | del _cmd_log[0] |
| 1035 | _cmd_log.append((time.time(), line)) |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 1036 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1037 | def print_log(): |
| 1038 | _mesg('last %d IMAP4 interactions:' % len(_cmd_log)) |
| 1039 | for secs,line in _cmd_log: |
| 1040 | _mesg(line, secs) |
Guido van Rossum | eda960a | 1998-06-18 14:24:28 +0000 | [diff] [blame] | 1041 | |
| 1042 | |
Guido van Rossum | 8c06221 | 1999-12-13 23:27:45 +0000 | [diff] [blame] | 1043 | |
| 1044 | if __name__ == '__main__': |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1045 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1046 | import getopt, getpass, sys |
Guido van Rossum | d659693 | 1998-05-29 18:08:48 +0000 | [diff] [blame] | 1047 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1048 | try: |
| 1049 | optlist, args = getopt.getopt(sys.argv[1:], 'd:') |
| 1050 | except getopt.error, val: |
| 1051 | pass |
Guido van Rossum | 66d4513 | 2000-03-28 20:20:53 +0000 | [diff] [blame] | 1052 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1053 | for opt,val in optlist: |
| 1054 | if opt == '-d': |
| 1055 | Debug = int(val) |
Guido van Rossum | 66d4513 | 2000-03-28 20:20:53 +0000 | [diff] [blame] | 1056 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1057 | if not args: args = ('',) |
Guido van Rossum | 66d4513 | 2000-03-28 20:20:53 +0000 | [diff] [blame] | 1058 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1059 | host = args[0] |
Guido van Rossum | b1f0812 | 1998-06-25 02:22:16 +0000 | [diff] [blame] | 1060 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1061 | USER = getpass.getuser() |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 1062 | PASSWD = getpass.getpass("IMAP password for %s on %s:" % (USER, host or "localhost")) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1063 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1064 | test_mesg = 'From: %s@localhost\nSubject: IMAP4 test\n\ndata...\n' % USER |
| 1065 | test_seq1 = ( |
| 1066 | ('login', (USER, PASSWD)), |
| 1067 | ('create', ('/tmp/xxx 1',)), |
| 1068 | ('rename', ('/tmp/xxx 1', '/tmp/yyy')), |
| 1069 | ('CREATE', ('/tmp/yyz 2',)), |
| 1070 | ('append', ('/tmp/yyz 2', None, None, test_mesg)), |
| 1071 | ('list', ('/tmp', 'yy*')), |
| 1072 | ('select', ('/tmp/yyz 2',)), |
| 1073 | ('search', (None, 'SUBJECT', 'test')), |
| 1074 | ('partial', ('1', 'RFC822', 1, 1024)), |
| 1075 | ('store', ('1', 'FLAGS', '(\Deleted)')), |
| 1076 | ('expunge', ()), |
| 1077 | ('recent', ()), |
| 1078 | ('close', ()), |
| 1079 | ) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1080 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1081 | test_seq2 = ( |
| 1082 | ('select', ()), |
| 1083 | ('response',('UIDVALIDITY',)), |
| 1084 | ('uid', ('SEARCH', 'ALL')), |
| 1085 | ('response', ('EXISTS',)), |
| 1086 | ('append', (None, None, None, test_mesg)), |
| 1087 | ('recent', ()), |
| 1088 | ('logout', ()), |
| 1089 | ) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1090 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1091 | def run(cmd, args): |
| 1092 | _mesg('%s %s' % (cmd, args)) |
| 1093 | typ, dat = apply(eval('M.%s' % cmd), args) |
| 1094 | _mesg('%s => %s %s' % (cmd, typ, dat)) |
| 1095 | return dat |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1096 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1097 | try: |
| 1098 | M = IMAP4(host) |
| 1099 | _mesg('PROTOCOL_VERSION = %s' % M.PROTOCOL_VERSION) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1100 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1101 | for cmd,args in test_seq1: |
| 1102 | run(cmd, args) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1103 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1104 | for ml in run('list', ('/tmp/', 'yy%')): |
| 1105 | mo = re.match(r'.*"([^"]+)"$', ml) |
| 1106 | if mo: path = mo.group(1) |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 1107 | else: path = ml.split()[-1] |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1108 | run('delete', (path,)) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1109 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1110 | for cmd,args in test_seq2: |
| 1111 | dat = run(cmd, args) |
Guido van Rossum | c2c07fa | 1998-04-09 13:51:46 +0000 | [diff] [blame] | 1112 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1113 | if (cmd,args) != ('uid', ('SEARCH', 'ALL')): |
| 1114 | continue |
Guido van Rossum | 38d8f4e | 1998-04-11 01:22:34 +0000 | [diff] [blame] | 1115 | |
Eric S. Raymond | 25a0cbc | 2001-02-09 06:50:21 +0000 | [diff] [blame] | 1116 | uid = dat[-1].split() |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1117 | if not uid: continue |
| 1118 | run('uid', ('FETCH', '%s' % uid[-1], |
| 1119 | '(FLAGS INTERNALDATE RFC822.SIZE RFC822.HEADER RFC822.TEXT)')) |
Guido van Rossum | 66d4513 | 2000-03-28 20:20:53 +0000 | [diff] [blame] | 1120 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1121 | print '\nAll tests OK.' |
Guido van Rossum | 66d4513 | 2000-03-28 20:20:53 +0000 | [diff] [blame] | 1122 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1123 | except: |
| 1124 | print '\nTests failed.' |
Guido van Rossum | 66d4513 | 2000-03-28 20:20:53 +0000 | [diff] [blame] | 1125 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1126 | if not Debug: |
| 1127 | print ''' |
Guido van Rossum | 66d4513 | 2000-03-28 20:20:53 +0000 | [diff] [blame] | 1128 | If you would like to see debugging output, |
| 1129 | try: %s -d5 |
| 1130 | ''' % sys.argv[0] |
| 1131 | |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 1132 | raise |