From 7f314ed71b29c83bbfce6f11d9a7b3e42b78bf38 Mon Sep 17 00:00:00 2001
From: Victor Stinner <victor.stinner@gmail.com>
Date: Wed, 15 Oct 2014 18:49:16 +0200
Subject: [PATCH] asyncio doc: write simpler examples to introduce asyncio

---
 Doc/library/asyncio-eventloop.rst | 61 +++++++++++++++++++++++++------
 Doc/library/asyncio-task.rst      | 58 ++++++++++++++++++++++-------
 2 files changed, 94 insertions(+), 25 deletions(-)

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 800fae236f1..072d0013183 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -649,24 +649,27 @@ Event loop examples
 
 .. _asyncio-hello-world-callback:
 
-Hello World with a callback
----------------------------
+Hello World with call_soon()
+----------------------------
 
-Print ``"Hello World"`` every two seconds using a callback scheduled by the
-:meth:`BaseEventLoop.call_soon` method::
+Example using the :meth:`BaseEventLoop.call_soon` method to schedule a
+callback. The callback displays ``"Hello World"`` and then stops the event
+loop::
 
     import asyncio
 
-    def print_and_repeat(loop):
+    def hello_world(loop):
         print('Hello World')
-        loop.call_later(2, print_and_repeat, loop)
+        loop.stop()
 
     loop = asyncio.get_event_loop()
-    loop.call_soon(print_and_repeat, loop)
-    try:
-        loop.run_forever()
-    finally:
-        loop.close()
+
+    # Schedule a call to hello_world()
+    loop.call_soon(hello_world, loop)
+
+    # Blocking call interrupted by loop.stop()
+    loop.run_forever()
+    loop.close()
 
 .. seealso::
 
@@ -674,6 +677,42 @@ Print ``"Hello World"`` every two seconds using a callback scheduled by the
    uses a :ref:`coroutine <coroutine>`.
 
 
+.. _asyncio-date-callback:
+
+Display the current date with call_later()
+------------------------------------------
+
+Example of callback displaying the current date every second. The callback uses
+the :meth:`BaseEventLoop.call_later` method to reschedule itself during 5
+seconds, and then stops the event loop::
+
+    import asyncio
+    import datetime
+
+    def display_date(end_time, loop):
+        print(datetime.datetime.now())
+        if (loop.time() + 1.0) < end_time:
+            loop.call_later(1, display_date, end_time, loop)
+        else:
+            loop.stop()
+
+    loop = asyncio.get_event_loop()
+
+    # Schedule the first call to display_date()
+    end_time = loop.time() + 5.0
+    loop.call_soon(display_date, end_time, loop)
+
+    # Blocking call interrupted by loop.stop()
+    loop.run_forever()
+    loop.close()
+
+.. seealso::
+
+   The :ref:`coroutine displaying the current date
+   <asyncio-date-coroutine>` example uses a :ref:`coroutine
+   <coroutine>`.
+
+
 .. _asyncio-watch-read-event:
 
 Watch a file descriptor for read events
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index fa95ca98040..21c4e339f57 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -77,30 +77,60 @@ Coroutines (and tasks) can only run when the event loop is running.
 
 .. _asyncio-hello-world-coroutine:
 
-Example: "Hello World" coroutine
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Example: Hello World coroutine
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Print ``"Hello World"`` every two seconds using a coroutine::
+Example of coroutine displaying ``"Hello World"``::
 
     import asyncio
 
     @asyncio.coroutine
-    def greet_every_two_seconds():
-        while True:
-            print('Hello World')
-            yield from asyncio.sleep(2)
+    def hello_world():
+        print("Hello World!")
 
     loop = asyncio.get_event_loop()
-    try:
-        loop.run_until_complete(greet_every_two_seconds())
-    finally:
-        loop.close()
+    # Blocking call which returns when the hello_world() coroutine is done
+    loop.run_until_complete(hello_world())
+    loop.close()
 
 .. seealso::
 
-   The :ref:`Hello World with a callback <asyncio-hello-world-callback>`
-   example uses a callback scheduled by the :meth:`BaseEventLoop.call_soon`
-   method.
+   The :ref:`Hello World with call_soon() <asyncio-hello-world-callback>`
+   example uses the :meth:`BaseEventLoop.call_soon` method to schedule a
+   callback.
+
+
+.. _asyncio-date-coroutine:
+
+Example: Coroutine displaying the current date
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example of coroutine displaying the current date every second during 5 seconds
+using the :meth:`sleep` function::
+
+    import asyncio
+    import datetime
+
+    @asyncio.coroutine
+    def display_date(loop):
+        end_time = loop.time() + 5.0
+        while True:
+            print(datetime.datetime.now())
+            if (loop.time() + 1.0) >= end_time:
+                break
+            yield from asyncio.sleep(1)
+
+    loop = asyncio.get_event_loop()
+    # Blocking call which returns when the display_date() coroutine is done
+    loop.run_until_complete(display_date(loop))
+    loop.close()
+
+.. seealso::
+
+   The :ref:`display the current date with call_later()
+   <asyncio-date-callback>` example uses a callback with the
+   :meth:`BaseEventLoop.call_later` method.
+
 
 Example: Chain coroutines
 ^^^^^^^^^^^^^^^^^^^^^^^^^