.. exception:: StopIteration
Raised by built-in function :func:`next` and an :term:`iterator`\'s
- :meth:`__next__` method to signal that there are no further items to be
- produced by the iterator.
- :meth:`~iterator.__next__` method to signal that there are no further values.
++ :meth:`~iterator.__next__` method to signal that there are no further
++ items produced by the iterator.
+ The exception object has a single attribute :attr:`value`, which is
+ given as an argument when constructing the exception, and defaults
+ to :const:`None`.
+
+ When a generator function returns, a new :exc:`StopIteration` instance is
+ raised, and the value returned by the function is used as the
+ :attr:`value` parameter to the constructor of the exception.
+
+ .. versionchanged:: 3.3
+ Added ``value`` attribute and the ability for generator functions to
+ use it to return a value.
.. exception:: SyntaxError
starting at ``0``). If it does not support either of those protocols,
:exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
then *object* must be a callable object. The iterator created in this case
- will call *object* with no arguments for each call to its :meth:`__next__`
- method; if the value returned is equal to *sentinel*, :exc:`StopIteration`
- will be raised, otherwise the value will be returned.
+ will call *object* with no arguments for each call to its
+ :meth:`~iterator.__next__` method; if the value returned is equal to
+ *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
+ be returned.
+ See also :ref:`typeiter`.
+
One useful application of the second form of :func:`iter` is to read lines of
a file until a certain line is reached. The following example reads a file
until the :meth:`readline` method returns an empty string::