Metadata-Version: 1.1
Name: greenado
Version: 0.1.1
Summary: Greenlet-based coroutines for tornado
Home-page: https://github.com/virtuald/greenado
Author: Dustin Spicuzza
Author-email: dustin@virtualroadside.com
License: Apache 2.0
Description: greenado
        ========
        
        .. image:: https://travis-ci.org/virtuald/greenado.png?branch=master
        
        Greenado is a utility library that provides greenlet-based coroutines for
        tornado. In tornado, coroutines allow you to perform asynchronous operations
        without using callbacks, providing a pseudo-synchronous flow in your 
        functions.
        
        When using gen.coroutine in tornado in a large codebase, you will notice 
        that they tend to be 'infectious' from the bottom up. In other words, for
        them to be truly useful, callers of the coroutine should 'yield' to them,
        which requires them to be a coroutine. In turn, their callers need to 'yield',
        and so on.
        
        Instead, greenado coroutines infect from the top down, and only requires
        the greenado.groutine decorator *somewhere* in the call hierarchy, but it
        doesn't really matter where. Once the decorator is used, you can use
        greenado.gyield to pseudo-synchronously wait for asynchronous events to 
        occur. This reduces complexity in large codebases, as you only need to use
        the decorator at the very top of your call trees, and nowhere else.
        
        Installation & Requirements
        ===========================
        
        .. code-block:: bash
        
            $ pip install greenado 
        
        greenado should work using tornado 3.2, but I only actively use it in
        tornado 4+
        
        I have only tested greenado on Linux & OSX, but I imagine that it would
        work correctly on platforms that tornado and greenlet support.
        
        Example usage
        =============
        
        In the below examples, 'main_function' is your toplevel function
        in the call hierarchy that needs to call things that eventually call
        some asynchronous operation in tornado.
        
        Normal tornado coroutine usage might look something like this:
        
        .. code-block:: python
        
            from tornado import gen
        
            @gen.coroutine
            def do_long_operation():
                retval = yield long_operation()
                raise gen.Return(retval)
        
            @gen.coroutine
            def call_long_operation():
                retval = yield do_long_operation()
                raise gen.Return(retval)
        
            @gen.coroutine
            def main_function():
                retval = yield call_long_operation()
        
        With greenado, it looks something like this instead:
        
        .. code-block:: python
        
            import greenado
        
            def do_long_operation():
                retval = greenado.gyield(long_operation())
                return retval
        
            def call_long_operation():
                retval = do_long_operation()
                return retval
        
            @greenado.groutine
            def main_function():
                retval = call_long_operation()
        
        Functions wrapped by greenado.groutine return a tornado.concurrent.Future
        object which you must either yield, call result(), or use IOLoop.add_future
        on, otherwise you may risk swallowing exceptions.
        
        Contributing new changes
        ========================
        
        1. Fork this repository
        2. Create your feature branch (`git checkout -b my-new-feature`)
        3. Test your changes (`tests/run_tests.sh`)
        4. Commit your changes (`git commit -am 'Add some feature'`)
        5. Push to the branch (`git push origin my-new-feature`)
        6. Create new Pull Request
        
        Credit
        ======
        
        Greenado is similar to and inspired by https://github.com/mopub/greenlet-tornado
        and https://github.com/Gawen/tornalet, but does not require that you use it from
        a tornado web handler as they do.
        
        Authors
        =======
        
        Dustin Spicuzza (dustin@virtualroadside.com)
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
