documentation

5 files changed, 186 insertions, 84 deletions

diff --git a/README b/README
index e128531..7e71364 100644
--- a/README
+++ b/README
@@ -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