From 6be69c3f9c7d809ee111054a5116567696480a32 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 21 Nov 2014 04:47:18 +0100 Subject: convert README to a sphinx documentation --- README | 318 +++++------------------------------------------------------------ 1 file changed, 22 insertions(+), 296 deletions(-) (limited to 'README') diff --git a/README b/README index 400d02c..19eda9b 100644 --- a/README +++ b/README @@ -1,296 +1,22 @@ -asyncio event loop implemented on top of eventlet. - -* Trollius project: http://trollius.readthedocs.org/ -* aiogreen at PyPI: https://pypi.python.org/pypi/aiogreen - - -Usage -===== - -Use aiogreen with asyncio -------------------------- - -aiogreen implements the asyncio API, see asyncio documentation: -https://docs.python.org/dev/library/asyncio.html - -To use aiogreen with asyncio, set the event loop policy before using an event -loop, example:: - - import aiogreen - import asyncio - - asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy()) - # .... - -Adding this code should be enough to try examples of the asyncio documentation. - -Hello World:: - - import aiogreen - import asyncio - - def hello_world(): - print("Hello World") - loop.stop() - - asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy()) - loop = asyncio.get_event_loop() - loop.call_soon(hello_world) - loop.run_forever() - loop.close() - - -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/ - -To use aiogreen with trollius, set the event loop policy before using an event -loop, example:: - - import aiogreen - import trollius - - trollius.set_event_loop_policy(aiogreen.EventLoopPolicy()) - # .... - -Hello World:: - - import aiogreen - import trollius as asyncio - - def hello_world(): - print("Hello World") - loop.stop() - - asyncio.set_event_loop_policy(aiogreen.EventLoopPolicy()) - loop = asyncio.get_event_loop() - loop.call_soon(hello_world) - loop.run_forever() - loop.close() - - -Use a greenthread in a coroutine --------------------------------- - -Use the ``wrap_greenthread(gt)`` function to wrap a greenthread into a Future -object. The Future object waits for the completion of a greenthread. - -Example with asyncio:: - - def slow_sum(x, y): - eventlet.sleep(1.0) - return x + y - - @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 - -Note: In debug mode, when a greenthread raises an exception, the exception is -logged to sys.stderr by eventlet, even if it is correctly copied to the Future -object. - - -Use a coroutine in a greenthread --------------------------------- - -Use the ``link_future(future)`` function to wait for a future or a task from a -greenthread. The function returns the result or raise the exception of the -future. - -Example with asyncio:: - - def coro_slow_sum(x, y): - yield from asyncio.sleep(1.0) - return x + y - - def green_sum(): - task = asyncio.async(coro_slow_sum(1, 2)) - value = aiogreen.link_future(task) - return value - - -API -=== - -Functions which are not in asyncio: - -* ``link_future(future)``: wait for a future (or a task) from a greenthread, - return the result or raise the exception of the future -* ``wrap_greenthread(gt)``: wrap a greenthread into a Future object - - -Installation -============ - -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), - but Tulip 3.4.1 or newer is recommended - * 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 - - -Run tests -========= - -Run tests with tox ------------------- - -The `tox project `_ 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). - -For example, to run tests with Python 2.7, just type:: - - tox -e py27 - -To run tests against other Python versions: - -* ``py26``: Python 2.6 -* ``py27``: Python 2.7 -* ``py27_patch``: Python 2.7 with eventlet monkey patching -* ``py32``: Python 3.2 -* ``py33``: Python 3.3 -* ``py34``: Python 3.4 - -Run tests manually ------------------- - -Run the following command from the directory of the aiogreen project: - - python runtests.py -r - - -Changelog -========= - -Version 0.2 (development version) ---------------------------------- - -The core of the event loop was rewritten to fits better in asyncio and -eventlet. aiogreen now reuses more code from asyncio/trollius. The code -handling file descriptors was also fixed to respect asyncio contract: -only call the callback once per loop iteration. - -Changes: - -* Add the ``link_future(future)`` function: wait for a future from a - greenthread. -* Add the ``wrap_greenthread(gt)`` function: wrap a greenthread into a Future -* Support also eventlet 0.14, not only eventlet 0.15 or newer -* Support eventlet with monkey-patching -* Rewrite the code handling file descriptors to ensure that the listener is - only called once per loop iteration, to respect asyncio specification. -* Simplify the loop iteration: remove custom code to reuse instead the - asyncio/trollius code (_run_once) -* Reuse call_soon, call_soon_threadsafe, call_at, call_later from - asyncio/trollius, remove custom code -* sock_connect() is now asynchronous -* Add a suite of automated unit tests -* Fix EventLoop.stop(): don't stop immediatly, but schedule stopping the event - loop with call_soon() -* Add tox.ini to run tests with tox -* Setting debug mode of the event loop doesn't enable "debug_blocking" of - eventlet on Windows anymore, the feature is not implemented on Windows - in eventlet. -* add_reader() and add_writer() now cancels the previous handle and sets - a new handle -* In debug mode, detect calls to call_soon() from greenthreads which are not - threadsafe (would not wake up the event loop). -* Only set "debug_exceptions" of the eventlet hub when the debug mode of the - event loop is enabled. - -2014-11-19: version 0.1 ------------------------ - -* First public release - - -Implemented -=========== - -Methods: - -* call_at() -* call_later() -* call_soon() -* run_forever() -* run_in_executor() -* run_until_complete() -* create_connection(): TCP client -* stop() -* coroutines and tasks - -Tests of aiogreen 0.1: - -* 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 - - -To do (Not supported) -===================== - -* add_reader() does only support one callback per file descriptor currently. -* 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. - - -eventlet issues -=============== - -* eventlet monkey patching on Python 3 is incomplete. The most blocking issue - is in the importlib: the thread module is patched to use greenthreads, but - importlib really need to work on real threads. Pull request: - https://github.com/eventlet/eventlet/pull/168 -* eventlet.tpool.setup() seems to be broken on Windows in eventlet 0.15. - Pull request: - https://github.com/eventlet/eventlet/pull/167 -* hub.debug_blocking is implemented with signal.alarm() which is is not - available on Windows. - - -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?) - -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?) - -OpenStack Kilo Summit: - -* 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) +aiogreen implements the asyncio API on top of eventet. 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 +``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 documentation `_ +* `asyncio documentation `_ +* `trollus documentation `_ +* `aiogreen project in the Python Cheeseshop (PyPI) + `_ +* `aiogreen project at Bitbucket `_ +* Copyright/license: Open source, Apache 2.0. Enjoy! + +See also the `Tulip project `_. -- cgit v1.2.1