diff options
author | Victor Stinner <victor.stinner@gmail.com> | 2014-11-21 13:39:49 +0100 |
---|---|---|
committer | Victor Stinner <victor.stinner@gmail.com> | 2014-11-21 13:39:49 +0100 |
commit | 4a0496fb5b9c95a1d265fcb64e94c25c4f877c51 (patch) | |
tree | 2216d914349eda9bfd6ca1e9e0b4c171ad96ac68 | |
parent | 44badca2e4bdc2fefac1049ba9a524a02b1f6e10 (diff) | |
download | aioeventlet-4a0496fb5b9c95a1d265fcb64e94c25c4f877c51.tar.gz |
documentation
-rw-r--r-- | README | 20 | ||||
-rw-r--r-- | doc/index.rst | 9 | ||||
-rw-r--r-- | doc/openstack.rst | 17 | ||||
-rw-r--r-- | doc/status.rst | 48 | ||||
-rw-r--r-- | doc/using.rst | 176 |
5 files changed, 186 insertions, 84 deletions
@@ -1,29 +1,17 @@ -aiogreen implements the asyncio API (PEP 3156) on top of eventet. It makes +aiogreen implements the asyncio API (PEP 3156) on top of eventlet. It makes possible to write asyncio code in a project currently written for eventlet. aiogreen allows to use greenthreads in asyncio coroutines, and to use asyncio coroutines, tasks and futures in greenthreads: see ``link_future()`` and ``wrap_greenthread()`` functions. -The main visible difference between trollius and aiogreen is that +The main visible difference between aiogreen and trollius is the behaviour of ``run_forever()``: ``run_forever()`` blocks with trollius, whereas it runs in a -greenthread with aiogreen. It means that it's possible to call -``run_forever()`` in the main thread and execute other greenthreads in -parallel. - -aiogreen: +greenthread with aiogreen. It means that aiogreen event loop can run in an +greenthread while the Python main thread runs other greenthreads in parallel. * `aiogreen documentation <http://aiogreen.readthedocs.org/>`_ * `aiogreen project in the Python Cheeseshop (PyPI) <https://pypi.python.org/pypi/aiogreen>`_ * `aiogreen project at Bitbucket <https://bitbucket.org/haypo/aiogreen>`_ * Copyright/license: Open source, Apache 2.0. Enjoy! - -Event loops: - -* `asyncio documentation <http://docs.python.org/dev/library/asyncio.html>`_ -* `trollus documentation <http://trollius.readthedocs.org/>`_ -* `eventlet documentation <http://eventlet.net/doc/>`_ -* `eventlet project <http://eventlet.net/>`_ -* `greenlet documentation <http://greenlet.readthedocs.org/>`_ -* `Tulip project <http://code.google.com/p/tulip/>`_ diff --git a/doc/index.rst b/doc/index.rst index b135d71..280f895 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -7,18 +7,17 @@ aiogreen :target: https://www.flickr.com/photos/haypo/7181768969/in/set-72157629731066236 aiogreen implements the asyncio API (`PEP 3156 -<http://www.python.org/dev/peps/pep-3156/>`_) on top of eventet. It makes +<http://www.python.org/dev/peps/pep-3156/>`_) on top of eventlet. It makes possible to write asyncio code in a project currently written for eventlet. aiogreen allows to use greenthreads in asyncio coroutines, and to use asyncio coroutines, tasks and futures in greenthreads: see :func:`link_future` and :func:`wrap_greenthread` functions. -The main visible difference between trollius and aiogreen is that +The main visible difference between aiogreen and trollius is the behaviour of ``run_forever()``: ``run_forever()`` blocks with trollius, whereas it runs in a -greenthread with aiogreen. It means that it's possible to call -``run_forever()`` in the main thread and execute other greenthreads in -parallel. +greenthread with aiogreen. It means that aiogreen event loop can run in an +greenthread while the Python main thread runs other greenthreads in parallel. * `aiogreen documentation <http://aiogreen.readthedocs.org/>`_ * `aiogreen project in the Python Cheeseshop (PyPI) diff --git a/doc/openstack.rst b/doc/openstack.rst index 2cae95d..c390227 100644 --- a/doc/openstack.rst +++ b/doc/openstack.rst @@ -114,6 +114,20 @@ Maybe the good one, aiogreen project: * November 19, 2014: First release of the aiogreen project +OpenStack Kilo Summit, November 3-7, 2014, at Paris: + +* `Python 3 in Oslo <https://etherpad.openstack.org/p/kilo-oslo-python-3>`_: + + * add a new greenio executor to Oslo Messaging + * port eventlet to Python 3 (with monkey-patching): see the :ref:`status of + the eventlet port to Python 3 <eventlet-py3>` + +* `What should we do about oslo.messaging? + <https://etherpad.openstack.org/p/kilo-oslo-oslo.messaging>`_: add the new + greenio executor + +* `Python 3.4 transition <https://etherpad.openstack.org/p/py34-transition>`_ + New try with a greenio executor for Oslo Messaging: * July 29, 2014: Doug Hellmann proposed the blueprint @@ -137,6 +151,9 @@ First try with a trollius executor for Oslo Messaging: * Jun 20, 2014: Patch `Add an optional timeout parameter to Listener.poll <https://review.openstack.org/#/c/71003/>`_ merged into Oslo Messaging +* May 28, 2014: Meeting at OpenStack in action with Doug Hellman, Julien + Danjou, Mehdi Abaakouk, Victor Stinner and Christophe to discuss the plan to + port OpenStack to Python 3 and switch from eventlet to asyncio. * April 23, 2014: Patch `Allow trollius 0.2 <https://review.openstack.org/#/c/79901/>`_ merged into openstack/requirements diff --git a/doc/status.rst b/doc/status.rst index e894b79..e098b9f 100644 --- a/doc/status.rst +++ b/doc/status.rst @@ -13,24 +13,26 @@ Methods: * stop() * coroutines and tasks -Tests of aiogreen 0.1: +aiogreen 0.1 was tested: -* Tested on Python 2.7, 3.3 and 3.5 -* Tested on Linux and Windows -* Tested with Trollius 1.0, 1.0.1 and 1.0.2 -* Tested with asyncio 0.4.1 and 3.4.2 +* on Python 2.7, 3.3 and 3.5 +* on Linux and Windows +* with Trollius 1.0, 1.0.1 and 1.0.2 +* with asyncio 0.4.1 and 3.4.2 To do (Not supported) ===================== +* wrap_greenthread() must not log the exception to sys.stderr if the + greenthread didn't start * run an event loop in a thread different than the main thread * sockets: create_server, sock_recv * pipes: connect_read_pipe * subprocesses: need pipes * signal handlers: add_signal_handler (only for pyevent hub?) -* tox.ini: add py33_patch. eventlet with Python 3 and monkey-patch causes - an issue in importlib. +* tox.ini: test Python 3.3 with monkey-patching, see eventlet bug: + https://github.com/eventlet/eventlet/pull/168 eventlet issues @@ -47,23 +49,29 @@ eventlet issues available on Windows. +.. _eventlet-py3: + eventlet and Python 3 ===================== -Issues: - -* https://github.com/eventlet/eventlet/issues/6 (root py3 issue) -* https://github.com/eventlet/eventlet/issues/157 (py3 related?) -* https://github.com/eventlet/eventlet/issues/153 (py3 related?) +eventlet 0.15 is the first release supporting Python 3. Python 3 is only +supported if monkey-patching is not used. -Pull requests: +Python 3 pull requests: -* https://github.com/eventlet/eventlet/pull/99 : complete monkey-patching -* => commit: https://github.com/therve/eventlet/commit/9c3118162cf1ca1e50be330ba2a289f054c48d3c -* https://github.com/eventlet/eventlet/pull/160 (py3 related?) +* Pull request #160: `Python 3 compat; Improve WSGI, WS, threading and tests + <https://github.com/eventlet/eventlet/pull/160>`_ (sent the Nov 5, 2014): not + merged yet +* Pull request #99, `Fix several issues with python3 thread patching + <https://github.com/eventlet/eventlet/pull/99>`_ (sent the July 3, 2014): not + merged yet, see the `commit + <https://github.com/therve/eventlet/commit/9c3118162cf1ca1e50be330ba2a289f054c48d3c>`_ -OpenStack Kilo Summit: +Python 3 issues: -* https://etherpad.openstack.org/p/kilo-oslo-python-3 -* https://etherpad.openstack.org/p/kilo-oslo-oslo.messaging -* https://etherpad.openstack.org/p/py34-transition (tangentially related) +* Issue #157: `eventlet hanging + <https://github.com/eventlet/eventlet/issues/157>`_ (open since Oct 30, 2014) +* Issue #153: `py3: green.threading.local is not green + <https://github.com/eventlet/eventlet/issues/153>`_ (closed the Nov 5, 2014) +* Issue #6: `Support Python 3.3 + <https://github.com/eventlet/eventlet/issues/6>`_ (open since Jan 2013) 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 |