[Python-checkins] cpython (3.4): asyncio doc: write simpler examples to introduce asyncio

[victor.stinner]

https://hg.python.org/cpython/rev/52d4dde01a10
changeset:   93077:52d4dde01a10
branch:      3.4
parent:      93075:2a25076c50ad
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Wed Oct 15 18:49:16 2014 +0200
summary:
  asyncio doc: write simpler examples to introduce asyncio

files:
  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
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -649,24 +649,27 @@
 
 .. _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 @@
    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
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -77,30 +77,60 @@
 
 .. _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
 ^^^^^^^^^^^^^^^^^^^^^^^^^

-- 
Repository URL: https://hg.python.org/cpython