| 1 | Introduction |
|---|
| 2 | ------------ |
|---|
| 3 | IMAPClient aims to be a easy-to-use, Pythonic and complete IMAP client |
|---|
| 4 | library 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 |
|---|
| 10 | no need to call different methods to use UIDs. |
|---|
| 11 | - Escaping for internationalised mailbox names is transparently |
|---|
| 12 | handled. Unicode mailbox names may be passed as input wherever a |
|---|
| 13 | folder name is accepted. |
|---|
| 14 | - Time zones are transparently handled including when the server and |
|---|
| 15 | client are in different zones. |
|---|
| 16 | - Convenience methods are provided for commonly used functionality. |
|---|
| 17 | - Exceptions are raised when errors occur. |
|---|
| 18 | |
|---|
| 19 | |
|---|
| 20 | Why IMAPClient? |
|---|
| 21 | --------------- |
|---|
| 22 | You may ask: "why create another IMAP client library for Python? |
|---|
| 23 | Doesn't the Python standard library already have imaplib?". |
|---|
| 24 | |
|---|
| 25 | The problem with imaplib is that it's very low-level. It expects |
|---|
| 26 | string values where lists or tuples would be more appropriate and |
|---|
| 27 | returns server responses almost unparsed. As IMAP server responses can |
|---|
| 28 | be quite complex this means everyone using imaplib ends up writing |
|---|
| 29 | their own flimsy parsing routines which break easily. |
|---|
| 30 | |
|---|
| 31 | Also, imaplib doesn't make good use of exceptions. This means you need |
|---|
| 32 | to check the return value of each call to imaplib to see if what you |
|---|
| 33 | just did was successful. |
|---|
| 34 | |
|---|
| 35 | IMAPClient actually uses imaplib internally. This may change at some |
|---|
| 36 | point in the future. |
|---|
| 37 | |
|---|
| 38 | |
|---|
| 39 | Current Status |
|---|
| 40 | -------------- |
|---|
| 41 | IMAPClient is currently under development but it is unlikely that |
|---|
| 42 | the existing API will change in backwards-incompatible ways. Changes |
|---|
| 43 | planned for the near future will only add extra functionality to the |
|---|
| 44 | API. |
|---|
| 45 | |
|---|
| 46 | You should feel confident using IMAPClient for production |
|---|
| 47 | purposes. Any problems found will be fixed quickly once reported. |
|---|
| 48 | |
|---|
| 49 | The project's home page is a Trac instance at: |
|---|
| 50 | |
|---|
| 51 | http://imapclient.freshfoo.com/ |
|---|
| 52 | |
|---|
| 53 | Details about upcoming versions and planned features/fixes can be |
|---|
| 54 | found there. |
|---|
| 55 | |
|---|
| 56 | |
|---|
| 57 | Using IMAPClient |
|---|
| 58 | ---------------- |
|---|
| 59 | IMAPClient is listed on the PyPI (Python Package Index). To install |
|---|
| 60 | via PyPI use the pip or easy_install tools: |
|---|
| 61 | |
|---|
| 62 | pip install imapclient |
|---|
| 63 | |
|---|
| 64 | easy_install IMAPClient |
|---|
| 65 | |
|---|
| 66 | To install from the source distribution: |
|---|
| 67 | |
|---|
| 68 | python setup.py install |
|---|
| 69 | |
|---|
| 70 | The project is packaged using Distribute (mostly compatible with |
|---|
| 71 | setuptools) and all the usual setup.py installation options are |
|---|
| 72 | available. See http://packages.python.org/distribute/ for more info. |
|---|
| 73 | |
|---|
| 74 | |
|---|
| 75 | Documentation |
|---|
| 76 | ------------- |
|---|
| 77 | HTML documentation can be found at doc/html in the source |
|---|
| 78 | distribution. The documentation is also available online at: |
|---|
| 79 | |
|---|
| 80 | http://imapclient.readthedocs.org/ |
|---|
| 81 | |
|---|
| 82 | The Sphinx source is at doc/src. If Sphinx is installed, the |
|---|
| 83 | documentation can be rebuilt using: |
|---|
| 84 | |
|---|
| 85 | python setup.py build_sphinx |
|---|
| 86 | |
|---|
| 87 | See imapclient/examples/example.py for a sample of how to use |
|---|
| 88 | IMAPClient. If the IMAPClient was installed from PyPI the examples |
|---|
| 89 | subdirectory can be found under the imapclient package installation |
|---|
| 90 | directory. |
|---|
| 91 | |
|---|
| 92 | |
|---|
| 93 | Mailing List |
|---|
| 94 | ------------ |
|---|
| 95 | The IMAPClient mailing list can be used to ask IMAPClient related |
|---|
| 96 | questions and report bugs. |
|---|
| 97 | |
|---|
| 98 | * To send to the list and subscribe send an email to imapclient@librelist.com |
|---|
| 99 | * Archives of the list are available at http://librelist.com/browser/imapclient/ |
|---|
| 100 | * See http://librelist.com/help.html for more information about the mailing list |
|---|
| 101 | |
|---|
| 102 | |
|---|
| 103 | interact.py |
|---|
| 104 | ----------- |
|---|
| 105 | This script connects an IMAPClient instance using the command line |
|---|
| 106 | args given and starts an interactive session. This is useful for |
|---|
| 107 | exploring the IMAPClient API and testing things out, avoiding the |
|---|
| 108 | steps required to set up an IMAPClient instance. |
|---|
| 109 | |
|---|
| 110 | The IPython shell is used if it is installed. Otherwise the |
|---|
| 111 | code.interact() function from the standard library is used. |
|---|
| 112 | |
|---|
| 113 | The interact functionality can also be accessed like this: |
|---|
| 114 | |
|---|
| 115 | python -m imapclient.interact ... |
|---|
| 116 | |
|---|
| 117 | This works when IMAPClient has been installed from PyPI. |
|---|
| 118 | |
|---|
| 119 | |
|---|
| 120 | livetest.py |
|---|
| 121 | ----------- |
|---|
| 122 | This script contains a series of functional tests which exercise |
|---|
| 123 | IMAPClient against a live IMAP account. It is useful for ensuring |
|---|
| 124 | compatibility with a given IMAP server implementation. livetest.py |
|---|
| 125 | must be used with an account that has an INBOX folder and write access |
|---|
| 126 | to the account. |
|---|
| 127 | |
|---|
| 128 | WARNING: The operations performed by livetest.py are |
|---|
| 129 | destructive. Emails and folders in the test account WILL BE |
|---|
| 130 | DELETED. Please only run against a dummy account that you don't care |
|---|
| 131 | about. |
|---|
| 132 | |
|---|
| 133 | Run livetest.py with the --help option to see usage. |
|---|
| 134 | |
|---|
| 135 | Please send the output of livetest.py to the mailing list if it fails |
|---|
| 136 | to run successfully against a particular IMAP server. Reports of |
|---|
| 137 | successful runs are also welcome. Please include the type and version |
|---|
| 138 | of the IMAP server. |
|---|
| 139 | |
|---|
| 140 | The livetest functionality can also be accessed like this: |
|---|
| 141 | |
|---|
| 142 | python -m imapclient.livetest ... |
|---|
| 143 | |
|---|
| 144 | This works when IMAPClient has been installed from PyPI. |
|---|
| 145 | |
|---|
| 146 | |
|---|
| 147 | Unit Tests |
|---|
| 148 | ---------- |
|---|
| 149 | There are comprehensive unit tests for the server response parser and |
|---|
| 150 | a number of other parts of the code. These tests use the unittest2 |
|---|
| 151 | package which is also included as the standard unittest package in |
|---|
| 152 | Python 2.7 and 3.2. |
|---|
| 153 | |
|---|
| 154 | Where unittest2 is included in the standard library (eg. Python 2.7 |
|---|
| 155 | and 3.2) you can run all unit tests like this (starting from the root |
|---|
| 156 | directory of the IMAPClient source): |
|---|
| 157 | |
|---|
| 158 | python -m unittest discover |
|---|
| 159 | |
|---|
| 160 | Alternatively, if unittest2 is installed separately use the unit2 |
|---|
| 161 | script (for Unix-like systems) or the unit2.py script: |
|---|
| 162 | |
|---|
| 163 | unit2 discover |
|---|
| 164 | unit2.py discover |
|---|