diff options
Diffstat (limited to 'doc/using.rst')
| -rw-r--r-- | doc/using.rst | 176 |
1 files changed, 133 insertions, 43 deletions
diff --git a/doc/using.rst b/doc/using.rst index 325d647..f42f0e3 100644 --- a/doc/using.rst +++ b/doc/using.rst @@ -4,9 +4,9 @@ Usage Use aiogreen with trollius -------------------------- -To support Python 2, you can use Trollius which uses ``yield`` instead -of ``yield from`` for coroutines: -http://trollius.readthedocs.org/ +aiogreen can be used with trollius, coroutines written with ``yield +From(...)``. Using aiogreen with trollius is a good start to port project +written for eventlet to trollius. To use aiogreen with trollius, set the event loop policy before using an event loop, example:: @@ -32,17 +32,16 @@ Hello World:: loop.run_forever() loop.close() +.. seealso:: + `Trollius documentation <http://trollius.readthedocs.org/>`_. + Use aiogreen with asyncio ------------------------- -aiogreen implements the asyncio API, see asyncio documentation: -https://docs.python.org/dev/library/asyncio.html - -eventlet 0.15 supports Python 3 if monkey-patching is not used. - +aiogreen can be used with asyncio, coroutines written with ``yield from ...``. To use aiogreen with asyncio, set the event loop policy before using an event -loop, example:: +loop. Example:: import aiogreen import asyncio @@ -50,7 +49,15 @@ loop, example:: asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy()) # .... -Adding this code should be enough to try examples of the asyncio documentation. +Setting the event loop policy should be enough to examples of the asyncio +documentation with the aiogreen event loop. + +.. warning:: + Since aiogreen relies on eventlet, eventlet port to Python 3 is not complete + and asyncio requires Python 3.3 or newer: using aiogreen with asyncio is not + recommended yet. *Using aiogreen with trollius should be preferred right + now*. See the :ref:`status of the eventlet port to Python 3 + <eventlet-py3>`. Hello World:: @@ -67,6 +74,10 @@ Hello World:: loop.run_forever() loop.close() +.. seealso:: + The `asyncio documentation + <https://docs.python.org/dev/library/asyncio.html>`_. + API === @@ -78,17 +89,44 @@ aiogreen specific functions: Wait for a future (or a task) from a greenthread. Return the result or raise the exception of the future. - Example with asyncio:: + Example of greenthread waiting for a trollius task. The ``progress()`` + callback is called regulary to see that the event loop in not blocked:: + + import aiogreen + import eventlet + import trollius as asyncio + from trollius import From, Return + + def progress(): + print("computation in progress...") + loop.call_later(0.5, progress) + + @asyncio.coroutine + def coro_slow_sum(x, y): + yield From(asyncio.sleep(1.0)) + raise Return(x + y) + + def green_sum(): + task = asyncio.async(coro_slow_sum(1, 2)) - @asyncio.coroutine - def coro_slow_sum(x, y): - yield from asyncio.sleep(1.0) - return x + y + loop.call_soon(progress) - def green_sum(): - task = asyncio.async(coro_slow_sum(1, 2)) - value = aiogreen.link_future(task) - return value + value = aiogreen.link_future(task) + print("1 + 2 = %s" % value) + loop.stop() + + asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy()) + eventlet.spawn(green_sum) + loop = asyncio.get_event_loop() + loop.run_forever() + loop.close() + + Output:: + + computation in progress... + computation in progress... + computation in progress... + 1 + 2 = 3 .. function:: wrap_greenthread(gt) @@ -96,45 +134,93 @@ aiogreen specific functions: The Future object waits for the completion of a greenthread. - Example with asyncio:: + In debug mode, if the greenthread raises an exception, the exception is + logged to ``sys.stderr`` by eventlet, even if the exception is copied to the + Future object. + + Example of trollius coroutine waiting for a greenthread. The ``progress()`` + callback is called regulary to see that the event loop in not blocked:: + + import aiogreen + import eventlet + import trollius as asyncio + from trollius import From, Return + + def progress(): + print("computation in progress...") + loop.call_later(0.5, progress) + + def slow_sum(x, y): + eventlet.sleep(1.0) + return x + y + + @asyncio.coroutine + def coro_sum(): + gt = eventlet.spawn(slow_sum, 1, 2) + + loop.call_soon(progress) + + fut = aiogreen.wrap_greenthread(gt, loop=loop) + result = yield From(fut) + print("1 + 2 = %s" % result) - def slow_sum(x, y): - eventlet.sleep(1.0) - return x + y + asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy()) + loop = asyncio.get_event_loop() + loop.run_until_complete(coro_sum()) + loop.close() - @asyncio.coroutine - def coro_sum(): - gt = eventlet.spawn(slow_sum, 1, 2) - fut = aiogreen.wrap_greenthread(gt, loop=loop) - result = yield from fut - return result + Output:: - .. note:: - If the debug mode of event loop is set, when a greenthread raises an - exception, the exception is logged to ``sys.stderr`` by eventlet, even if - the exception is copied to the Future object as expected. + computation in progress... + computation in progress... + computation in progress... + 1 + 2 = 3 Installation ============ +Install aiogreen with pip +------------------------- + +Type:: + + pip install aiogreen + +Install aiogreen on Windows with pip +------------------------------------ + +Procedure for Python 2.7: + +* If pip is not installed yet, `install pip + <http://www.pip-installer.org/en/latest/installing.html>`_: download + ``get-pip.py`` and type:: + + \Python27\python.exe get-pip.py + +* Install aiogreen with pip:: + + \Python27\python.exe -m pip install aiogreen + +* pip also installs dependencies: ``eventlet`` and ``trollius`` + +Manual installation of aiogreen +------------------------------- + Requirements: - eventlet 0.14 or newer - asyncio or trollius: - * Python 3.4 and newer: asyncio is now part of the stdlib - * Python 3.3: need Tulip 0.4.1 or newer (pip install asyncio), + * Python 3.4 and newer: asyncio is now part of the stdlib (only eventlet is + needed) + * Python 3.3: need Tulip 0.4.1 or newer (``pip install asyncio``), but Tulip 3.4.1 or newer is recommended - * Python 2.6-3.2: need Trollius 0.3 or newer (pip install trollius), + * Python 2.6-3.2: need Trollius 0.3 or newer (``pip install trollius``), but Trollius 1.0 or newer is recommended Type:: - pip install aiogreen - -or:: - python setup.py install @@ -146,9 +232,13 @@ Run tests with tox The `tox project <https://testrun.org/tox/latest/>`_ can be used to build a virtual environment with all runtime and test dependencies and run tests -against different Python versions (2.6, 2.7, 3.2, 3.3). +against different Python versions (2.6, 2.7, 3.2, 3.3, 3.4). + +To test all Python versions, just type:: + + tox -For example, to run tests with Python 2.7, just type:: +To run tests with Python 2.7, type:: tox -e py27 @@ -164,6 +254,6 @@ To run tests against other Python versions: Run tests manually ------------------ -Run the following command from the directory of the aiogreen project:: +Run the following command:: python runtests.py -r |