Changeset 163:c2446cf42d92

Show
Ignore:
Timestamp:
02/09/10 20:40:40 (17 months ago)
Author:
Menno Smits <menno@…>
Branch:
default
Message:

Updated README to indicate true status of the project

Also tidied up formatting and updated minor points wrt to current
reality.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • README

    r159 r163  
    11Introduction 
    22------------ 
    3 IMAPClient aims to be a easy-to-use, Pythonic and complete IMAP client library 
    4 with no dependencies outside the Python standard library.  
     3IMAPClient aims to be a easy-to-use, Pythonic and complete IMAP client 
     4library with no dependencies outside the Python standard library. 
    55 
    66Features: 
    77- Arguments and return values are natural Python types.  
    88- 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. 
     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. 
    1616- Convenience methods are provided for commonly used functionality. 
    1717- Exceptions are raised when errors occur. 
    1818 
     19 
    1920Why IMAPClient? 
    2021--------------- 
    21 You may ask: "why create another IMAP client library for Python? Doesn't the 
    22 Python standard library already have imaplib?".  
     22You may ask: "why create another IMAP client library for Python? 
     23Doesn't the Python standard library already have imaplib?". 
    2324 
    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.  
     25The problem with imaplib is that it's very low-level. It expects 
     26string values where lists or tuples would be more appropriate and 
     27returns server responses almost unparsed. As IMAP server responses can 
     28be quite complex this means everyone using imaplib ends up writing 
     29their own flimsy parsing routines which break easily. 
    2930 
    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. 
     31Also, imaplib doesn't make good use of exceptions. This means you need 
     32to check the return value of each call to imaplib to see if what you 
     33just did was successful. 
    3334 
    34 IMAPClient actually uses imaplib internally. This may change at some point in 
    35 the future. 
     35IMAPClient actually uses imaplib internally. This may change at some 
     36point in the future. 
     37 
    3638 
    3739Current Status 
    3840-------------- 
    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.  
     41IMAPClient is currently under development but it is unlikely that 
     42the existing API will change in backwards-incompatible ways. Changes 
     43planned for the near future will only add extra functionality to the 
     44API. 
    4345 
    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. 
     46You should feel confident using IMAPClient for production 
     47purposes. Any problems found will be fixed quickly once reported. 
     48 
     49The project's home page is a Trac instance at: 
     50 
     51    http://imapclient.freshfoo.com/.   
     52 
     53Details about upcoming versions and planned features/fixes can be 
     54found there. 
     55 
    4656 
    4757Using IMAPClient 
    4858---------------- 
    49 IMAPClient uses setuptools. To install directly from PyPI use the easy_install 
    50 tool: 
     59IMAPClient is listed on the PyPI (Python Package Index). To install 
     60via PyPI use the pip or easy_install tools: 
     61 
     62    pip install imapclient 
    5163 
    5264    easy_install IMAPClient 
    … …  
    5668    python setup.py install 
    5769 
    58 The usual setuptools installation options are available. See  
     70The usual setuptools installation options are available. See 
    5971http://peak.telecommunity.com/DevCenter/EasyInstall for more info. 
    6072 
    6173See examples/example.py for a simple example of how to use IMAPClient. 
    6274 
    63 The code is well documented. See the docstrings for more usage information. 
     75The code is well documented. See the docstrings for more usage 
     76information. 
    6477 
    6578 
    … …  
    7790livetest.py 
    7891----------- 
    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. 
     92This is a standalone Python script which exercises IMAPClient against 
     93a live IMAP account. It performs operations and then attempts to 
     94confirm that these have been successful. 
    8295 
    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. 
     96It must be used with an account that has an INBOX folder and write 
     97access to the account. The folders and contents of the account don't 
     98matter. 
    8599 
    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. 
     100WARNING: The operations performed by livetest.py are 
     101destructive. Emails and folders in the test account WILL BE 
     102DELETED. Please only run against a dummy account that you don't care 
     103about. 
    89104 
    90105Run livetest.py with the --help option to see usage. 
    91106 
    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. 
     107Please send me the output of livetest.py if it fails to run 
     108successfully against a particular IMAP server. Reports of successful 
     109runs are also welcome.  Please include the type and version of the 
     110IMAP server. 
     111 
    95112 
    96113Unit Tests 
    97114---------- 
    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". 
     115There are comprehensive unit tests for the FETCH response parser and a 
     116growing number of other parts of the code. These tests use unittest 
     117and can be run using "python setup.py test" or "python run_tests.py".