updated from atlas

Author: ramalho

control/coroaverager0.py

@@ -4,7 +4,6 @@
 
     >>> coro_avg = averager()  # <1>
     >>> next(coro_avg)  # <2>
-    0.0
     >>> coro_avg.send(10)  # <3>
     10.0
     >>> coro_avg.send(30)
@@ -15,8 +14,9 @@
 """
 
 def averager():
-    total = average = 0.0
+    total = 0.0
     count = 0
+    average = None
     while True:
         term = yield average  # <4>
         total += term

control/coroaverager1.py

@@ -19,8 +19,9 @@
 
 @coroutine  # <5>
 def averager():  # <6>
-    total = average = 0.0
+    total = 0.0
     count = 0
+    average = None
     while True:
         term = yield average
         total += term

control/coroaverager2.py

@@ -1,31 +1,61 @@
 """
-A coroutine to compute a running average
-
-    >>> coro_avg = averager()  # <1>
-    >>> from inspect import getgeneratorstate
-    >>> getgeneratorstate(coro_avg)  # <2>
-    'GEN_SUSPENDED'
-    >>> coro_avg.send(10)  # <3>
-    10.0
+A coroutine to compute a running average.
+
+Testing ``averager`` by itself::
+
+# BEGIN RETURNING_AVERAGER_DEMO1
+
+    >>> coro_avg = averager()
+    >>> next(coro_avg)  # <1>
+    >>> coro_avg.send(10)
     >>> coro_avg.send(30)
-    20.0
-    >>> coro_avg.send(5)
-    15.0
+    >>> coro_avg.send(6.5)
+    >>> coro_avg.send(None)  # <2>
+    Traceback (most recent call last):
+       ...
+    StopIteration: Result(count=3, average=15.5)
+
+# END RETURNING_AVERAGER_DEMO1
+
+Catching `StopIteration` to extract the value returned by
+the coroutine::
+
+# BEGIN RETURNING_AVERAGER_DEMO2
+
+    >>> coro_avg = averager()
+    >>> next(coro_avg)
+    >>> coro_avg.send(10)
+    >>> coro_avg.send(30)
+    >>> coro_avg.send(6.5)
+    >>> try:
+    ...     coro_avg.send(None)
+    ... except StopIteration as exc:
+    ...     result = exc.value
+    ...
+    >>> result
+    Result(count=3, average=15.5)
+
+# END RETURNING_AVERAGER_DEMO2
+
 
 """
 
+# BEGIN RETURNING_AVERAGER
 from collections import namedtuple
 
-Result = namedtuple('Result', 'count total average')
+Result = namedtuple('Result', 'count average')
+
 
-def averager():  # <6>
-    total = average = 0.0
+def averager():
+    total = 0.0
     count = 0
-    try:
-        while True:
-            term = yield average
-            total += term
-            count += 1
-            average = total/count
-    finally:
-        return Result(count, total, average)
+    average = None
+    while True:
+        term = yield
+        if term is None:
+            break  # <1>
+        total += term
+        count += 1
+        average = total/count
+    return Result(count, average)  # <2>
+# END RETURNING_AVERAGER

control/simulation/taxi_sim.py

@@ -57,7 +57,7 @@ def taxi_process(ident, trips, start_time=0):  # <1>
         time = yield Event(trip_ends, ident, 'drop off passenger')  # <7>
 
     yield Event(time + 1, ident, 'going home')  # <8>
-    # <9>
+    # end of taxi process # <9>
 # END TAXI_PROCESS
 
 # BEGIN TAXI_SIMULATOR