Changeset 163:c2446cf42d92 for README
Legend:
- Unmodified
- Added
- Removed
-
README
r159 r163 1 1 Introduction 2 2 ------------ 3 IMAPClient aims to be a easy-to-use, Pythonic and complete IMAP client library4 with no dependencies outside the Python standard library. 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 5 6 6 Features: 7 7 - Arguments and return values are natural Python types. 8 8 - IMAP server responses are fully parsed and readily usable. 9 - IMAP unique message IDs (UIDs) are handled transparently. There is no10 n eed 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 is13 accepted.14 - Time zones are transparently handled including when the server and client15 are in different zones.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 16 - Convenience methods are provided for commonly used functionality. 17 17 - Exceptions are raised when errors occur. 18 18 19 19 20 Why IMAPClient? 20 21 --------------- 21 You may ask: "why create another IMAP client library for Python? Doesn't the22 Python standard library already have imaplib?". 22 You may ask: "why create another IMAP client library for Python? 23 Doesn't the Python standard library already have imaplib?". 23 24 24 The problem with imaplib is that it's very low-level. It expects string values25 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. 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. 29 30 30 Also, imaplib doesn't make good use of exceptions. This means you need to check31 t he return value of each call to imaplib to see if what you just did was32 successful.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. 33 34 34 IMAPClient actually uses imaplib internally. This may change at some point in 35 the future. 35 IMAPClient actually uses imaplib internally. This may change at some 36 point in the future. 37 36 38 37 39 Current Status 38 40 -------------- 39 IMAPClient is currently under development . It is incomplete and some API's may40 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. 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. 43 45 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 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 46 56 47 57 Using IMAPClient 48 58 ---------------- 49 IMAPClient uses setuptools. To install directly from PyPI use the easy_install 50 tool: 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 51 63 52 64 easy_install IMAPClient … … 56 68 python setup.py install 57 69 58 The usual setuptools installation options are available. See 70 The usual setuptools installation options are available. See 59 71 http://peak.telecommunity.com/DevCenter/EasyInstall for more info. 60 72 61 73 See examples/example.py for a simple example of how to use IMAPClient. 62 74 63 The code is well documented. See the docstrings for more usage information. 75 The code is well documented. See the docstrings for more usage 76 information. 64 77 65 78 … … 77 90 livetest.py 78 91 ----------- 79 This is a standalone Python script which exercises IMAPClient against a live80 IMAP account. It performs operations and then attempts to confirm that these 81 have been successful.92 This is a standalone Python script which exercises IMAPClient against 93 a live IMAP account. It performs operations and then attempts to 94 confirm that these have been successful. 82 95 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. 96 It must be used with an account that has an INBOX folder and write 97 access to the account. The folders and contents of the account don't 98 matter. 85 99 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. 100 WARNING: The operations performed by livetest.py are 101 destructive. Emails and folders in the test account WILL BE 102 DELETED. Please only run against a dummy account that you don't care 103 about. 89 104 90 105 Run livetest.py with the --help option to see usage. 91 106 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. 107 Please send me the output of livetest.py if it fails to run 108 successfully against a particular IMAP server. Reports of successful 109 runs are also welcome. Please include the type and version of the 110 IMAP server. 111 95 112 96 113 Unit Tests 97 114 ---------- 98 There are fairly comprehensive unit tests for the FETCH response parser and99 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".115 There are comprehensive unit tests for the FETCH response parser and a 116 growing number of other parts of the code. These tests use unittest 117 and can be run using "python setup.py test" or "python run_tests.py".
