Metadata-Version: 1.1
Name: aioimaplib
Version: 0.5.3
Summary: Python asyncio IMAP4rev1 client library
Home-page: https://github.com/bamthomas/aioimaplib
Author: Bruno Thomas
Author-email: bruno@barreverte.fr
License: GPL-3.0
Description: About
        =====
        .. _imaplib2: https://sourceforge.net/projects/imaplib2/
        .. _imaplib: https://docs.python.org/3/library/imaplib.html
        .. _asyncio: https://docs.python.org/3/library/asyncio.html
        
        .. image:: https://travis-ci.org/bamthomas/aioimaplib.png?branch=master
           :alt: Build status
           :target: https://travis-ci.org/bamthomas/aioimaplib
        
        .. image:: https://coveralls.io/repos/github/bamthomas/aioimaplib/badge.svg
           :target: https://coveralls.io/github/bamthomas/aioimaplib
        
        This library is inspired by imaplib_ and imaplib2_ from Piers Lauder, Nicolas Sebrecht, Sebastian Spaeth. Some utilities functions are taken from imaplib/imaplib2 thanks to them.
        
        The aim is to port the imaplib with asyncio_, to benefit from the sleep or treat model.
        
        It runs with python 3.4 and 3.5.
        
        Example
        -------
        
        ::
        
            import asyncio
            from aioimaplib import aioimaplib
        
        
            @asyncio.coroutine
            def check_mailbox(host, user, password):
                imap_client = aioimaplib.IMAP4_SSL(host=host)
                yield from imap_client.wait_hello_from_server()
        
                yield from imap_client.login(user, password)
        
                res, data = yield from imap_client.select()
                print('there is %s messages INBOX' % data[0])
        
                yield from imap_client.logout()
        
        
            if __name__ == '__main__':
                loop = asyncio.get_event_loop()
                loop.run_until_complete(check_mailbox('my.imap.server', 'user', 'pass'))
        
        IDLE command
        ------------
        .. _RFC2177: https://tools.ietf.org/html/rfc2177
        
        The RFC2177_ is implemented, to be able to wait for new mail messages without using CPU. The responses are pushed in an async queue, and it is possible to read them in real time. To leave the IDLE mode, it is necessary to send a "DONE" command to the server.
        
        ::
        
            @asyncio.coroutine
            def wait_for_new_message(host, user, password):
                imap_client = aioimaplib.IMAP4_SSL(host=host)
                yield from imap_client.wait_hello_from_server()
        
                yield from imap_client.login(user, password)
                yield from imap_client.select()
        
                asyncio.async(imap_client.idle())
                while True:
                    msg = yield from imap_client.wait_server_push()
                    print('--> received from server: %s' % msg)
                    if 'EXISTS' in msg:
                        imap_client.idle_done()
                        break
        
                yield from imap_client.logout()
        
            if __name__ == '__main__':
                    loop = asyncio.get_event_loop()
                    loop.run_until_complete(wait_for_new_message('my.imap.server', 'user', 'pass'))
        
        
        Threading
        ---------
        .. _asyncio.Event: https://docs.python.org/3.4/library/asyncio-sync.html#event
        .. _asyncio.Condition: https://docs.python.org/3.4/library/asyncio-sync.html#condition
        .. _supervisor: http://supervisord.org/
        
        The IMAP4ClientProtocol class is not thread safe, it uses asyncio.Event_ and asyncio.Condition_ that are not thread safe, and state change for pending commands is not locked.
        
        It is possible to use threads but each IMAP4ClientProtocol instance should run in the same thread :
        
        .. image:: images/thread_imap_protocol.png
        
        Each color rectangle is an IMAP4ClientProtocol instance piece of code executed by the thread asyncio loop until it reaches a yield, waiting on I/O.
        
        For example, it is possible to launch 4 mono-threaded mail-fetcher processes on a 4 cores server with supervisor_, and use a distribution function like len(email) % (process_num) or whatever to share equally a mail account list between the 4 processes.
        
        IMAP command concurrency
        ------------------------
        
        IMAP protocol allows to run some commands in parallel. Four rules are implemented to ensure responses consistency:
        
        1. if a sync command is running, the following requests (sync or async) must wait
        2. if an async command is running, same async commands (or with the same untagged response type) must wait
        3. async commands can be executed in parallel
        4. sync command must wait pending async commands to finish
        
        
        Tested with
        -----------
        
        - dovecot 2.2.13 on debian Jessie
        
        Develop
        =======
        
        Developers are welcome ! If you want to improve it, fix bugs, test it with other IMAP servers, give feedback, thank you for it.
        
        To develop, just run::
        
            virtualenv --python=python3.4 venv
            source venv/bin/activate
            python setup.py develop
            pip install -r dev-requirements.txt
            nosetests
        
        To add a imaplib or imaplib2 command you can :
        
        - add the function to the testing imapserver with a new imaplib or imaplib2 server test, i.e. test_imapserver_imaplib.py or test_imapserver_imaplib2.py respectively;
        - then add the function to the aioimaplib doing almost the same test than above but the async way in test_aioimaplib.py.
        
        Not unit tested
        ---------------
        - PREAUTH
        - SSL
        
        TODO
        ----
        - STARTTLS command
        - AUTHENTICATE command
        - other commands listed in the aioimaplib Commands list
        - tests with other servers
        
        If it goes wrong
        ----------------
        Sometimes you break things and you don't understand what's going on (I always do). For this library I have two related tools:
        
        - ngrep on the imap test port : sudo ngrep -d lo port 12345
        - activate debug logs changing INFO to DEBUG at the top of the mock server and the aioimaplib
        
        
        Changes
        =======
        
        
        V0.5.3
        ------
        - fix aioimaplib bug when receiving chunked fetch data
        - do not abort when receiving unsollicited data from server
        
        V0.5.2
        ------
        - build CI environment
        - license GPL v3.0
        
        V0.5.1
        ------
        - added APPEND command
        - fix usernames can have '@' for mockimapserver
        - server can handle SEARCH with CHARSET opt parameter (but ignores it)
        
        V0.5
        ----
        - added 11 new imap commands
        - added imap command synchronizing
        - refactor
        - documentation
        
        V0.1
        ----
        - init project with mockimapserver
        - project files
        - 11 imap commands
Keywords: asyncio mail imap
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
Classifier: Topic :: Internet
