Make PyIter_Next() a little smarter (wrt its knowledge of iterator

internals) so clients can be a lot dumber (wrt their knowledge).

pep-0234.txt

@@ -43,10 +43,11 @@ C API Specification
     Another new slot, named tp_iternext, is added to the type
     structure, for obtaining the next value in the iteration.  To use
     this slot, a new C API function PyIter_Next() is added.  The
-    signature for both the slot and the API function is as follows:
-    the argument is a PyObject * and so is the return value.  When the
-    return value is non-NULL, it is the next value in the iteration.
-    When it is NULL, there are three possibilities:
+    signature for both the slot and the API function is as follows,
+    although the NULL return conditions differ:  the argument is a
+    PyObject * and so is the return value.  When the return value is
+    non-NULL, it is the next value in the iteration.  When it is NULL,
+    then for the tp_iternext slot there are three possibilities:
 
     - No exception is set; this implies the end of the iteration.
 
@@ -56,6 +57,15 @@ C API Specification
     - Some other exception is set; this means that an error occurred
       that should be propagated normally.
 
+    The higher-level PyIter_Next() function clears the StopIteration
+    exception (or derived exception) when it occurs, so its NULL return
+    conditions are simpler:
+
+    - No exception is set; this means iteration has ended.
+
+    - Some exception is set; this means an error occurred, and should
+      be propagated normally.
+
     In addition to the tp_iternext slot, every iterator object must
     also implement a next() method, callable without arguments.  This
     should have the same semantics as the tp_iternext slot function,