Stackless issue python#78: documentation update for iterating over channels

- document, that the sender must notify the receiver of an
end-of-iteration condition by sending a StopIteration exception.
- document the return value of channel.send_sequence()
- issue python#53: document the behaviour of channel.close()
- add another test case to test_chanel.

https://bitbucket.org/stackless-dev/stackless/issues/78
https://bitbucket.org/stackless-dev/stackless/issues/53
(grafted from 38b6cdef017849134ee433c78d6daf168c1c01e2)

Author: Anselm Kruis

Doc/library/stackless/channels.rst

@@ -102,10 +102,20 @@ The ``channel`` class
 .. method:: channel.send_sequence(seq)
 
    Send a stream of values over the channel.  Combined with a generator, this
-   is a very efficient way to build fast pipes.
+   is a very efficient way to build fast pipes. This method returns the length
+   of *seq*. 
+
+   This method is equivalent to::
+
+       def send_sequence(channel, sequence):
+           length = 0
+           for item in sequence:
+               channel.send(item)
+               length += 1
+           return length
 
    Example - sending a sequence over a channel::
-   
+
        >>> def sender(channel):
        ...     channel.send_sequence(sequence)
        ...
@@ -135,11 +145,23 @@ The ``channel`` class
    Channels can work as an iterator.  When they are used in this way, call
    overhead is removed on the receiving side, making it an efficient approach.
 
+   The receiver does not know, if the sender will send further objects
+   or not. Therefore the sender must notify the receiver about the
+   end-of-iteration condition. Currently this requires sending a
+   :exc:`StopIteration` over the channel (i.e. by
+   calling ``channel.send_exception(StopIteration)``).
+
+   .. note::
+
+      A future version of Stackless may send a :exc:`StopIteration` automatically,
+      if you close the channel.
+   
    Example - iterating over a channel::
    
        >>> def sender(channel):
        ...     for value in sequence:
        ...         channel.send(value)
+       ...     channel.send_exception(StopIteration)
        ...
        >>> def receiver(channel):
        ...     for value in channel:
@@ -159,6 +181,27 @@ The ``channel`` class
        2
        3       
 
+   Of course you can combine :meth:`send_sequence` with iterating over a channel::
+   
+      >>> def sender(channel, sequence):
+      ...     channel.send_sequence(sequence)
+      ...     channel.send_exception(StopIteration)
+      ...
+      >>> def receiver(channel):
+      ...     for value in channel:
+      ...         print value
+      ...
+      >>> c = stackless.channel()
+      >>> stackless.tasklet(sender)(c, range(4))
+      <_stackless.tasklet object at 0x0244E0E8>
+      >>> stackless.tasklet(receiver)(c)
+      <_stackless.tasklet object at 0x0244E140>
+      >>> stackless.run()
+      0
+      1
+      2
+      3
+
 .. method:: channel.next()
 
    Part of the :ref:`iteration protocol <typeiter>`.  Either returns the next value, or raises

Stackless/changelog.txt

@@ -10,6 +10,11 @@ What's New in Stackless 3.X.X?
 
 *Release date: 20XX-XX-XX*
 
+- https://bitbucket.org/stackless-dev/stackless/issues/78
+  Documentation update: if you iterate over a channel, the
+  sender must send StopIteration manually. See
+  http://stackless.readthedocs.io/en/latest/library/stackless/channels.html#channel.__iter__
+
 - https://bitbucket.org/stackless-dev/stackless/issue/83
   Fix demo/tracing.py: don't use flextype features. Unfortunately
   it is no longer possible to change the __repr__ method of class tasklet.

Stackless/unittests/test_channel.py

@@ -240,6 +240,7 @@ def setUp(self):
         self.c = stackless.channel()
 
     # TODO: This test shows how ill conceived the current closing/closed semantics are.
+    # See https://bitbucket.org/stackless-dev/stackless/issues/53
     def testSequence(self):
         def sender():
             self.c.send_sequence(range(10))
@@ -264,6 +265,28 @@ def receiver():
         self.assertEqual(data, list(range(11)))
         self.assertTrue(self.c.closed)
 
+    def testSequence2(self):
+        def sender():
+            length = self.c.send_sequence(range(10))
+            self.assertEqual(length, 10)
+            # A future version of Stackless may send StopIteration
+            # automatically, if you close the channel
+            # See https://bitbucket.org/stackless-dev/stackless/issues/53
+            self.c.send_exception(StopIteration)
+            self.c.close()
+
+        data = []
+
+        def receiver():
+            for i in self.c:
+                data.append(i)
+
+        stackless.tasklet(sender)()
+        stackless.tasklet(receiver)()
+        stackless.run()
+        self.assertEqual(data, list(range(10)))
+        self.assertTrue(self.c.closed)
+
     def testSender(self):
         self.c.close()
         self.assertRaises(ValueError, self.c.send, None)