r"""IMAP4 client class. Instantiate with: IMAP4([host[, port[, timeout=None]]]) host - host's name (default: localhost); port - port number (default: standard IMAP4 port). timeout - socket timeout (default: None) If timeout is not given
| 135 | |
| 136 | |
| 137 | class IMAP4: |
| 138 | |
| 139 | r"""IMAP4 client class. |
| 140 | |
| 141 | Instantiate with: IMAP4([host[, port[, timeout=None]]]) |
| 142 | |
| 143 | host - host's name (default: localhost); |
| 144 | port - port number (default: standard IMAP4 port). |
| 145 | timeout - socket timeout (default: None) |
| 146 | If timeout is not given or is None, |
| 147 | the global default socket timeout is used |
| 148 | |
| 149 | All IMAP4rev1 commands are supported by methods of the same |
| 150 | name (in lowercase). |
| 151 | |
| 152 | All arguments to commands are converted to strings, except for |
| 153 | AUTHENTICATE, and the last argument to APPEND which is passed as |
| 154 | an IMAP4 literal. If necessary (the string contains any |
| 155 | non-printing characters or white-space and isn't enclosed with |
| 156 | either parentheses or double quotes) each string is quoted. |
| 157 | However, the 'password' argument to the LOGIN command is always |
| 158 | quoted. If you want to avoid having an argument string quoted |
| 159 | (eg: the 'flags' argument to STORE) then enclose the string in |
| 160 | parentheses (eg: "(\Deleted)"). |
| 161 | |
| 162 | Each command returns a tuple: (type, [data, ...]) where 'type' |
| 163 | is usually 'OK' or 'NO', and 'data' is either the text from the |
| 164 | tagged response, or untagged results from command. Each 'data' |
| 165 | is either a string, or a tuple. If a tuple, then the first part |
| 166 | is the header of the response, and the second part contains |
| 167 | the data (ie: 'literal' value). |
| 168 | |
| 169 | Errors raise the exception class <instance>.error("<reason>"). |
| 170 | IMAP4 server errors raise <instance>.abort("<reason>"), |
| 171 | which is a sub-class of 'error'. Mailbox status changes |
| 172 | from READ-WRITE to READ-ONLY raise the exception class |
| 173 | <instance>.readonly("<reason>"), which is a sub-class of 'abort'. |
| 174 | |
| 175 | "error" exceptions imply a program error. |
| 176 | "abort" exceptions imply the connection should be reset, and |
| 177 | the command re-tried. |
| 178 | "readonly" exceptions imply the command should be re-tried. |
| 179 | |
| 180 | Note: to use this module, you must read the RFCs pertaining to the |
| 181 | IMAP4 protocol, as the semantics of the arguments to each IMAP4 |
| 182 | command are left to the invoker, not to mention the results. Also, |
| 183 | most IMAP servers implement a sub-set of the commands available here. |
| 184 | """ |
| 185 | |
| 186 | class error(Exception): pass # Logical errors - debug required |
| 187 | class abort(error): pass # Service errors - close and retry |
| 188 | class readonly(abort): pass # Mailbox status changed to READ-ONLY |
| 189 | class _responsetimeout(TimeoutError): pass # No response during IDLE |
| 190 | |
| 191 | def __init__(self, host='', port=IMAP4_PORT, timeout=None): |
| 192 | self.debug = Debug |
| 193 | self.state = 'LOGOUT' |
| 194 | self.literal = None # A literal argument to a command |