| 1 | Introduction |
|---|
| 2 | ------------ |
|---|
| 3 | IMAPClient aims to be a easy-to-use, Pythonic and complete IMAP client library |
|---|
| 4 | with no dependencies outside the Python standard library. |
|---|
| 5 | |
|---|
| 6 | Features: |
|---|
| 7 | - Arguments and return values are natural Python types. |
|---|
| 8 | - IMAP server responses are fully parsed and readily usable. |
|---|
| 9 | - IMAP unique message IDs (UIDs) are handled transparently. There is no |
|---|
| 10 | need to call different methods to use UIDs. |
|---|
| 11 | - Escaping for internationalised mailbox names is transparently handled. |
|---|
| 12 | Unicode mailbox names may be passed as input wherever a folder name is |
|---|
| 13 | accepted. |
|---|
| 14 | - Time zones are transparently handled including when the server and client |
|---|
| 15 | are in different zones. |
|---|
| 16 | - Convenience methods are provided for commonly used functionality. |
|---|
| 17 | - Exceptions are raised when errors occur. |
|---|
| 18 | |
|---|
| 19 | Why IMAPClient? |
|---|
| 20 | --------------- |
|---|
| 21 | You may ask: "why create another IMAP client library for Python? Doesn't the |
|---|
| 22 | Python standard library already have imaplib?". |
|---|
| 23 | |
|---|
| 24 | The problem with imaplib is that it's very low-level. It expects string values |
|---|
| 25 | where lists or tuples would be more appropriate and returns server responses |
|---|
| 26 | almost unparsed. As IMAP server responses can be quite complex this means |
|---|
| 27 | everyone using imaplib ends up writing their own flimsy parsing routines which |
|---|
| 28 | break easily. |
|---|
| 29 | |
|---|
| 30 | Also, imaplib doesn't make good use of exceptions. This means you need to check |
|---|
| 31 | the return value of each call to imaplib to see if what you just did was |
|---|
| 32 | successful. |
|---|
| 33 | |
|---|
| 34 | IMAPClient actually uses imaplib internally. This may change at some point in |
|---|
| 35 | the future. |
|---|
| 36 | |
|---|
| 37 | Current Status |
|---|
| 38 | -------------- |
|---|
| 39 | IMAPClient is currently under development. It is incomplete and some API's may |
|---|
| 40 | change in the near future. There's still a significant amount of IMAP |
|---|
| 41 | functionality that the IMAPClient class doesn't cover yet. That said, what's |
|---|
| 42 | there now is documented, has been tested and should be fairly solid. |
|---|
| 43 | |
|---|
| 44 | The project's home page is a Trac instance at http://imapclient.freshfoo.com/. |
|---|
| 45 | Details about upcoming versions and planned features/fixes can be found there. |
|---|
| 46 | |
|---|
| 47 | Using IMAPClient |
|---|
| 48 | ---------------- |
|---|
| 49 | IMAPClient uses setuptools. To install directly from PyPI use the easy_install |
|---|
| 50 | tool: |
|---|
| 51 | |
|---|
| 52 | easy_install IMAPClient |
|---|
| 53 | |
|---|
| 54 | To install from the source distribution: |
|---|
| 55 | |
|---|
| 56 | python setup.py install |
|---|
| 57 | |
|---|
| 58 | The usual setuptools installation options are available. See |
|---|
| 59 | http://peak.telecommunity.com/DevCenter/EasyInstall for more info. |
|---|
| 60 | |
|---|
| 61 | See examples/example.py for a simple example of how to use IMAPClient. |
|---|
| 62 | |
|---|
| 63 | The code is well documented. See the docstrings for more usage information. |
|---|
| 64 | |
|---|
| 65 | |
|---|
| 66 | interact.py |
|---|
| 67 | ----------- |
|---|
| 68 | This script connects an IMAPClient instance using the command line |
|---|
| 69 | args given and starts an interactive session. This is useful for |
|---|
| 70 | exploring the IMAPClient API and testing things out, avoiding the |
|---|
| 71 | steps required to set up an IMAPClient instance. |
|---|
| 72 | |
|---|
| 73 | The IPython shell is used if it is installed. Otherwise the |
|---|
| 74 | code.interact() function from the standard library is used. |
|---|
| 75 | |
|---|
| 76 | |
|---|
| 77 | livetest.py |
|---|
| 78 | ----------- |
|---|
| 79 | This is a standalone Python script which exercises IMAPClient against a live |
|---|
| 80 | IMAP account. It performs operations and then attempts to confirm that these |
|---|
| 81 | have been successful. |
|---|
| 82 | |
|---|
| 83 | It must be used with an account that has an INBOX folder and write access to |
|---|
| 84 | the account. The folders and contents of the account don't matter. |
|---|
| 85 | |
|---|
| 86 | WARNING: The operations performed by livetest.py are destructive. Emails and |
|---|
| 87 | folders in the test account WILL BE DELETED. Please only run against a dummy |
|---|
| 88 | account that you don't care about. |
|---|
| 89 | |
|---|
| 90 | Run livetest.py with the --help option to see usage. |
|---|
| 91 | |
|---|
| 92 | Please send me the output of livetest.py if it fails to run successfully |
|---|
| 93 | against a particular IMAP server. Reports of successful runs are also welcome. |
|---|
| 94 | Send the type and version of the IMAP server. |
|---|
| 95 | |
|---|
| 96 | Unit Tests |
|---|
| 97 | ---------- |
|---|
| 98 | There are fairly comprehensive unit tests for the FETCH response parser and |
|---|
| 99 | a growing number of other parts of the code. These tests use unittest and can |
|---|
| 100 | be run using "python setup.py test" or "python run_tests.py". |
|---|
