[Python-checkins] peps: More clarifications in response to Oscar Benjamin.

[guido.van.rossum]

https://hg.python.org/peps/rev/15988b36b9d9
changeset:   5644:15988b36b9d9
user:        Guido van Rossum <guido at python.org>
date:        Thu Dec 11 11:02:14 2014 -0800
summary:
  More clarifications in response to Oscar Benjamin.

files:
  pep-0479.txt |  28 ++++++++++++++++++++++++----
  1 files changed, 24 insertions(+), 4 deletions(-)


diff --git a/pep-0479.txt b/pep-0479.txt
--- a/pep-0479.txt
+++ b/pep-0479.txt
@@ -43,13 +43,16 @@
 somewhat surprising, and can conceal obscure bugs.  An unexpected
 exception should not result in subtly altered behaviour, but should
 cause a noisy and easily-debugged traceback.  Currently,
-``StopIteration`` can be absorbed by the generator construct.
+``StopIteration`` raised accidentally inside a generator function will
+be interpreted as the end of the iteration by the loop construct
+driving the generator.
 
 The main goal of the proposal is to ease debugging in the situation
 where an unguarded ``next()`` call (perhaps several stack frames deep)
 raises ``StopIteration`` and causes the iteration controlled by the
-generator to terminate silently.  (When another exception is raised, a
-traceback is printed pinpointing the cause of the problem.)
+generator to terminate silently.  (Whereas, when some other exception
+is raised, a traceback is printed pinpointing the cause of the
+problem.)
 
 This is particularly pernicious in combination with the ``yield from``
 construct of PEP 380 [1]_, as it breaks the abstraction that a
@@ -352,7 +355,9 @@
 iterators are generators.  Generators have additional methods that
 iterators don't have, like ``send`` and ``throw``.  All this is
 unchanged.  Nothing changes for generator users -- only authors of
-generator functions may have to learn something new.
+generator functions may have to learn something new.  (This includes
+authors of generator expressions that depend on early termination of
+the iteration by a ``StopIteration`` raised in a condition.)
 
 An iterator is an object with a ``__next__`` method.  Like many other
 special methods, it may either return a value, or raise a specific
@@ -489,6 +494,10 @@
 (Using a dedicated exception type, perhaps subclassing ``ValueError``,
 would help this; however, all code would still need to be rewritten.)
 
+Note that calling ``next(it, default)`` catches ``StopIteration`` and
+substitutes the given default value; this feature is often useful to
+avoid a ``try/except`` block.
+
 
 Sub-proposal: decorator to explicitly request current behaviour
 ---------------------------------------------------------------
@@ -556,6 +565,17 @@
 ``RuntimeError``; the fact that they cannot should not preclude
 generators from doing so.
 
+Why not fix all __next__() methods?
+-----------------------------------
+
+When implementing a regular ``__next__()`` method, the only way to
+indicate the end of the iteration is to raise ``StopIteration``.  So
+catching ``StopIteration`` here and converting it to ``RuntimeError``
+would defeat the purpose.  This is a reminder of the special status of
+generator functions: in a generator function, raising
+``StopIteration`` is redundant since the iteration can be terminated
+by a simple ``return``.
+
 
 References
 ==========

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