[Python-checkins] peps: Add more words to GeneratorReturn alternative.

[guido.van.rossum]

https://hg.python.org/peps/rev/d71f1c9cd084
changeset:   5599:d71f1c9cd084
user:        Guido van Rossum <guido at python.org>
date:        Mon Nov 17 12:15:42 2014 -0800
summary:
  Add more words to GeneratorReturn alternative.

files:
  pep-0479.txt |  27 +++++++++++++++++++++------
  1 files changed, 21 insertions(+), 6 deletions(-)


diff --git a/pep-0479.txt b/pep-0479.txt
--- a/pep-0479.txt
+++ b/pep-0479.txt
@@ -129,8 +129,18 @@
 For certain situations, a simpler and fully backward-compatible
 solution may be sufficient: when a generator returns, instead of
 raising ``StopIteration``, it raises a specific subclass of
-``StopIteration`` which can then be detected.  If it is not that
-subclass, it is an escaping exception rather than a return statement.
+``StopIteration`` (``GeneratorReturn``) which can then be detected.
+If it is not that subclass, it is an escaping exception rather than a
+return statement.
+
+The inspiration for this alternative proposal was Nick's observation
+[7]_ that if an ``asyncio`` coroutine [8]_ accidentally raises
+``StopIteration``, it currently terminates silently, which may present
+a hard-to-debug mystery to the developer.  The main proposal turns
+such accidents in clearly distinguishable ``RuntimeError`` exceptions,
+but if that is rejected, this alternate proposal would enable
+``asyncio`` to distinguish between a ``return`` statement and an
+accidentally-raised ``StopIteration`` exception.
 
 Of the three outcomes listed above:
 
@@ -144,10 +154,10 @@
 exception in its ``__cause__``.  If uncaught, this would clearly show
 the chaining of exceptions.
 
-This alternative does *not* affect the discrepancy between generator expressions
-and list comprehensions, but allows generator-aware code (such as the
-contextlib and asyncio modules) to reliably differentiate between the
-second and third outcomes listed above.
+This alternative does *not* affect the discrepancy between generator
+expressions and list comprehensions, but allows generator-aware code
+(such as the ``contextlib`` and ``asyncio`` modules) to reliably
+differentiate between the second and third outcomes listed above.
 
 However, once code exists that depends on this distinction between
 ``GeneratorReturn`` and ``StopIteration``, a generator that invokes
@@ -186,6 +196,11 @@
 .. [6] wrap unbounded generator to restrict its output
    (http://code.activestate.com/recipes/66427-wrap-unbounded-generator-to-restrict-its-output/)
 
+.. [7] Post from Nick Coghlan mentioning asyncio
+   (https://mail.python.org/pipermail/python-ideas/2014-November/029961.html)
+
+.. [8] Coroutines in asyncio
+   (https://docs.python.org/3/library/asyncio-task.html#coroutines)
 
 Copyright
 =========

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